Setting Store Parameters

Changing Parameters
Setting Store Wide Policy Parameters
Admin Parameters
Storage Node Parameters
Replication Node 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" 

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.

  • adminHttpPort=<Integer>

    Sets the port on which the Oracle NoSQL Database web-based Admin Console is contacted. Examples in this book use port 5001. If the value is 0, the web interface is disabled.

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".

  • memoryMB=<Integer>

    Sets the amount of memory known to be available on this Storage Node, in megabytes. This number is used to inform the allocation of resources equitably among Replication Nodes when capacity > 1. Defaults to "0", which means "unknown." It allows the deployment plan to configure each Replication Node with an appropriate -Xmx heap size.

  • 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.

  • 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).

  • mgmtPollPort=<Integer>

    Sets the port on which the SNMP agent listens.

  • mgmtTrapHost=<String>

    Sets the host to which SNMP notifications are sent.

  • mgmtTrapPort=<Integer>

    Sets the port to which SNMP notifications are sent.

  • 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 should be large enough to accommodate the Storage Node and all the Replication Nodes (as defined by the capacity parameter) hosted on the machines. The number of ports required depends on whether the system is configured for security. For a non-secure system, each Storage Node consumes three ports (including the Registry Service) and each Replication Node consumes three ports in the range. An Admin, if configured consumes 2 ports. On a secure system, one additional port is required for each Storage Node, Replication Node and Admin. As a general rule, 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.

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

    3 (Storage Nodes, adding one for safety) +
    3 * capacity (the number of replication nodes) \
    + 2 (added only if the Storage Node is hosting an admin process as well) 

    For example, if a Storage Node has capacity 1 and is hosting an admin process, the range size must be at least 8. You may want to increase the range size beyond this minimum (in increments of 3). Doing so allows for safety and expansion of the Storage Node without requiring future changes to this parameter. If capacity were 2, the the range size must be greater than or equal to 11. It is best to find a range on the machine that is contiguous. If other services on the host use ports in the range, those will be skipped and the range must be larger.

    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:

    4 (Storage Nodes, adding one for safety) +
    4 * capacity (the number of replication nodes) \
    + 3 (added only if the Storage Node is hosting an admin process as well) 

    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.

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.

  • statsInterval=<Long TimeUnit>

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

  • 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. Such an event produces a popup in the Admin Console, and it is stored in the Admin's database as a critical event. If SNMP or 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.

Security Parameters

The following 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.

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)
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