X509-related Utilities and Configurations
A.1 Configuration Parameters specific to X509-Secured GemStone
This section includes configuration parameters that are specific to X509-Secured GemStone. Refer to the System Administration Guide for information on additional configuration parameters that apply to all GemStone systems.
NetLDI configuration Parameters
The following configuration parameters only apply to X509 NetLDIs. They are used in a configuration file passed into the startnetldi -E argument.
NETLDI_PORT_RANGE
Specifies the range of port numbers, which will be used for listening sockets for remote X509 Gems during login. The two elements must be in the port range 1..65535, and the second element must be greater than the first.
NETLDI_PORT_RANGE = 50000, 50020;
If this is not set, or set with the pair of values 10000,65535, random ports in the range used by ephemeral ports will be used. On Linux the ephemeral port range is in /proc/sys/net/ipv4/ip_local_port_range.
NETLDI_START_MIDCACHE
This should be set to true only when starting an X509 secured mid-level cache node.
When set to true, the startnetldi processing, after starting the shared cache on the mid-cache node, then starts a HostAgent process on the mid-cache node, which will log into the Stone’s HostAgent.
NETLDI_HostAgentUser_cert
Required when starting an X509 secured mid-level cache node, or when doing cache warming. The path and name of the cert file for HostAgentUser, HostAgentUser.chain.pem.
NETLDI_HostAgentUser_key
Required when starting an X509 secured mid-level cache node, or when doing cache warming. The path and name of the private key file for HostAgentUser, HostAgentUser.privkey.pem.
NETLDI_WARMER_ARGS
Enables warming a remote X509 leaf or mid-level cache, either from the Stone’s cache or from another mid-level cache. For details, see the description here.
SHR_PUSH_TO_MIDCACHES_THREADS
Enables pushing of pages committed by X509-secured Gems to a mid-level cache. Specified as the number of threads to do the pushing. The allowed range is 0..20. This is normally set in the range 2-5, depending on the network bandwidth between the Stone and mid-level cache hosts. For details, see the description here.
Configuration parameters used for x509 remote caches
In addition to the x509-specific configuration parameters listed above, the following configuration parameters, if set in the configuration file provided with the startnetldi -E argument, are used to configure how the remote cache is started:
GEM_STATMONITOR_MID_CACHE_ARGS
SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY
SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB
Gem Configuration Parameters
GemRemoteCommit
If TRUE, a gem on a remote gem will execute the critical region of commit in the session's thread in the pgsvr or HostAgent on stone host. This avoids latency and decreases network traffic between the Stone and Gem hosts. Can only be enabled, and is the default, if gem and stone host have same byte order.
Runtime name: #GemRemoteCommit
Default: true (for remote X509 Gem on a host with the same byte order as stone host.
Other parameters with specific behavior in X509-secured processes
GEM_PGSVR_COMPRESS_PAGE_TRANSFERS is always true, regardless of the configuration parameter setting, for X509-secured Gems.
GEM_PGSVR_USE_SSL is always true for X509-secured sessions.
When a remote cache is started by a X509-secured NetLDI, the default computation for SHR_PAGE_CACHE_NUM_PROCS on Linux is half of the smaller of the maximum open files or the maximum size of a semaphore array. On other platforms the default is 256.
A.2 Utility details for X509
This section includes additional features of utilities that are specific to X509-Secured GemStone. Refer to the System Administration Guide for information on these utilities, and other utilities that are required to manage a GemStone installation.
gslist
gslist (without -v) reporting on processes the local machine uses only the lock file. Since it does not need to connect to any NetLDI, it treats X509-secured processes no differently than regular GemStone processes.
On the local machine, gslist -v option attempts to connect to a process to verify status. For X509-secured processes, gslist -v reports "OK" if gslist gets a response indicating that an SSL handshake is requested. It does not complete the handshake, and does not require credentials.
gslist for remote nodes
When using gslist -m to request the status of processes on a different node, gslist must have credentials that allow it to connect to the NetLDI on the other node. The following arguments are required to gslist:
-J Specify an X.509 CA certificate file.
-R Specify a private key file.
-U Specify an X.509 certificate file.
For example, on the host remote_host, to query for the GemStone processes running on the Stone’s node stn_host, with the certificate-only NetLDI at port 54321:
unix> gslist -m stn_host -v -N 54321
-U $MyCertDir/remote_host.chain.pem
-R $MyCertDir/remote_host.privkey.pem
-J $MyCertDir/stoneCA-gs64stone.cert.pem
HostAgent information
HostAgents are included in the gslist report on the Stone’s or mid-cache node only when the -H option is used. This avoids an excessive amount of information if there a very large number of HostAgents for remote nodes.
When the -H option to gslist is included, gslist on the Stone’s node includes lines of the form:
exists 3.5.0 gsadmin Feb 26 12:24 hostagent hostagent-gs64stone-10.95.143.15
Mid-level cache HostAgents are:
exists 3.5.0 gsadmin Feb 26 16:49 hostagent hostagent-gs64stone-midcache-remote_host
gslist -x reports detailed information on the HostAgent only if the -H flag is also included.
starthostagent
Once the Stone and the remote NetLDI are started, you execute starthostagent on the Stone’s node. This initiate the steps to authenticate with the remote node, start the HostAgent, and start the remote shared page cache.
starthostagent requires the following arguments:
-J CACertFilePath
Specifies a certificate authority certificate (CA) in PEM format.
-m remoteNodeNameOrIP
The name or IP address of the remote node for which the HostAgent is to be started. A startnetldi -E must have been executed on that remote node.
-N stoneNetLDInameOrPort
The name or port of the NetLDI running on the Stone’s node (the node this script is executing on).
-n remoteNetLDInameOrPort
The name or port of the NetLDI on the remote node remoteNodeNameOrIP. This must have been started using the startnetldi -E (along with other appropriate arguments).
-R privateKeyFilePath
Specifies the host private key chain certificate (for the host named remoteNodeNameOrIP), in PEM format.
-U publicKeyFilePath
Specifies host public key chain certificate (for the host named remoteNodeNameOrIP) in PEM format.
Note that there is no argument to pass in the name of the Stone; the Stone name is determined from the certificate file CACertFilePath, which is passed in with the -J argument.
starthostagent also accepts -h to print help information, and -V to print version information.
startnetldi
The X509-secure NetLDI process has a number of different behaviors and requirements than an ordinary NetLDI. X509-secured NetLDIs only work with X509 remote caches and Gems, and do not support ordinary caches and Gems, and vice versa.
The X509-secured NetLDI on the Stone’s node and the one on the remote node have quite different responsibilities; the Stone’s NetLDI is responsible for starting the HostAgents for remote nodes, and the remote NetLDI is responsible for starting the remote cache and remote Gems.
To start a Netldi using startnetldi, use the -S argument to specify an X509-Secured Netldi, and include the arguments that provide the X509 credentials.
Using startnetldi with the -S argument also requires that you include the -D argument, which provides the default log directory for the processes started during X509 logins.
The following are the startnetldi arguments that specifically support certificate-only mode:
-E configFileName
For use in secure certificate-only mode for a remote NetLDI, not for the Stone’s NetLDI. This enables startup of a remote shared page cache or a mid-level cache on this node.
The specified configuration file includes parameters that define settings for the shared page cache. For mid-level caches, it includes parameters for the mid-level cache.
-J path
Specifies a certificate authority certificate (CA) in PEM format to use. Requires -S.
-L path
Specifies a certificate revocation list (CRL) file in PEM format.Used on the Stone’s NetLDI, not with remote NetLDIs. Requires -S.
-R path
Specifies the host private key in PEM format to use. Requires -S.
-S
start NetLDI in secure certificate mode; must include -D, -J, -R, and -U, and on the remote node, also -E.
-U path
Specifies the host X.509 certificate in PEM format to use. Requires -S.
startnetldi has a number of other command line options, which are required, such as the -D argument to specify log file locations. Refer to the System Administration Guide for details, or see startnetldi -h output.
stophostagent
Stopping a HostAgent requires the same arguments as starting a HostAgent, except the -n is not used. The arguments are:
-J CACertFilePath
Specifies a certificate authority certificate (CA) in PEM format.
-m remoteNodeNameOrIP
The name or IP address of the remote node that the HostAgent is servicing.
-N stoneNetLDInameOrPort
The name or port of the NetLDI running on the Stone’s node (the node this script is executing on).
-R privateKeyFilePath
Specifies the host private key chain certificate (for the host named remoteNodeNameOrIP), in PEM format.
-U publicKeyFilePath
Specifies host public key chain certificate (for the host named remoteNodeNameOrIP) in PEM format.
stophostagent also accepts -h to print help information, and -V to print version information.