ObjectStore Management
Chapter 2
Server Parameters
This chapter describes Server parameters, which determine some aspects of how the ObjectStore Server functions. There are defaults for all parameters. You do not need to do anything to use the defaults.
To modify a parameter, seem the instructions in the chapter for your operating system. After you modify a Server parameter you must shut down and restart the Server for the change to take effect.
Parameters are available on all platforms unless otherwise noted. Case is not significant. Defaults are in the left margin.
The parameters described in this chapter are
Admin Host List
Default: none
The Admin Host List parameter specifies the pathname of a file. This file must contain a set of primary names of hosts, one per line. (If DNS is in use, they must be fully qualified domain names.) The hosts listed in this file are the hosts on which an administrative user, designated with the Admin User parameter, can perform ObjectStore Server operations.
When this parameter is not set, an administrative user can perform ObjectStore Server operations on any ObjectStore host.
When you specify a host in the file pointed to by the Admin Host List parameter, it causes that host to require only SYS authentication. This is true regardless of that host's setting of the Authentication Required Server parameter.
When you create an administrative hosts list, and you also have a host access list set with the Host Access List Server parameter, ObjectStore adds all hosts in the administrative hosts list to the host access list.
Admin User
Default: none
When Admin User is set to a user name, it allows that user to run any ObjectStore utility without having root permission. When this parameter is not set, you must have root permission to run ObjectStore utilities, for example, ossvrshtd and ossvrclntkill.
When you set this parameter, you designate a user who does not have root privileges to perform ObjectStore administrative functions. This administrative user can execute any ObjectStore utility that a user with root permission can, except for operating on file databases. File databases are not affected when the Admin User parameter is set.
When a utility operates on rawfs databases, administrative users are not restricted by access control. They can access any database and perform any operation even though they are operating under their own user names and groups.
When a utility operates on file databases, administrative users have the same restrictions they normally have. Being an administrative user does not give them additional privileges.
Allow NFS Locks
Default: yes
When the Allow NFS Locks parameter is set to yes (the default), the Server can perform database-level locking. If database-level locking is on, when an ObjectStore Server handles access to a remote (or local) database, it holds a lock on the database as long as the database is open. If the database is open for read-only, the Server holds a read lock; if the database is open for read/write, the Server holds a write lock.
When an ObjectStore Server holds a read lock on a database, this prevents other Servers from acquiring a write lock on the database. Read access by other Servers is allowed. A read lock does not prevent write access by another application if the same Server handles the access.
When an ObjectStore Server holds a write lock on a database, this prevents other Servers from acquiring either a read lock or a write lock on the database. Again, this does not prevent access by another application if the same ObjectStore Server handles the access.
If a Server is blocked from acquiring a lock, ObjectStore signals the exception err_database_lock_conflict. Access is not automatically retried.
Caution
You can turn off database-level locking by setting the Server parameter Allow NFS Locks to No. You must use extreme caution if you turn off locking. Concurrent database access by different Servers can corrupt the database. Note that a mistake in the contents of a locator file could cause unintentional concurrent access of this sort.
Windows and OS/2
File locking is always turned on.
Allow Remote Database Access
Default: no
The Allow Remote Database Access parameter determines whether the Server can handle access to remote databases. If ObjectStore determines from a locator file that a particular ObjectStore Server should handle access to a database remote to that Server, and that Server has a value of yes for this parameter, the Server handles access to the database. If the Server does not have a value of yes, the exception err_file_not_local is signaled.
If you allow any Server-remote access, each database should be assigned exactly one ObjectStore Server that handles all access to it by all applications, unless that database is never opened for read/write. This is because when one Server handles access to a database, it can prevent concurrent access by other ObjectStore Servers. See the Server parameter Allow NFS Locks.
Caution
Use this parameter with caution. A mistake in the content of a locator file could cause unintentional concurrent access.
Allow Shared Communications
Default: yes
The Allow Shared Communications parameter controls whether the Server allows shared memory communications between itself and the client when they are on the same host. Doing so improves performance. It is a Boolean that defaults to yes (meaning shared memory communication is enabled). If these communications are enabled, the Server and client exchange data by means of shared memory.
It is possible for the Server to run out of virtual memory if you have Allow Shared Communications set to yes and you have many local clients. That's because the server maps each local client's cache information into its virtual memory. Setting Allow Shared Communications to no eliminates the problem.
Authentication Required
Default: by platform
An understanding of ObjectStore authentication is necessary before an explanation of the Authentication Required parameter makes sense.
The defaults are
How the Server controls access to data
ObjectStore has a client/server architecture. When an application reads or modifies a database, it sends messages to an ObjectStore Server, which in turn reads and writes the data in the database.
Because each ObjectStore Server handles requests from many different users, it is responsible for enforcing access control to files containing databases. It must use privileged access to read or write any user's database, and it must ensure that only users entitled by the host system's rules for access control are allowed access to databases. To implement access control, the ObjectStore Server must know the user name and group of the client process that is requesting that it operate on a database.
Authentication
If you start an application that asks the ObjectStore Server to read or modify a protected file, the Server determines whether you have proper read/write permission for the file. This access checking has two parts. The first part is authentication, the operation in which the Server learns who the client is, and on behalf of which user it is performing operations. The second part is checking whether that user has permission to perform the requested operation.
The type of authentication ObjectStore uses is determined by the value of the Server parameter Authentication Required.
Note that certain Server operations that deal with file databases require authentication. If the client does not provide authentication, the Server refuses to perform such an operation. These operations include looking up, creating, and deleting file databases, or asking their size or access modes.
Administrative commands for which authorization is required send authentication to the Server first. Administrative commands are ObjectStore utilities that affect other people's work environment, for example, the utility that shuts down the Server.
ObjectStore applications send authentication to the Server the first time the application does an operation on that Server for which authentication is required. After an application sends authentication information to a Server, it need not do so again for the lifetime of the process.
Administrative operations for authorized clients
The Server performs several administrative operations only on behalf of an authorized client. These are the Server operations invoked by the ossvrshtd and ossvrclntkill utilities, with these exceptions:
Parameter values
The Authentication Required Server parameter specifies how the Server controls database access. There are five possible types of authentication:
On UNIX platforms, clients who present authentication NONE cannot access file databases. Release 5 clients always present some other form of authentication if possible.
On Windows NT, clients who present authentication NONE can access file databases. Clients can access any file that is accessible to the user running the Server (usually Local System).
The client sends the Server a UNIX user ID and a set of group IDs, which the Server trusts. The ObjectStore client library always sends the current effective user ID and group set. This is the same mechanism used by the NFS protocol.
Caution
If you use this method, be aware of the following points:
For a full explanation of the secure RPC mechanism, see the documentation supplied with your operating system.
DES authentication protects against abuse of the root password and against straightforward attempts to patch an ObjectStore client to send a fraudulent access ID. However, it is not secure against a determined intruder, due to bugs both in its design and in the reference implementation.
ObjectStore requires each client application to send a user name and password to the Server, which validates them. See "User interface to authentication". The advantage of this method is that there is no way to fool the Server - it grants exactly the access available to the user it authenticates. The disadvantage is that ObjectStore cannot arrange a trusted path. That is, there is no way that a user, prompted for a password, can be sure that the password will be sent to the ObjectStore Server and only to the ObjectStore Server. A malicious program author could solicit and then retain passwords.
Parameter value might imply a set of values
When you set the parameter to one of these authentication types, it means that the Server can use that value as well as any values that follow it in the list, if the value can be specified on that Server's platform. The complete prioritized list of authentication types is
- NONE
- SYS
- DES
- NAME PASSWORD
- NT LOCAL
To determine the list of authentication types that a Server supports, run the ossvrstat utility. See ossvrstat: Displaying Server and Client Informationfor further information.
Examples of allowable authentication
For example, if an AIX Server has the value NONE for the Authentication Required Server parameter, it means that a client can return information that complies with NONE, SYS, DES, or NAME PASSWORD. These four values make up the Server-supported list on this platform.
If an HP Server has Authentication Required set to SYS, it means that a client can return information that complies with SYS or NAME PASSWORD. The Server-supported list for HP-UX has two values.
If a Windows NT Server has Authentication Required set to Name Password, clients can return information that complies with Name Password or NT Local. The Server-supported list for Windows NT contains two values.
How does a
client choose?
How does a client determine which type of authentication to provide to the Server?
On all platforms, if Authentication Required is NONE and if the Server can have a value of SYS for the parameter, the client returns information that complies with SYS. This allows Release 5 clients to access Release 5 rawfs and file databases.
Suppose that Authentication Required is NONE but the Server cannot have a value of SYS. In this case, the client returns information that complies with the first value in the Server-supported list that the client supports. For an AIX client contacting a Windows NT Server, this would be Name Password. Note that if the Server were on AIX, both the SYS and DES values would be allowed. A Server that cannot have a value of SYS is not a UNIX system and so the Server-supported list of values for authentication includes NONE, Name Password, and possibly NT Local.
UNIX clients always provide Name Password authentication when accessing Windows NT Servers.
Windows NT clients
When a Windows NT client provides authentication it must provide the domain name, the user name, and the user password. By default, ObjectStore uses the USERDOMAIN environment variable. You can override this by specifying a name of the form domain\name.
When a Release 5 Windows NT client contacts a local Windows NT Server, the client always provides NT Local authentication.
When a Release 5 Windows NT client contacts a remote Windows NT Server or a UNIX Server, the default is for the client to provide Name Password authentication.
To allow a Windows NT client to provide SYS authentication to a UNIX Server, you must set the user ID and group ID in the Windows NT registry. To prohibit Windows NT clients from returning SYS authentication to UNIX Servers, you can either set Authentication Required to Name Password or forbid the user ID and group ID entries in the registry. See Chapter 8, Managing ObjectStore on Windows.
Suppose a Release 5 Windows NT client contacts a Server that can accept SYS authentication. Further suppose that user ID and group are set in the Windows NT registry. In this case, the client provides SYS authentication. This allows compatibility with UNIX Servers. If the Server does not allow SYS authentication or if the user ID and group are not set in the registry, then the client provides the first type of authentication that it can that is in the list of Server-supported authentication types. In some cases, this is Name Password. But it might be NONE, which means that a Release 5 Windows NT client can access file databases that are accessible by the user running the Server.
Exceptions
When a Server is using Name Password for authentication and detects something wrong, it signals the err_authentication_failure exception. This usually means that there is no user by the specified name or the password is incorrect.
If the Server receives a command that needs authentication, but the connection has not been authenticated, and Authentication Required is not None, the Server rejects the command and signals the err_rpc_auth_tooweak (client credential too weak) exception. This means that the client could not provide the authentication that the Server requested. This happens when a client cannot generate any of the types of authentication that the Server requires.
User interface to authentication
By default, the interface to Name Password authentication communicates with the user interactively. On UNIX, it uses the /dev/tty device or the stdin and stdout streams to prompt for a user name and a password. On Windows, console applications work the same way. Windows applications pop up a dialog box. Your application can control the Name Password interface with the functions objectstore::set_simple_auth_ui() and get_simple_auth_ui(), which are described in the ObjectStore C++ API Reference.
Cache Manager Ping Time
Default: 300
The Cache Manager Ping Time parameter specifies a number of seconds. Whenever between Cache Manager Ping Time seconds and twice Cache Manager Ping Time seconds have elapsed with no message from the client, the Server attempts to send a message to the client's Cache Manager to check whether the client is still active. If the Cache Manager cannot be contacted or the Cache Manager indicates that the client does not exist, the Server disconnects the client connection. The minimum number of seconds you can specify is 10.
A large value for this parameter reduces network traffic and reduces the chance that a client will be disconnected because of a transient network failure. A small value increases network traffic, but ensures that a client that is disconnected from the network cannot hold locks for more than a short period of time.
If Cache Manager Ping Time and Cache Manager Ping Time In Transaction have different values, ObjectStore uses Cache Manager Ping Time when the client is not in a transaction.
Cache Manager Ping Time In Transaction
Default: 300
The Cache Manager Ping Time In Transaction parameter is the same as the Cache Manager Ping Time parameter, except the Server uses the interval you specify only during transactions. The number of seconds you specify for Cache Manager Ping Time In Transaction must be less than or equal to the value set for Cache Manager Ping Time. The minimum you can specify is 10 seconds.
If Cache Manager Ping Time and Cache Manager Ping Time In Transaction have different values, ObjectStore uses Cache Manager Ping Time In Transaction when the client is in a transaction.
DB Expiration Time
Default: 300
The DB Expiration Time parameter specifies the number of seconds that the Server keeps a rawfs database open after the last user has closed the database. This allows data propagation to happen in the background, which means that users do not wait for propagation to occur before they can close the rawfs database. Also, applications that use the rawfs database start more quickly if they are starting during DB Expiration Time.
Deadlock Victim
Default: work
The Deadlock Victim parameter specifies the method that the Server uses to select a victim in the event of a deadlock. Specify one of the following to determine which client is the victim. The Server sends a message to the selected client to abort the transaction.
This method of choosing a victim is secondary to transaction priority. See objectstore::set_transaction_priority() in the ObjectStore C++ API Reference for more information on transaction priorities.
Deadlock
Deadlock occurs when two or more processes are waiting for locks and there is a circular dependency such that none of them can obtain the locks. For example, ProcessA is waiting for a lock held by ProcessB, which is waiting for a lock held by ProcessA. Because the dependency is circular, none of the processes can obtain the requested lock. If the ObjectStore Server did not detect deadlock situations, the processes involved would wait for an infinite length of time.
Transaction data
When deadlock occurs, the Server automatically detects it and chooses a victim whose transaction is aborted. If the aborted transaction is a lexical transaction, it is automatically retried. If it is a dynamic transaction, the transaction is aborted with err_deadlock.
When the Server aborts lexical transactions, it rolls back the persistent data that has been modified during the transaction to its pretransaction state. Also, stack variables declared within the scope of the transaction go out of scope. Special care must be taken for stack variables whose values have been changed within the transaction and for space allocated on the heap during the transaction.
To obtain information about where the deadlock occurs, run the Server in debug mode.
Direct to Segment Threshold
Default: 128
The Direct to Segment Threshold parameter specifies, in sectors, the threshold value that determines whether the Server writes segments to the log first and then to the database, or writes them directly to the database. If less than this threshold is written past the current end of segment during a transaction, the data is written to the log before being written to the database. If the number of sectors written is greater than this threshold, the data is written directly to the database. The default is 128 sectors (64 KB).
Choosing a value depends on the size of the log and the cost of writing and flushing the data separately from writing and flushing the log record. For example, if you need to add 1 KB to each of 100 segments, writing 1 KB to each segment accesses the disk 100 times. If average disk speed is 8 to 12 milliseconds per access, it would take 800 milliseconds to 1.2 seconds to perform all the write operations. But if you write the data to the log, either in a record or in the log data segment, the write operation would probably be to contiguous disk storage and only take about 50 milliseconds. This parameter lets you choose between
The Server applies the following tests in the following order; the first one that matches determines how the data is stored:
- If the data is being written to a newly created segment, data is always written directly to the database segment.
- If the following conditions are met, the data goes directly to the database (this formula means the decision to write data directly to a database is not changed by the size of individual write operations):
- If neither of the previous conditions applies, data is put in the log until the commit is done.
Failover Heartbeat Time
Default: none
The Failover Heartbeat Time parameter must be specified if you are using a failover Server. This parameter can be set to between 2 and 60 seconds. The parameter defines how often a heartbeat message is written to disk. In the advent of a failure, it takes five times Failover Heartbeat Time for the secondary Server to recognize the failure and to take over.
Host Access List
Default: none
The Host Access List parameter specifies the pathname of a file. This file must contain a set of primary names of hosts, one name per line. (If DNS is in use, they must be fully qualified domain names.) The Server refuses connections from any host not on the list, or whose name cannot be determined. This mechanism is only as secure as the available means for translating host addresses to host names. On some networks, such as NetBIOS, there might not be a secure method.
This parameter is intended for use in environments where a machine is on a network with untrustworthy hosts and DES authentication is unavailable or unworkable.
When you create a host access list, and you also have an administrative hosts list set with the Admin Host List Server parameter, ObjectStore adds all hosts in the administrative hosts list to the host access list.
Log Data Segment Growth Increment
Default: 2048
The Log Data Segment Growth Increment parameter specifies how many sectors to add to the data segment in the transaction log when more room is needed. The default is 2048 sectors (1 MB).
Log Data Segment Initial Size
Default: 2048
The Log Data Segment Initial Size parameter sets the initial size of the data segment in the transaction log in sectors. The default is 2048 sectors (1 MB).
Log File
Default: rawfs
The Log File parameter specifies the pathname of the transaction log file.If you do not specify a value for Log File, the Server maintains the log in the rawfs, where it does not need a name. If you do not have a rawfs and you do not specify a value for Log File, the Server fails to start and displays the message
There are no partitions specified in the parameters file. Whenever
partitions are omitted from the parameters file a log file path must be
specified in the parameters file.
If you have a rawfs, you should not specify a name for this parameter. See Description of the Server Transaction Log.
If you specify a pathname for this parameter, the pathname cannot be for a raw partition. The directory that contains the log file must exist before you start the Server. When the log is in the native file system, you should place it where it can never be accidentally deleted by a user. You might want to name it in such a way that it is never deleted.
Caution: Deleting the log file can cause database corruption.
Windows and OS/2
On Windows and OS/2, the value of this parameter is normally set while you run the ObjectStore Setup utility. If you indicate that you do not want the log file to be in the rawfs, the utility prompts you to enter the name of the log file. You can press Enter to select the default. The defaults are in the following table.
Log Record Segment Buffer Size
Default: 1024
The Log Record Segment Buffer Size parameter defines how much buffer space is reserved for log records. The default is 1024 sectors (512 KB).
Log Record Segment Growth Increment
Default: 512
The Log Record Segment Growth Increment parameter specifies by how many sectors to increase the log record segment when more room is needed. The default is 512 sectors (256 KB).
Log Record Segment Initial Size
Default: 1024
The Log Record Segment Initial Size parameter sets the initial combined size of the two log record segments in sectors. The default is 1024 sectors (512 KB).
Max AIO Threads
Default: 3
The Max AIO Threads parameter determines the number of threads the Server can start to perform file input/output (I/O). One thread performs all I/O for a given file. Each thread can handle I/O for multiple files. ObjectStore assigns files to threads on a rotating basis.
When this parameter is set to 0, Servers perform I/O synchronously.
If you never open more than a given number of files, you might want to set this parameter to that number. This ensures that there is one thread per file.
While ObjectStore does not have a limit on the number of threads you can use, your operating system might.
The default setting is 3 threads.
Max Connect Memory Usage
Default: 0
The Max Connect Memory Usage parameter defines in kilobytes an amount of virtual memory. When the Server is using this much virtual memory, it will refuse new connections from clients. As long as the amount of virtual memory in use is less than the amount set for Max Connect Memory Usage, the Server allows a new connection. The Server does not consider how much memory the new connection might need.
ObjectStore does allow its utilities to connect to the Server when the amount specified for Max Connect Memory Usage is exceeded. However, the amount of virtual memory being used must be less than (Max Connect Memory Usage + Max Memory Usage)/2.
The Max Connect Memory Usage parameter is always at least 1 MB less than the Max Memory Usage parameter. When you increase the value set for Max Connect Memory Usage, the Server increases Max Memory Usage if necessary.
The default is that Max Connect Memory Usage is unlimited. This is indicated with a 0.
Max Data Propagation Per Propagate
Default: 512
The Max Data Propagation Per Propagate parameter specifies the maximum number of sectors that can be moved in one propagate operation. This limits the impact of propagation on the handling of client requests. The default is 512 sectors (256 KB).
When counting the amount of data being propagated, ObjectStore weights the effect of noncontiguous data by 64 sectors. This means that with Max Data Propagation Per Propagate set to its default of 512 sectors, a maximum of eight noncontiguous writes can occur in a single propagation.
Max Data Propagation Threshold
Default: 8192
The Max Data Propagation Threshold parameter sets the number of sectors that can be waiting to be propagated. When the number of sectors waiting to be propagated exceeds the value specified for Max Data Propagation Threshold the Server forces propagation to run faster. The default is 8192 sectors (4096 KB).
Max Memory Usage
Default: 0
The Max Memory Usage parameter specifies in kilobytes the maximum amount of virtual memory the Server can use. The Server checks this parameter when it starts. The Server immediately allocates and then frees the specified amount of memory. On some platforms, this confirms the availability of the memory and reserves swap space for the Server.
Specify a number that includes the minimum needed plus some other arbitrary amount. If you specify a number that is less than the minimum needed, the Server increases the number to an appropriate value. When calculating the minimum amount of virtual memory needed, the Server allows for
The default is that Max Memory Usage is unlimited. This is indicated with a 0.
Max Two Phase Delay
Default: 30
The Max Two Phase Delay parameter specifies the maximum number of seconds that the Server can delay a two-phase commit so that the Server can back up data. Sometimes, when ObjectStore is backing up data on multiple Servers at the same time, ObjectStore must synchronize the relevant Servers. This ensures that a transaction applying to more than one Server is committed on all relevant Servers. To do this, the Server must sometimes delay the commit of some transactions. Usually, ObjectStore can synchronize the Servers in much less than a second.
If a client aborts during a two-phase commit, this value could be exceeded. If this value is exceeded, ObjectStore cancels the delay and tries again.
Message Buffer Size
Default: 512
The Message Buffer Size parameter sets the size of the message buffer that the Server uses for processing a message from a client. The Server reads data from this buffer and writes data requested by the clients into this buffer. The default is 512 sectors (256 KB), with the value being rounded to a multiple of 64 KB.
Message Buffers
Default: 4
The Message Buffers parameter sets the number of message buffers the Server uses to communicate with clients. This number defines the maximum number of clients that can simultaneously perform operations that fetch or store persistent data.
Notification Retry Time
Default: 60
The Notification Retry Time parameter specifies the time in seconds between retries for Server-to-Server communication. It is used during two-phase commit recovery.
PartitionN
Default: none
The PartitionN parameter (where N is an integer) specifies a partition in the rawfs. See Creating a Rawfs in the chapter for your platform for information about using this parameter.
Preferred Network Receive Buffer Size
Preferred Network Send Buffer Size
Default: 16,384
The Preferred Network Receive Buffer Size and Preferred Network Send Buffer Size parameters specify the network buffer sizes in bytes for sending and receiving messages to and from the Server, respectively.
UNIX
On many UNIX platforms these are TCP buffer sizes.
Propagation Buffer Size
Default: 8192
The Propagation Buffer Size parameter selects the amount of buffer space reserved for propagation. This space is used for reading data from the log that is to be written to target databases. If the buffer size is large enough, data written to the log can be kept in memory until propagation occurs, thus avoiding the need to read the log. The default is 8192 sectors (4096 MB).
Propagation Sleep Time
Default: 60
The Propagation Sleep Time parameter determines the number of seconds between propagations. This parameter takes effect only when there is data to be propagated. If a lot of data is waiting to be propagated, the Server temporarily decreases this interval.
Restricted File DB Access
Default:
none
Determines file access when an account that does not have root privileges starts the Server. Possible values are User, Group, All, or None. When you set this parameter to a value other than None and the account that starts the Server does not have root permission, then
By default Restricted File DB Access is set to None, which, in effect, disables this parameter. This means that if an account with non-root permission starts the Server, ObjectStore allows access to rawfs databases but does not allow access to file databases.
[previous] [next]
Copyright © 1997 Object Design, Inc. All rights
reserved.
Updated: 03/26/98 20:18:35