Installation Configuration Parameters

Before you configure Oracle NoSQL Database, you should determine the following parameters for each Storage Node in the store. Each of these parameters are directives to use with the makebootconfig utility:

root

Where the KVROOT directory should reside. There should be enough disk space on each storage node to hold the data to be stored in your Oracle NoSQL Database store. The KVROOT disk space requirements can be reduced if the storagedir parameter is used to store the data at a different location outside the KVROOT directory. We recommend that you make the KVROOT directory the same local directory path on each node (but not a shared or NFS mounted directory). The examples in this book assume that the KVROOT directory already exists.
port

The TCP/IP port through which the Storage Node should contact the Oracle NoSQL Database. This port should be free (unused) on each storage node. The examples in this book use port 5000. This port is sometimes referred to as the registry port.
harange

The Replication Nodes and Admin process use the harange (high availability range) ports to communicate between each other. For each Storage Node in the store, specify sequential port numbers, one port for each Replication Node on the Storage Node, plus an additional port if the Storage Node hosts an Admin. The Storage Node Agent manages this allotment of ports, reserving one for an Admin service, if needed, and allocating the rest with one port for each Replication Node. Specify the port range as startPort, endPort. After using port 5000 for the Storage Node itself, this document uses values 5010,5020 for examples, with one for the Admin service, and one for the Replication node.
servicerange

A range of ports that a Storage Node uses to communicate with other administrative services and its managed services. This optional parameter is useful when Storage Node services must use specific ports for a firewall or other security purposes. By default, the services use anonymous ports. Specify this port range as value string as startPort,endPort. For more information, see Storage Node Parameters.
store-security

Specifies whether security is in use. While this is an optional parameter, we strongly advise that you configure Oracle NoSQL Database with security in mind.

Specifying none indicates that security will not be in use.

Specifying configure indicates that you want to configure security. The makebootconfig process will then invoke the securityconfig utility as part of its operation.

Specifying enable indicates security will be in use. However, you will need to either configure security by utilizing the security configuration utility, or by copying a previously created configuration from another system.

Note:

The -store-security parameter is optional. If you do not specify this parameter, security is configured by default. To complete a secure installation, you must use the securityconfig utility to create the security folder before starting up the Storage Node agents. For more information, see Configuring the KVStore.
capacity

The total number of Replication Nodes the Storage Node can support. Capacity is an optional, but extremely important parameter, representing the number of replication nodes. If the Storage Node you are configuring has the resources to support more than a one Replication Node, set the capacity value to the appropriate number. As a general heuristic, hosting Replication Nodes successfully requires sufficient disk, cpu, memory, and network bandwidth to satisfy peak runtime demands.

To have your Storage Node host Arbiter Nodes, set the capacity to 0 . Then, the pool of Storage Nodes configured to host Arbiter Nodes within a zone, will be allocated as Arbiter Nodes whenever required. For more information see Deploying an Arbiter Node Enabled Topology.

Consider the following configuration settings for Storage Nodes with a capacity greater than one:
1. We recommend configuring each Storage Node with a capacity equal to the number of available disks on the machine. Such a configuration permits the placement of each Replication Node on its own disk, ensuring that Replication Nodes on the Storage Node are not competing for I/O resources. The –storagedir parameter lets you specify the directory location for each Replication Node disk.
  
  For example:
```
> java -Xmx64m -Xms64m \
    -jar <KVHOME>/lib/kvstore.jar makebootconfig \
    -root /opt/ondb/var/kvroot \
    -port 5000 \
    -host node10
    -harange 5010,5025 \
    -capacity 3 \
    -admindir /disk1/ondb/admin01 \
    -admindirsize 200-MB \
    -storagedir /disk1/ondb/data \
    -storagedir /disk2/ondb/data \
    -storagedir /disk3/ondb/data \
    -storagedirsize 1_tb \
    -rnlogdir /disk1/ondb/rnlog01 \
    -rnlogdir /disk2/ondb/rnlog02 \
    -rnlogdir /disk3/ondb/rnlog03 
```
  where -capacity 3 represents the number of disks on the Storage Node (node10). The disks are (disk1, disk2, disk3).
2. Increase the –harange parameter to support additional ports required for the Replication and Admin Nodes.
3. Increase the –servicerange parameter to account for the additional ports required by the Replication Nodes.
The capacity value indicates the number of –storagedir parameters you must specify. Otherwise, the value defaults to 1. The examples in this document use 1 as the capacity.
admindir

The directory path to contain the environment associated with a Storage Node Admin process.

We strongly recommend that the Admin directory path resolves to a separate disk. You can accomplish this by creating suitable entries in the /etc/fstab directory that attaches the file system on disk to an appropriate location in the overall directory hierarchy. Placing the Admin environment on a separate disk ensures that the Admin is not competing for I/O resources. It also isolates the impact of a disk failure to a single environment.
If you do not specify an explicit directory path for -admindir, the Admin environment files are located in this directory:
```
   KVROOT/KVSTORE/<SNID>/<AdminId>/
```
admindirsize

The size of the Admin storage directory. This is optional but recommended. For more information, see Managing Admin Directory Size.
storagedir

A directory path that will contain the environment associated with a Replication Node. When the –capacity parameter is greater than 1, you must specify a multiple set of –storagedir parameter values, one for each Replication Node that the Storage Node hosts. Each directory path should resolve to a separate disk. You can accomplish this by creating suitable entries in the /etc/fstab directory that attaches the file system on disk to an appropriate location in the overall directory hierarchy. Placing each environment on a separate disk ensures that the shards are not competing for I/O resources. It also isolates the impact of a disk failure to a single location.

If you do not specify explicit directory locations, the environments are located under the KVROOT directory.
storagedirsize

The size of each storage directory. We strongly recommend that you specify this parameter for each Replication Node. The Oracle NoSQL Database uses the storage directory size to enforce disk usage, using the –storagedirsize parameter value to calculate how much data to store on disk before suspending write activity. For more information, see Managing Storage Directory Sizes.
rnlogdir

The directory path to contain the log files associated with a Replication Node. For capacity values greater than one, specify multiple rnlogdir parameters, one for each Replication Node that the Storage Node is hosting.

We recommend that each rnlogdir path resolves to a separate disk partition on a Replication Node. You can accomplish this by creating suitable entries in the /etc/fstab directory that attaches the file system on a disk to an appropriate location in the overall directory hierarchy. Placing rnlogdir in a distinct partition on the Replication Node ensures that metrics and errors can be reported and retained, even if the partition containing the JE log files is full. Separating the rnlogdir on a distinct partition also isolates the impact of losing complete Replication Node log files from a kvroot disk failure.

If you do not specify a location for rnlogdir, logs are placed under the KVROOT/KVSTORE/log directory by default.
num_cpus

The total number of processors on the machine available to the Replication Nodes. This is an optional parameter, used to coordinate the use of processors across Replication Nodes. If the value is 0, the system queries the Storage Node to determine the number of processors on the machine. The default value for num_cpus is 0, and examples in this document use that value.
memory_mb

The total number of megabytes of memory available to the Replication Node. The system uses the memory_mb value to guide specification of the Replication Node's heap and cache sizes. This calculation is more critical if a Storage Node hosts multiple Replication Nodes, and must allocate memory between these processes. If the value is 0, the system attempts to determine the amount of memory on the Replication Node. However, the amount of memory value is available only when the JVM used is the Oracle Hotspot JVM. The default value for memory_mb is 0, and examples in this document use that value.
force

Specifies that the command generates the boot configuration files, even if verifying the configuration against the system finds any inaccurate parameters.

Configuring Your KVStore Installation

Once you determine your configuration information as described in the previous section (see Installation Configuration Parameters), complete the following tasks to configure your store. One of the tasks to complete is to start the SNA on each storage node.

Note:

Before starting the SNA, on each node, set the environment variable MALLOC_ARENA_MAX to 1. Doing this ensures that memory usage is restricted to the specified heap size.

Create the initial bootconfig configuration file using the makebootconfig utility. Do this on each Oracle NoSQL Database node.

Note:
Using the makebootconfig command to create the configuration file is integrated with the Storage Node on which you run the command. Such integration checks and validates all parameters and their values against the SN environment before generating the boot configuration files. To bypass verifying any parameters or values for the boot configuration files, use the -force flag (makebootconfig -force).

Following is an example of using makebootconfig, using a standard set of parameters and values. For a list of all the makebootconfig parameters, see makebootconfig.
```
> mkdir -p KVROOT 
> java -Xmx64m -Xms64m \
-jar <KVHOME>/lib/kvstore.jar \
makebootconfig -root KVROOT \
               -port 5000 \
               -host <hostname> \
               -harange 5010,5020 \
               -capacity 1 \
               -admindir /export/admin \
               -admindirsize 2000_MB \
               -storagedir /export/data1 \
               -storagedirsize 1_tb \
               -rnlogdir /export/rnlogs
```
Note:
We strongly recommend that you specify both storagedir and storagedirsize. If you specify the -storagedir parameter, but not -storagedirsize, makebootconfig displays a warning.

For more information about the makebootconfig command, see Configuring Security with Makebootconfig in the Security Guide.

Use the securityconfig tool to create the security directory (also creates security related files):

java -Xmx64m -Xms64m 
-jar <KVHOME>/lib/kvstore.jar 
securityconfig \
config create -root KVROOT -kspwd (******)
Created files
KVROOT/security/security.xml
KVROOT/security/store.keys
KVROOT/security/store.trust
KVROOT/security/client.trust
KVROOT/security/client.security
KVROOT/security/store.passwd (Generated in CE version)
KVROOT/security/store.wallet/cwallet.sso (Generated in EE version)
Created

See Configuring Security with Securityconfig in the Security Guide.

Note:

Once you configure multiple SNAs after running makebootconfig on each SNA, copy the security directory to the KVROOT of each Oracle NoSQL Database Storage Node Agent (SNA).

scp -r KVROOT/security NODE:KVROOT/

Start the Oracle NoSQL Database Storage Node Agent (SNA) on each of the Oracle NoSQL Database nodes. The SNA manages the Oracle NoSQL Database administrative processes on each node. It also owns and manages the registry port, which is the main way to communicate with Oracle NoSQL Database processes on that storage node. To start the SNA on each storage node use the start utility as follows:
```
nohup java -Xmx64m -Xms64m \
-jar <KVHOME>/lib/kvstore.jar start -root KVROOT &
```
Note:

If the Replication Node or the Admin Service crashes, the SNA restarts the processes.

Use the jps -m command to verify that the Oracle NoSQL Database processes are running :

> jps -m
29400 ManagedService -root /tmp -class Admin -service
BootstrapAdmin.13250 -config config.xml
29394 StorageNodeAgentImpl -root /tmp -config config.xml

Using ssh to reach the node, issue a ping command to be sure that the Oracle NoSQL Database client library can contact the Oracle NoSQL Database Storage Node Agent:

ssh node01
java -Xmx64m -Xms64m -jar <KVHOME>/lib/kvstore.jar ping -host node01 -port 5000 
-security KVROOT/security/client.security

Login as: Anonymous (Enter any user name here)
Anonymous's password: (Enter any password)

SNA at hostname: node01, registry port: 5000 is not registered. 
No further information is available 
Can't find store topology: 
Could not contact any RepNode at: [node01:5000]

This return informs you that only the SN process is running on the local host. Once Oracle NoSQL Database is fully configured, using ping again will provide more details.

If the client library cannot contact the Storage Node agent, ping displays this message:

Unable to connect to the storage node agent at host node01,
port 5000, which may not be running; nested exception is:

java.rmi.ConnectException: Connection refused to host: node01;
nested exception is:
java.net.ConnectException: Connection refused
Can't find store topology:
Could not contact any RepNode at: [node01:5000]

If the Storage Nodes do not start up, review the adminboot and snaboot logs in the KVROOT directory to investigate what occurred and to help identify the problem. If you have not completed the steps in the Configuring Security with Remote Access, the ping command for a secure store is only available locally.

When the Storage Nodes have all started successfully, you can configure the KVStore. For more information on how to configure the KVSTORE, see Configuring the KVStore.

Note:

For best results, configure your nodes so that the SNA starts automatically when the node boots up. The details of how to do this are beyond the scope of this document, because they depend on how your operating system is designed. See your operating system documentation for information about launching application automatically at bootup.