SAND CDBMS Administration Guide
The Nucleus.ini File

 

Previous Topic:
Introduction
Chapter Index
Next Topic:
Nucleus.ini file Parameters - Connection Sections

 

Nucleus.ini file Parameters


DATABASE Sections

A DATABASE section contains parameters governing the operations of an nserv database server engine running a specific database instance.

The format for the section heading is [DATABASE instance-name], where instance-name is the name of the database (Real or Persistent Mode) or virtual database (Virtual Mode) started by the nserv engine. The instance name in the DATABASE section header can be entered in any combination of uppercase and lowercase characters.

In order to create or start a database instance using the nserv utility, a corresponding [DATABASE instance-name] section must be present in the nucleus.ini file, containing at least a DatabasePath entry that points to the location of the primary database file for that instance.


Parameters

DatabasePath
The path to the primary database file (database-name.n00). This parameter is required.

Maximum path length: 128 characters

Cache
The maximum amount of operating system memory (in megabytes) to be used for SAND CDBMS caching during database operations. The Cache value should be somewhat lower than the amount of real memory (RAM) available to the system; a rule of thumb is to set the value to 1/40 of the database size. Cache size should usually be increased for substantial data loads, especially when high-cardinality fields (with many unique values) are involved.

Minimum: 64
Maximum:
UNIX: 131072 (128 GB)
                    
Windows: 2047 (2 GB minus 1 MB)
Default, or when value is out of range:
128


RunMode
The operating mode in which SAND CDBMS will start the database instance.

Possible values:

REAL
(default)
Standard operation: upon execution of the COMMIT [WORK] command, changes are written to the real database. Only one instance of a given database can be started in Real Mode; the instance name in the DATABASE section header must be the same as the real database (database-name.n00)

VIRTUAL
Upon execution of the COMMIT [WORK] command, changes are written to a temporary Delta File, which is destroyed when the nserv engine process is shutdown. Any number of virtual instances of a database may run concurrently; each must have its own DATABASE section with a unique instance name in the section header, but will share the same PrimaryDB (see below).

When the instance name is equal to the PrimaryDB (that is, when the instance is the "master" virtual instance), the changes in the Delta File may be applied to the real database using the SHUTDOWN...KEEP CHANGE command. See below for information about additional parameters required for Virtual Mode operation. For more information about Virtual Mode, consult the Virtual Mode Operations section of the SAND CDBMS Administration Guide.

PERSISTENT
Time Travel operation: changes are written to a temporary Delta File, which can be made permanent using the SHUTDOWN...KEEP CHANGE command (the real database remaining unchanged). The permanent Update File can serve as an entry point to the new version of the database. See below for information about additional parameters required for Persistent Mode operation. For more information about Persistent Mode, consult the Persistent Mode Operations section of the SAND CDBMS Administration Guide.

DirectIO
Enables or disables direct I/O for file operations. When direct I/O is enabled, reads and writes are performed directly between SAND CDBMS and the storage devices, bypassing the operating system's file system buffer. For certain operations, such as loading data or merging Snapshots, this can result in significantly better performance compared to standard buffered I/O.

Note that direct I/O cannot be used in Real Mode.

Possible values:

0
(default)
Disables direct I/O.

1
Enables direct I/O.


MaxVMem

(UNIX only) Sets the maximum amount of virtual memory (in megabytes) that nserv will use. If MaxVMem is not set, the server will use the environment’s hard ulimit setting to determine its virtual memory limit, based on the hard ulimit’s relation to the minimum memory requirements for the server (Cache value + 1024 MB).

If the MaxVMem setting is less than the Cache value + 1024 MB (1 GB), it is automatically set to Cache + 1 GB. If the MaxVMem setting is greater than the hard ulimit setting, it is automatically set to the hard ulimit setting. If MaxVMem is not set and the hard ulimit setting is unlimited, MaxVMem defaults to Cache + 1 GB.

The maximum virtual memory settings are summarized in the table below:

MaxVMem is not set   MaxVMem is set
ulimit < (Cache + 1 GB) Maximum virtual memory is set to the hard ulimit value, which is below nserv’s minimum memory requirements (Cache value + 1 GB), so the server will fail to start. MaxVMem < (Cache + 1 GB) Maximum virtual memory is set to (Cache value + 1 GB).
ulimit > (Cache + 1 GB) Maximum virtual memory is set to the hard ulimit value. MaxVMem > (Cache + 1 GB) Maximum virtual memory is set to the MaxVMem value, up to a maximum of the hard ulimit value.
ulimit is unlimited Maximum virtual memory is set to (Cache value + 1 GB). ulimit is unlimited Maximum virtual memory is set to the MaxVMem value.


A setting of 0 removes any limits on virtual memory usage by the server, although it is still bound by the hard ulimit. However, if the hard ulimit is unlimited, a setting of 0 means that nserv will attempt to use as much memory as possible for its operations, irrespective of other, non-SAND processes. This situation is not recommended unless the machine is dedicated to running SAND operations. Otherwise, it is best to ensure that a certain amount of system memory is reserved for non-SAND processes.

Minimum: Cache value + 1024 MB
Maximum:
the hard ulimit setting
Default: Cache value + 1024 MB (set only if MaxVMem is undefined and the hard ulimit is unlimited)


ODDBPreferredNode
(Octopus only) The prioritized, comma-separated list of nodes where the Octopus ODDB instance should start. Octopus will attempt to start the database as an ODDB instance on the first node in the ODDBPreferredNode list. If that attempt fails, another attempt will be made to start the instance on the next node in the list. And so on down the list until the ODDB instance successfully starts on a node, or the list of nodes is exhausted (resulting in an error condition).

The asterisk wildcard character (*) can be used to indicate "any available node". If included in the ODDBPreferredNode list, it should appear last so that "any available node" will only be used if the specific nodes listed before the '*' are not accessible.

Default: use any available node

Note that any of the following configurations will produce the default behavior:


LDAPHOST
(Required if LDAP is used) The host name or IP address, and optionally the port number, for the LDAP server(s). If the port number is omitted, the default port is assumed (389, or 636 for SSL).

The format of the LDAPHOST string (or "URL") is as follows:

LDAP://<host name or IP>[:<port number>]

For example:

LDAPHOST=LDAP://host1:2900
LDAPHOST=LDAP://192.0.1.184:2900
LDAPHOST=LDAP://host2
LDAPHOST=LDAP://ldap.myhost.com:5999

If Secure Sockets Layer (SSL) is enabled, specify "LDAPS" instead of "LDAP":

LDAPS://<host name or IP>[:<port number>]

For example:

LDAPHOST=LDAPS://host1:2900

Multiple or redundant LDAP servers can be specified in the LDAPHOST parameter simply by separating the URLs with commas. For example:

LDAPHOST=LDAP://host1:2900,LDAPS://host2:2900,LDAP://host3:3200

The LDAP servers are read from left to right in the LDAPHOST list. If the leftmost server is not available, the next one in the list will be tried, and so on until an available LDAP server is found.


LDAPBASEDN

(Required if LDAP is used) The format of the base "distinguished name" message string that will be sent to the LDAP server. It has the following form:

[ou=<organizational unit>,]dc=<domain component>[,dc=<domain component>]

The "ou" parameter specifies an organizational unit, such as the country code. The "dc" parameter(s) specify each component of the domain, delimited by commas. For example, "uk.myhost.com" would be represented as "ou=uk,dc=myhost,dc=com".


LDAPROLE

(Required if LDAP is used and LDAPBINDINGS is not setThe name of the LDAP attribute containing the SAND database role.


LDAPBINDINGS

(Required if LDAP is used and LDAPROLE is not setThe list of LDAP group and SAND database role bindings in the following format:

<LDAP group>:<SAND database role>

Multiple binding pairs must be separated by semicolons, as in this example:

ldap1:user1;ldap2:user2;ldap3:user3

Beyond simple one-to-one bindings, some logical construction is permitted in the string, allowing logical OR/AND group memberships to determine bindings. For instance, membership in both group 1 and group 2 can be defined as a requirement for binding to authorization X. Similarly, membership in either group 1, group 2, or group 3 can be defined as a requirement for binding to authorization Y. The logical OR is represented by a comma ( , ), while the logical AND is represented by a plus sign (+). Logical evaluation is performed left-to-right, although this order can be altered with parentheses, since logical expressions within parentheses are evaluated first.

In addition, a binding can be limited to a particular SAND database by including @database immediately after the binding pair.

There is also a way to specify a default binding if no other binding applies to the LDAP user. This is done by specifying *:user last in the LDAPBINDINGS list (where * represents "all Active Directory groups").

The following table summarizes the special characters permitted in the LDAPBINDINGS string:

Symbol Description
,

Logical OR. The LDAP user can be a member of one or another group in the binding pair. For example, groupA,groupB:user1 specifies that users belonging to either "groupA" or "groupB" will be binded to the SAND authorization "user1".

+
Logical AND. The LDAP user must be a member of both groups in the binding pair. For example, groupA+groupB:user2 specifies that only users belonging to both "groupA" or "groupB" will be binded to the SAND authorization "user2".
( )
Items enclosed by parentheses in the LDAPBINDINGS string will be logically evaluated first. This is useful for removing ambiguity in the order of evaluation. For example, (groupA+groupB),(groupA+groupC):user3 indicates that users belonging to both "groupA" and "groupB", or to both "groupA" and "groupC", will be binded to the SAND authorization "user3".
@
Database specifier, used to limit a binding to a particular database. For example, groupD:user4@db1 indicates that the LDAP group "groupD" is binded to the SAND authorization "user4" only for the "db1" database.
*
A shorthand way to represent"all LDAP groups" in a binding pair (for example, *:user4), allowing a default binding to be assigned if no other binding applies to the user. For example, *:public specifies that all Active Directory groups be binded to the SAND authorization "public". Note that this default binding must be specified last in the LDAPBINDINGS list for it to work properly. Since this binding is always valid for every user, any bindings that come after it in the list will never be applied.

If an LDAP user belongs to more than one group, the first binding in the list that applies to the user (reading from left to right) will be used.


LDAPMODE

Sets the user authentication mode. There settings are:

LOGIN (default)
The user name and password entered through the client are used to connect to the LDAP server and perform the authorization lookup.

OPEN
SAND uses a third party "service user" (defined with the LDAPSERVICEUSER and LDAPSERVICEPASSWORD parameters) to perform the authorization lookup on the LDAP server on behalf of the client. When the special constant "_me_" is entered as the user name on the client, the service user will retrieve the client user's system login name and perform the lookup on the LDAP server using that information. In effect, Open Mode is a form of shared authentication.

Note that both LDAP modes can be enabled by including both "LOGIN" and "OPEN" for the LDAPMODE parameter, separated by a comma (for example, "LOGIN,OPEN"). In this case, the user can enter either their user name and password, or the "_me_" constant.

If "OPEN" is specified and "LOGIN" is not, only users that connect with "_me_" will be accepted.


LDAPSERVICEUSER

(Required if LDAPMODE=Open) Specifies a third party "service user" that will perform the LDAP authorization lookup on behalf of the client user. Typically, this is a specialized user defined on the LDAP server with limited privileges beyond authorization lookup.


LDAPSERVICEPASSWORD

The LDAP server password for the user specified with the LDAPSERVICEUSER parameter.


LDAPDOMAIN

A comma-separated list of one or more Active Directory domains (for example, "dev,qa,mkt,sales"). The domain associated with the user's system login name is checked against this list. If it is not found, the LDAP authentication will fail.

If this parameter is omitted, user domain verification is not performed.


LDAPCNALIAS

Specifies the LDAP attribute that stores the user name. This parameter should only be set if the standard CN (Common Name) attribute is not used to store the user name.


LDAPPATH

Sets the full path, including file name, of the system's LDAP library, in case the default library will not be used. This parameter applies only to operating systems other than Windows and AIX.

Default: libldap.so in the LDLIBRARYPATH location

 

Sample DATABASE section (Real Mode)

[DATABASE customer]
DatabasePath=/usr/sand/db
Cache=2048
MaxVMem=4096
LDAPHOST=LDAP://ccm.sand.com:2162
LDAPBASEDN=ou=ca,dc=sand,dc=com
LDAPROLE=SANDRole
LDAPBINDINGS=MKT:MARKETING;SLS:SALES;*:PUBLIC
LDAPPATH=/tmp/lib/ldaplib.so
LDAPMODE=LOGIN



DATABASE Section Parameters for Virtual Mode and Persistent (Time Travel) Mode Operation

To run a SAND database instance in Virtual or Persistent Mode, the DATABASE section can contain additional parameters relating specifically to these modes of operation. These parameters are described below.


PrimaryDB
The name of the real database used in Virtual or Persistent Mode.

Default: instance name from the DATABASE section header (in Virtual mode, the instance will be the master virtual instance)


MaxDeltaFileSize
The maximum size of the Delta File, expressed in megabytes; a value of 0 indicates no limit.

Default: 0 (no limit)


MaxDeltaFileRatio
The maximum size of the Delta File, expressed as a percentage of the database size. If this parameter is included, it takes precedence over the MaxDeltaFileSize parameter, with one exception: if MaxDeltaFileRatio is set to 0 (zero), the MaxDeltaFileSize parameter is used.

Default: 0 (MaxDeltaFileSize is used)

Note:
MaxDeltaFileRatio should be used only with databases larger than 10 GB; for smaller databases, use the MaxDeltaFileSize parameter.


DeltaPath

The location of the Delta File. Note that the maximum length of the Delta File directory path is 128 characters.

Default: (see "Resolving Update File and Delta File Paths" below)


SnapshotPath

(Persistent Mode only) The overriding location for the Delta File and new Update Files created via KEEP CHANGE.

By default, new Update Files are created in the same directory as the primary database file (specified by the DatabasePath parameter), while the location of the instance's Delta File is given by the DeltaPath parameter. When the SnapshotPath parameter is specified, the Delta File and new Update Files are stored in the same directory so that the creation of a new Update File requires only that the Delta File be renamed.

Default: (see "Resolving Update File and Delta File Paths" below)

 

Resolving Update File and Delta File Paths

Given the presence or absence of the SnapshotPath/DeltaPath parameters, the Update File and Delta File paths are resolved in the following manner:

 

Sample DATABASE section (Virtual Mode)

[DATABASE customer_vdb]
RunMode=virtual
PrimaryDB=customer
DatabasePath=/usr/sand/dB
Cache=2048
MaxDeltaFileSize=0
MaxDeltaFileRatio=10
DeltaPath=/usr/sand/delta
DirectIO=1

 
Previous Topic:
Introduction
Chapter Index
Next Topic:
Nucleus.ini file Parameters - Connection Sections