6. Administration
This chapter contains additional information that may be useful in managing an X509-Secure GemStone system.
Administering an X509-Secure GemStone system includes additional responsibilities over a regular GemStone environment. The significant tasks are covered in the earlier chapters of this document. You should also be familiar with the basic administration tasks, such as garbage collection, backups, and so on, as described in System Administration Guide.
Topics in this chapter include:
- Managing HostAgents – Getting information about HostAgents and stopping HostAgents.
- Managing Caches – Remote cache timeout, getting details about remote caches, and warming remote caches.
- Managing NetLDIs – Additional information on managing NetLDIs in an X509-Secured configuration.
- Log Files – The location and names of log files in X509-Secured GemStone.
- Other Administration– Other useful information related to administration in X509-Secure Gemstone configurations.
6.1 Managing HostAgents
Information about HostAgents
HostAgents are included in the gslist report on the Stone’s or mid-cache node, when the gslist -H flag is used. gslist on the Stone’s node reports lines of the form:
exists 3.5.0 gsadmin Feb 26 16:24 hostagent hostagent-gs64stone-10.95.143.15
Where the IP is the IP of the remote node that is being serviced by this HostAgent.
From Smalltalk, System class >> hostAgentSessions reports the sessions IDs of running HostAgents.
System class >> descriptionOfSession: for a HostAgent session ID reports 'hostagent' in slot #17, and its listening port in slot #24. The other slots provide the usual details for the HostAgent session.
To find out if the current session is using a HostAgent (and therefor is X509-secured), use
System class >> sessionIsUsingHostagent
To get a report of all HostAgent sessions, use System >> hostAgentSessionsReport. This produces a report with lines containing Host Agent session details, for example:
session 5 hostagent servicing: 10.94.141.15 gemPid: 9848 listeningPort: 46627
Stopping HostAgents
Stopping from the command line
The stophostagent utility will stop a HostAgent process. The command line arguments are the same as the ones used by starthostagent, except -n is not used.
alcatraz> stophostagent -m fiji -N 54321
-U $MyStoneCertDir/alcatraz.chain.pem
-R $MyStoneCertDir/alcatraz.privkey.pem
-J $MyStoneCertDir/stoneCA-gs64stone.cert.pem
Stopping from within the image
System class >> stopUserSessions will stop secure gem sessions, but does not stop the HostAgent session itself.
HostAgents can be stopped using the following methods. The stopHostAgent* methods attempt a graceful shutdown, and return an error if unable to complete. The killhostAgent* methods terminate the HostAgent with a fatal error.
System class >> stopHostAgents
System class >> stopHostAgentSession: sessionId
System class >> stopHostAgentForHost: hostNameOrIp
System class >> killHostAgents
System class >> killHostAgentSession: sessionId
Stopping a HostAgent also stops all x509 sessions using that HostAgent.
6.2 Managing Caches
Timeout of the secure remote cache
With regular GemStone, remote caches can be automatically started or 0restarted when a remote Gem logs in; but with X509-Secured GemStone, since connections are initiated from the Stone’s host, the remote cache must be explicitly started (or restarted, if it has timed out and shut down), by executing utilities on the Stone’s node.
If there are no Gems on the remote node, the remote shared page cache will shut down according to the STN_REMOTE_CACHE_TIMEOUT configuration (by default, 5 minutes).
This also causes the HostAgent on the stone’s node to shut down.
When the HostAgent has been shut down, either by timeout or manually, you must restart the NetLDI on the remote host, then execute starthostagent on the Stone’s node, to reestablish the connection and allow logins to complete.
Mid level caches require explicit stop
Because a mid-level HostAgent is running on the remote node, mid-level remote caches do not timeout. You must manually stop a mid-level cache when you are done with it.
When a mid level cache is connected, stopstone will report that users are logged in; either stop the mid level cache remote hostagents, or use stopstone -i.
Information on caches
System class >> midLevelCachesReport
System class >> remoteCachesReport
include cache types 'x509mid' and 'x509remote', in addition to the existing types 'mid' and 'remote'.
Warming caches on startup
You can configure cache warming on a remote X509-secured cache (leaf cache) or X509-secured mid-level cache by setting a configuration parameter in the configuration file passed with the -E argument to startnetldi.
The configuration parameter NETLDI_WARMER_ARGS can be set to a String, which provide the arguments that control out the cache will be warmed. Cache warming will be done by the page server or host agent on the newly started cache.
If the argument string is empty, no warming is done; otherwise the argument string may contain the following options:
-d include data pages. If not included, only warm object table pages.
-M midCacheHostName
Include this argument if you wish to warm the newly started cache from an already running mid level cache.
If -M specifies a host on which a mid-level cache is running (that is associated with the same Stone), the newly started mid-level cache will be warmed with the pages from the other mid-level cache.
If no -M argument is provided, or if the specified host resolves to localhost or the mid level cache is not found, then pages will be pulled from the stone cache to warm the newly started mid-level cache. Pages pulled from the Stone are based on the current view as of the login of the warmer session.
-n int
the integer number of threads. These must be in the range 1..20 for warming a mid-level cache and in the range 1..2 for warming a leaf cache. This further limits the value for SHR_PUSH_TO_MIDCACHES_THREADS.
NETLDI_WARMER_ARGS = '-d -M adelaide -i4';
When the remote cache is a mid-level cache (NETLDI_START_MIDCACHE=true), multiple pusher threads are started in either the mid cache host agent for the source of the pages, or in the HostAgent on stone host, and those threads scan the source cache pushing pages to the newly started mid cache.
When the remote cache is a leaf cache (that is, it is not a mid-level cache, so NETLDI_START_MIDCACHE=false), the number of threads is limited to 2, since a warmer session on an x509 leaf cache has only a single threaded connection to a mid or stone cache.
You must specify the NETLDI_HostAgentUser_cert and NETLDI_HostAgentUser_key configuration parameters when using cache warming.
Keeping mid-level caches warm
As changes are committed by X509-secured sessions, you can configure your system to have these changes pushed to mid-level caches, ensuring that the mid-level caches contain the latest used pages.
This feature is limited to X509-secured mid level caches and commits performed by X509-secured sessions; changes made, for example, by administrative sessions running in linked mode on the Stone’s node will not get pushed to mid-level caches.
To enable, set the configuration parameter SHR_PUSH_TO_MIDCACHES_THREADS to the number of threads to use. This is normally set in the range 2-5, depending on the network bandwidth between the Stone and mid-level cache hosts.
SHR_PUSH_TO_MIDCACHES_THREADS = 3;
6.3 Managing NetLDIs
Stopping certificate-only NetLDIs
Shutting down the certificate-only NetLDI on the Stone’s node does not disrupt existing HostAgents for remote caches.
If the certificate-only NetLDI on a remote node is shut down, the associated HostAgent and all x509 sessions using that HostAgent will be shut down.
You must restart the NetLDI on the remote host, then execute starthostagent on the Stone’s node, to restart the cache on the remote node.
Multiple NetLDIs
For a given Stone and host, you may have only one certificate-only NetLDI, and each Stone on a given host must have its own separate certificate-only NetLDI.
This differs from ordinary NetLDIs, for which you may have multiple NetLDIs per Stone, or one ordinary NetLDI that services multiple Stones.
You may start one or more ordinary NetLDIs in addition to one certificate-only NetLDI on a host, although this may compromise the security of Stone access.
6.4 Log Files
Processes that support X509-secured GemStone write log files with additional connection information. These can be useful to detect problems in a multi-node system. It is recommended that all log files are written to a single log directory.
Netldi default log file directory
X509-secured NetLDIs require the -D argument to startnetldi, specifying the default log file directory. This simplifies management of log files in a distributed system.
The -D argument is required both for the Stone’s and the remote NetLDIs, and is used for system log files, as well as in composing Gem log file names and locations. It is not used for the NetLDI log itself; this is specified using the -l argument.
Gem logs
X509-secured Gem logs are not written in the user’s home directory.
The Gem created by an X509 login is located by default in the directory supplied to the startnetldi -D argument, and has the default log file name gemPIDnodename.log.
The X509 login parameters include a field directory (Unlike regular GemStone parameters, X509 parameters do not include the Gem NRS, but instead have specific fields for supported features). This directory field overrides the -D setting in startnetldi.
If this directory field is set to a value that includes a %D, the startnetldi -D argument replaces the %D to compose the log and working directory.
HostAgent logs
The HostAgent log is located in the directory specified by -D argument to startnetldi on the Stone’s node (or on the mid-cache node, for mid-cache HostAgents), and has the name:
Other process log files
The other processes associated with the X509-secured remote cache also have different default log file names than those for ordinary remote caches, and are located in the directory specified by the startnetldi -D option.
pgsvrmainPIDnodeName.log
remoteCacheName_PIDpgsvrff_nodeName.log
remoteCacheName_PIDpcmon_nodeName.log
6.5 Other Administration
Requiring UserProfiles to use X509 Authentication
You may specify that individual UserProfiles may only authenticate using X509 logins. Configuring UserProfiles in this way means that no other means of authentication is allowed, ensuring that all accesses are always certificate-based and secure.
System accounts may not be configured in this way.
Note that since X509 does not support linked sessions, users configured with this authentication will not be able to log in a linked.
The following methods set and report the status of this authentication scheme.
UserProfile >> enableX509Authentication
UserProfile >> authenticationSchemeIsX509
The following method has also been added
UserProfile >> x509loginStatus
This method creates a new UserProfile that can only log in using X509 authentication.
UserProfile class >> newX509WithUserId:
Disallowed Operations in a X509 session
Some operations may not be run in an X509 sessions. This includes operations such as markForCollection, objectAudit, fullBackupTo:, and similar operations. These operations will return an error including the phrase. "not allowed when gem is remote with an X509 login".
To run a multi-threaded scan operation in a secure environment, login linked on the Stone’s node.