Setting Store Parameters

Changing Parameters
Setting Store Wide Policy Parameters
Admin Parameters
Storage Node Parameters
Replication Node Parameters
Global Parameters
Security Parameters
Admin Restart
Replication Node Restart

The three Oracle NoSQL Database service types; Admin, Storage Node and Replication Node; have configuration parameters, some of which can be tweaked after the service is deployed. To see the parameter values that can be changed, you use the following command in the CLI:

show parameters -service <id>

This command allows you to display service parameters and state for the specified service. The service may be a Replication Node, a Storage Node, or Admin service, as identified by any valid string. You can use the -policy optional flag to show global policy parameters.

Changing Parameters

All of the CLI commands used for creating parameter-changing plans share a similar syntax:

plan change-parameters -service <id>...

All such commands can have multiple ParameterName=NewValue assignment arguments on the same command line. If NewValue contains spaces, then the entire assignment argument must be quoted within double quote marks. For example, to change the Admin parameter collectorPollPeriod, you would issue the command:

kv-> plan change-parameters -all-admins -params \
    "collectorPollPeriod=20 SECONDS" 

If your configProperties for all Replication Nodes is set to:

"configProperties=je.cleaner.minUtilization=40;"

And you want to add new settings for configProperties, you would issue the following command:

kv-> plan change-parameters -all-rns -params \
     "configProperties=je.cleaner.minUtilization=40;\
     je.env.runVerifier=false;"

If for some reason, different Replication Nodes have different configProperties parameter values, then the change-parameters command will need to be tailored for each Replication Node.

The following commands are used to change service parameters:

  • plan change-parameters -service <shardId-nodeId> -params [assignments]

    This command is used to change the parameters of a single Replication Node, which must be identified using the shard and node numbers. The shardId-nodeId identifier must be given as a single argument with one embedded hyphen and no spaces. The shardId identifier is represented by rgX, where X refers to the shard number.

  • plan change-parameters -all-rns -params [assignments]

    This command is used to change the parameters of all Replication Nodes in a store. No Replication Node identifier is needed in this case.

  • plan change-parameters -service <storageNodeId> -params [assignments]

    This command is used to change the parameters of a single Storage Node instance. The storageNodeId is a simple integer.

  • plan change-parameters -all-admins -params [assignments]

    This command is used to change Admin parameters. Because each instance of Admin is part of the same replicated service, all instances of the Admin are changed at the same time, so no Admin identifier is needed in this command.

    If an Admin parameter change requires the restarting of the Admin service, KVAdmin loses its connection to the server. Under normal circumstances, KVAdmin automatically reconnects after a brief pause, when the next command is given. At this point the plan is in the INTERRUPTED state, and must be completed manually by issuing the plan execute command.

  • plan change-parameters -security <id>

    This command is used to change security parameters. The parameters are applied implicitly and uniformly across all SNs, RNs and Admins.

In all cases, you can choose to create a plan and execute it; or to create the plan and execute it in separate steps by using the -noexecute option of the plan command.

Setting Store Wide Policy Parameters

Most admin, Storage Node, and replication node parameters are assigned to default values when a store is deployed. It can be inconvenient to adjust them after deployment, so Oracle NoSQL Database provides a way to set the defaults that are used during deployment. These defaults are called store-wide Policy parameters.

You can set policy parameters in the CLI by using this command:

change-policy -params [name=value]

The parameters to change follow the -params flag and are separated by spaces. Parameter values with embedded spaces must be separated by spaces. Parameter values with embedded spaces must be quoted. For example: name = "value with spaces". If the optional dry-run flag is specified, the new parameters are returned without changing them.

Admin Parameters

The following parameters can be set for the Admin service:

  • adminLogFileCount=<Integer>

    Sets the number of log files that are kept. This value defaults to "20". It is used to control the amount of disk space devoted to logging history.

  • adminLogFileLimit=<Integer>

    Limits the size of log files. After reaching this limit, the logging subsystem switches to a new log file. This value defaults to "4,000,000" bytes. The limit specifies an approximate maximum amount to write (in bytes) to any one file. If the value is zero, then there is no limit.

  • collectorPollPeriod=<Long TimeUnit>

    Sets the Monitor subsystem's delay for polling the various services for status updates. This value defaults to "20" seconds. Units are supplied as a string in the change-parameters command, for example: -params collectorPollPeriod="2 MINUTES"

  • loggingConfigProps=<String>

    Property settings for the Logging subsystem in the Admin process. Its format is property=value;property=value.... Standard java.util.logging properties can be set by this parameter.

  • eventExpiryAge=<Long TimeUnit>

    You can use this parameter to adjust how long the Admin stores critical event history. The default value is "30 DAYS".

  • configProperties=<String>

    This is an omnibus string of property settings for the underlying BDB JE subsystem. Its format is property=value;property=value....

  • javaMiscParams=<String>

    This is an omnibus string that is added to the command line when the Admin process is started. It is intended for setting Java VM properties, such as -Xmx and -Xms to control the heap size. If the string is not a valid sequence of tokens for the JVM command line, the Admin process fails to start.

Storage Node Parameters

The following parameters can be set for Storage Nodes:

  • serviceLogFileCount=<Integer>

    Sets the number of log files that are kept, for this Storage Node and for all Replication Nodes hosted on this Storage Node. This value defaults to "20". It is used to control the amount of disk space devoted to logging history.

  • serviceLogFileLimit=<Integer>

    Limits the size of log files. After reaching this limit, the logging subsystem switches to a new log file. This setting applies to this Storage Node and to all Replication Nodes hosted on this Storage Node. This value defaults to "2,000,000" bytes. The limit specifies an approximate maximum amount to write (in bytes) to any one file. If the value is zero, then there is no limit.

  • haPortRange=<String>

    Defines the range of port numbers available for assigning to Replication Nodes that are hosted on this Storage Node. A port is allocated automatically from this range when a Replication Node is deployed. The format of the value string is "lowport,highport".

  • haHostname=<String>

    Sets the name of the network interface used by the HA subsystem. A valid string for a hostname can be a DNS name or an IP address.

  • capacity=<Integer>

    Sets the number of Replication Nodes that can be hosted on this Storage Node. This value is used to inform decisions about where to place new Replication Nodes. Capacity can be set to values greater than 1 when the Storage Node has sufficient disk, CPU, and memory to support multiple Replication Nodes. Default value: "1".

    If capacity is set to 0, then this Storage Node may be used to host Arbiter Nodes. The pool of Storage Nodes in a zone configured to host Arbiter Nodes are used for Arbiter Node allocation. For more information see Deploying an Arbiter Node Enabled Topology.

  • memoryMB=<Integer>

    Sets the amount of memory known to be available on this Storage Node, in megabytes. Defaults to "0", which means "unknown." and is determined automatically by the store as the total amount of RAM available on the machine.

    You should not need to change this parameter under normal circumstances. Set it to a value less than the amount of RAM, if the machine has other applications running on it (not a recommended configuration) in order to reserve some memory for the other applications.

  • numCPUs=<Integer>

    Sets the number of CPUs known to be available on this Storage Node. Default value: 1.

  • rnHeapPercent=<Integer>

    Sets the percentage of a Storage Node's memory reserved for heap, for all RN processes hosted on this SN. Default value: 85.

  • rnHeapMaxMB=<Integer>

    Sets a hard limit for the maximum size of the Replication Node's Java VM heap. Default value is 0, which means the VM-specific limit is used. The default is roughly 32 GB, which represents the largest heap size that can make use of compressed object references.

    Do not set this value to greater than 32 GB. Doing so can adversely impact your Replication Node's performance.

    Settings larger than the maximum size that supports compressed object references will maintain the default limit unless the size is large enough that the heap can reference a larger number of objects given the increased memory requirements for uncompressed object references. Using these larger heap sizes is also not recommended.

  • systemPercent=<Integer>

    Sets the percentage of the Storage Node's memory which will be used for operating system purposes. This memory is used by the operating system for purposes such as the file system cache, page mapping tables, file system handles, thread stacks, and so forth.

    If this parameter is set to a value less than 100, then the off-heap cache might be used if there is memory left over after allowing for the heap and system use. See Managing the Off-heap Cache for details.

    Default value is 100.

  • mgmtClass=<String>

    The name of the class that provides the Management Agent implementation. See Standardized Monitoring Interfaces for more information. The port cannot be a privileged port number (<1024).

  • servicePortRange=<String>

    Sets the range of ports used for communication among administrative services running on a Storage Node and its managed services. This parameter is optional. By default the services use anonymous ports. The format of the value string is "startPort,endPort."

    The range needs to be large enough to accommodate the Storage Node, all the Replication Nodes (as defined by the capacity parameter), Admin and Arbiter services hosted on the machine, as well as JMX, if enabled. The number of ports required also depends on whether the system is configured for security. For a non-secure system, the Storage Node consumes 1 port (which will be shared with the port assigned separately for the Registry Service, if it overlaps the service port range), and each Replication Node consumes 1 port in the range. An Admin, if configured, consumes 1 port. Arbiters also each consume 1 port. If JMX is enabled, that consumes 1 additional port. On a secure system, two additional ports are required for the Storage Node and two for the Admin. As a general rule, if possible, it is good practice to specify a range that is significantly larger than the minimum to allow for increases in Storage Node capacity or network problems that may render ports temporarily unavailable.

    Note that the ports specified in the service port range should not overlap with the admin port or with ports in the HA range. The service port range can include the registry port, though, and the registry and Storage Node will share a port in that case.

    For a non-secure system, you can use the following formula to arrive at an estimate for the port range size number:

    1 (Storage Node) +
    capacity (the number of Replication Nodes) +
    Arbiters (the number of Arbiter Nodes) +
    1 (if the Storage Node is hosting an admin) +
    1 (if the Storage Node is running JMX)

    For example, if a Storage Node has capacity 1, it is hosting an admin process, and neither Arbiters nor JMX are in use, the range size must be at least 3. You may want to increase the range size beyond this minimum. Doing so allows for safety and expansion of the Storage Node without requiring future changes to this parameter. If capacity were 2, the range size must be greater than or equal to 4.

    If you are deploying a secure Oracle NoSQL Database then you can use the following formula to arrive at an estimate for the port range size number:

     3 (Storage Nodes) +
    capacity (the number of Replication Nodes) +
    Arbiters (the number of Arbiter Nodes) +
    3 (if the Storage Node is hosting an admin) +
    1 (if the Storage node is running JMX) 

    where an additional port was added for each Storage Node, Replication Node or the Admin (if configured).

    For more information on configuring Oracle NoSQL Database securely, see the Oracle NoSQL Database Security Guide.

  • rootDirPath=<path>

    The path to the Storage Node's root directory.

  • rootDirSize=<String>

    Sets the storage size the root directory. Use for heterogeneous installation environments where some Storage Nodes have more disk capacity than others. In that case, this parameter should be used only for those Storage Nodes that place data in the root directory. If the Storage Nodes use some other directory (such as might be specified using plan change-storagedir) then do not use this parameter.

    This parameter is intended for backward compatibility with older installations that were created without specifying the -storagedir parameter.

    Note

    It is strongly recommended that you not place your data in your root directory.

    See Managing Storage Directory Sizes for more information.

    The value specified for this parameter must be a long, followed optionally by a unit string. Accepted unit strings are: KB, MB, GB, and TB, corresponding to 1024, 1024^2, 1024^3, 1024^4 respectively. Acceptable strings are case insensitive. Valid delimiters between the long value and the unit string are " ", "-", or "_".

    Note

    When setting this parameter, no run-time checks are performed to verify that the actual directory size is greater than or equal to the specified size.

Replication Node Parameters

The following parameters can be set for Replication Nodes:

  • collectEnvStats=<Boolean>

    If true, then the underlying BDB JE subsystem dumps statistics into the .stat file. This information is useful for tuning JE performance. Oracle Support may request these statistics to aid in tuning or to investigate a problem.

  • maxTrackedLatency=<Long TimeUnit>

    The highest latency that is included in the calculation of latency percentiles.

  • configProperties=<String>

    Contains property settings for the underlying BDB JE subsystem. Its format is property=value;property=value....

  • javaMiscParams=<String>

    A string that is added to the command line when the Replication Node process is started. It is intended for setting Java VM properties, such as -Xmx and -Xms to control the heap size. If the string is not a valid sequence of tokens for the JVM command line, the Admin process fails to start.

  • loggingConfigProps=<String>

    Contains property settings for the Logging subsystem. The format of this string is like that of configProperties, above. Standard java.util.logging properties can be set by this parameter.

  • cacheSize=<Long>

    Sets the cache size in the underlying BDB JE subsystem. The units are bytes. The size is limited by the java heap size, which in turn is limited by the amount of memory available on the machine. You should only ever change this low level parameter under explicit directions from Oracle support.

  • latencyCeiling=<Integer>

    If the Replication Node's average latency exceeds this number of milliseconds, it is considered an "alertable" event. If JMX monitoring is enabled, the event also causes an appropriate notification to be sent.

  • throughputFloor=<Integer>

    Similar to latencyCeiling, throughputFloor sets a lower bound on Replication Node throughput. Lower throughput reports are considered alertable. This value is given in operations per second.

  • rnCachePercent=<Integer>

    The portion of an RN's memory set aside for the JE environment cache.

Global Parameters

The following store-wide non-security parameters can be implicitly and uniformly set across all Storage Nodes, Replication Nodes and Admins:

collectorInterval =<Long TimeUnit>

Sets the collection period for latency statistics at each component. This value defaults to "20" seconds. Values like average interval latencies and throughput are averaged over this period of time.

Security Parameters

The following store-wide security parameters can be implicitly and uniformly set across all Storage Nodes, Replication Nodes and Admins:

  • sessionTimeout=<Long TimeUnit>

    Specifies the length of time for which a login session is valid, unless extended. The default value is 24 hours.

  • sessionExtendAllowed=<Boolean>

    Indicates whether session extensions should be granted. Default value is true.

  • accountErrorLockoutThresholdInterval=<Long TimeUnit>

    Specifies the time period over which login error counts are tracked for account lockout monitoring. The default value is 10 minutes.

  • accountErrorLockoutThresholdCount=<Integer>

    Number of invalid login attempts for a user account from a particular host address over the tracking period needed to trigger an automatic account lockout for a host. The default value is 10 attempts.

  • accountErrorLockoutTimeout=<Long TimeUnit>

    Time duration for which an account will be locked out once a lockout has been triggered. The default value is 30 minutes.

  • loginCacheTimeout=<Long TimeUnit>

    Time duration for which KVStore components cache login information locally to avoid the need to query other servers for login validation on every request. The default value is 5 minutes.

The following password security parameters can be set:

Parameter Name Value Range and Type Description
passwordAllowedSpecial Sub set or full set of #$%&'()*+,-./:; <=>?@[]^_`{|} (string)~ Lists the allowed special characters.
passwordComplexityCheck [true|false] (boolean) Whether to enable the password complexity checking. The default value is true.
passwordMaxLength 1 - 2048 (integer) The maximum length of a password. The default value is 256.
passwordMinDigit 0 - 2048 (integer) The minimum required number of numeric digits. The default value is 2.
passwordMinLength 1 - 2048 (integer) The Minimum length of a password. The default value is 9.
passwordMinLower 0 - 2048 (integer) The minimum required number of lower case letters. The default value is 2.
passwordMinSpecial 0 - 2048 (integer) The minimum required number of special characters. The default value is 2.
passwordMinUpper 0 - 2048 (integer) The minimum required number of upper case letters. The default value is 2.
passwordNotStoreName [true|false] (boolean) If true, password should not be the same as current store name, nor is it the store name spelled backwards or with the numbers 1–100 appended. The default value is true.
passwordNotUserName [true|false] (boolean) If true, password should not be the same as current user name, nor is it the user name spelled backwards or with the numbers 1-100 appended. The default value is true.
passwordProhibited list of strings separated by comma (string) Simple list of words that are not allowed to be used as a password. The default reserved words are: oracle,password,user,nosql.
passwordRemember 0 - 256 (integer) The maximum number of passwords to be remembered that are not allowed to be reused when setting a new password. The default value is 3.

For more information on top-level, transport, and password security parameters see the Oracle NoSQL Database Security Guide.

Admin Restart

Changes to the following Oracle NoSQL Database parameters will result in a Admin restart by the Storage Node Agent:

Admin parameters:

  • adminLogFileCount

  • adminLogFileLimit

  • configProperties

  • javaMiscParams

  • loggingConfigProps

  • adminHttpPort

For example:

kv-> plan change-parameters -all-admins 
-params adminLogFileCount=10
Started plan 14. Use show plan -id 14 to check status.
        To wait for completion, use plan wait -id 14
kv-> show plan -id 14
Plan Change Admin Params (14)
Owner: null
State:                 INTERRUPTED
Attempt number:        1
Started:               2013-08-26 20:12:06 UTC
Ended:                 2013-08-26 20:12:06 UTC
Total tasks:           4
 Successful:           1
 Interrupted:          1
 Not started:          2
Tasks not started
   Task StartAdmin start admin1
   Task WaitForAdminState waits for Admin admin1 to reach RUNNING state
kv-> plan execute -id 14
Started plan 14. Use show plan -id 14 to check status.
        To wait for completion, use plan wait -id 14
kv-> show plan -id 14
Plan Change Admin Params (14)
State:                 SUCCEEDED
Attempt number:        1
Started:               2013-08-26 20:20:18 UTC
Ended:                 2013-08-26 20:20:18 UTC
Total tasks:           2
 Successful:           2 

Note

When you change a parameter that requires an Admin restart using the plan change-parameters command, the plan ends in an INTERRUPTED state. To transition it to a SUCCESSFUL state, re-issue the plan a second time using the plan execute -id <id> command.

Replication Node Restart

Changes to the following Oracle NoSQL Database parameters will result in a Replication Node restart by the Storage Node Agent:

Storage Node parameters:

  • serviceLogFileCount

  • serviceLogFileLimit

  • servicePortRange

Replication Node parameters:

  • configProperties

  • javaMiscParams

  • loggingConfigProps