GemStone Utility Commands

Previous chapter

Next chapter

The GemStone/S 64 Bit utility commands in this appendix are provided in the $GEMSTONE/bin directory.

copydbf

copydbf sourceNRS destinationNRS [ -C | -z | -Z | -c | -u ] [ -E ] [ -f filePrefix ] [ -netLdiName ] [ -pgsvrId ] [ -Mbytes ] [ -l | -| -]

copydbf sourceNRS -i | -I [ -n netLdiName ] [ -p pgsvrId ]

copydbf sourceNRS-W encrCertFN | -X signCertFN | -Y sigFN

copydbf -V sourceNRS [-K keyRingDirs]

copydbf -h | -v

sourceNRS

The source file or raw partition (containing an extent, a transaction log, or a backup file created by fullBackupTo:) as a GemStone network resource string.

destinationNRS

The destination file, directory, or raw partition as a GemStone network resource string. If the destination is a file system directory (the trailing / is optional), a file name is generated and appended to destinationNRS based on the type and internal fileId of the source. Use of /dev/null as the destination is supported only for files as a means of verifying that the file is readable.

-c

Write the transaction log with individual record-level compression. This option only applies to transaction logs. Used by hotstandby utilities.

-C

Write the entire output file compressed, in gzip format; the same as the -z option. The output must be a filesystem file, and you must specify the .gz in the filename.

-E

Ignore disk read errors. If the disk read error occurs while reading an extent root page, the copy will fail. Otherwise, pages of the source file that cannot be read will be replaced with an invalid-page-kind page in the destination file. The destination file may not be usable.

This option only applies to extents, not to transaction logs or backup files.

-f filePrefix

If destinationNRS is a file system directory, then filePrefix overrides the filename prefix that would be generated based on the contents of sourceNRS. If destinationNRS is other than a file system directory, this option has no effect.

-h

Print usage and exit.

-i

Information only. When this option is present without destinationNRS, information about sourceNRS is printed without performing a file copy. If both -i and destinationNRS are present, an error message is printed.

-I

Full information. The same information is printed as for -i. In addition, if the file is a transaction log, all checkpoint times found are listed instead of only the last one.

-K keyRingDirs

For secure backup. List of colon-separated directories which contain keys and certificates, which is used with the -V option to verify the digital signature.

-l

Least-significant-byte ordering for the destinationNRS. This byte ordering is the native byte ordering for Intel processors.

-m

Most-significant-byte ordering for the destinationNRS. This byte ordering is the native byte ordering for Solaris SPARC, AIX POWER, and HP-UX PA-RISC and Itanium processors.

-netLdiName

The name of the GemStone network server; the default is gs64ldi.

-P

Preserve byte ordering. This option creates the destination file using the byte ordering found in the source file. The default is to write the file using the host’s native byte ordering.

-p pgsvrId

The name of a specific runpgsvr (similar to gemnetid).

-s MB

The size (in MB) to pre-allocate the destination file. For instance, -s10 allocates at least 10 MB to the created file. If you do not specify the -s option, the output file is made as short as possible.

-u

Uncompress output records (default is to preserve record-level compression from input); used by hotstandby utilities.

-v

Print version and exit.

-V

For secure backup. Verify the digital signature of a secure backup. Secure backup must be local. This requires including either the -K command line option, or setting the GEMSTONE_KEYRING_TABS environment variable.

-W encrCertFN

For secure backup. Create a new file or files with the given name containing the encryption certificate(s) from a secure backup to file(s). Secure backup must be local. Cannot be used with other write options on a single command line.

-X signCertFN

For secure backup. Create a new file with the given name containing the signing certificate from a secure backup to a file. Secure backup must be local. Cannot be used with other write options on a single command line.

-Y sigFN

For secure backup. Create a new file with the given name containing the digital signature from a secure backup to file. Secure backup must be local. Cannot be used with other write options on a single command line.

-z

Write the output file compressed, in gzip format; the same as the -C option. The output must be a filesystem file, and you must specify .gz in the filename.

-Z

Write the output file compressed, in LZ4 format. The output must be a filesystem file, and you must specify .lz4 in the filename.

To make copies of extent files or transaction logs, the user executing copydbf must have read permission to the file. If you attempt to copy extent files that are in use, if checkpoints are not suspended the resulting repository may be corrupt and unusable. See How To Make an Extent Snapshot Backup for more information.

GemStone repository files on the UNIX file system or to an NFS-mounted drive can usually be copied using the ordinary cp command, as well as using copydbf.

If you are copying between operating systems and the source and destination have different byte ordering, you should use copydbf. You can use the copydbf for disk-to-disk copies between machines when the remote disk is not NFS-mounted; to use copydbf between remote nodes in this case, you must have a NetLDI running on both nodes, and authentication must be configured to allow access.

If the destination is a directory in a file system, copydbf generates a filename based on the type of file. The generated name includes a prefix (extent, tranlog, or backup), a fileId representing an internal sequence number that starts at 0, and the extension .dbf. You can use the -f option to change the prefix.

A message describing the source and destination files is printed to stderr before starting the copy. The size of the destination file is printed to stderr after the copy is completed.

For example:

% copydbf $GEMSTONE/bin/extent0.dbf .
 
Source file: /users/GemStone/data/extent0.dbf
   File type: extent  fileId: 0 
   ByteOrder: Intel (LSB first)  compatibilityLevel: 844 
   Last checkpoint written at: 08/27/2017 19:03:46 PDT.
Destination file:  ./extent0.dbf
   ByteOrder: Intel (LSB first) 
   Clean shutdown, no tranlog needed for recovery.
   Last tranlog written to had fileId 5 ( tranlog5.dbf ).
   File contains 4608 records occupying 75.5 MBytes.

Compression of copydbf output

The output of copydbf can be compressed at the file level using gzip or LZ4 compression (-C|-z|-Z), or compressed at the record level. (-c). Tranlog restore and copydbf can read any of the compression variants.

Record-level compression is used by the hotstandby implementation. The logsender does record-level compression before sending tranlog records to the log receiver. The transmitted tranlogs that are written on the slave system by the logreceiver are record-level compressed. File-level zip/LZ4 compressed tranlogs are converted into record-level compressed tranlog records by the logsender.

Using copydbf to access information on a file

To obtain the same source file information (but not the size) without making a copy, use the second form of the command: copydbf -i sourceNRS. In this usage, you do not specify a destinationNRS.

The following copydbf -i example displays information for an extent, and indicates the oldest transaction log that would be needed to recover from a system crash:

% copydbf -i extent0.dbf
  
Source file: extent0.dbf
   File type: extent  fileId: 0 
   ByteOrder: Intel (LSB first)  compatibilityLevel: 844 
   Last checkpoint written at: 08/04/2017 19:03:46 PDT.
   Oldest tranlog needed for recovery/restore is fileId 5 ( tranlog5.dbf ).
   Extent was shutdown cleanly; no recovery needed.

The next example displays information for a backup, and indicates the oldest transaction log that would be needed to restore subsequent transactions.

% copydbf -i backup.dat
 
File type: backup  fileId: 0 
   ByteOrder: Intel (LSB first)  compatibilityLevel: 850 
   The file was created at: 08/27/2017 19:03:46 PDT.
   Full backup started from checkpoint at: 08/27/2017 19:03:46 PDT.
   Oldest tranlog needed for restore is fileId 2 ( tranlog2.dbf ).
   Backup was created by GemStone Version: 3.2.0 .

To obtain the size of a repository file in a raw partition, use this form:

% copydbf sourceNRS destinationNRS

For a listing of all checkpoints recorded in a transaction log, use copydbf -I sourceNRS. This information is helpful in restoring a GemStone backup to a particular point in time. For example:

% copydbf -I tranlog5.dbf
 
Source file: tranlog5.dbf
   File type: tranlog  fileId: 5 
   ByteOrder: Intel (LSB first)  compatibilityLevel: 933 
   The file was created at: 08/27/17 11:49:05 PST.
   The previous file last recordId is  36 .
   Scanning file to find last checkpoint...
   Checkpoint 1 started at: 08/27/17 11:54:35 PST.
     oldest transaction references fileId -1 ( this file ).
   Checkpoint 2 started at: 08/27/17 11:56:17 PST.
     oldest transaction references fileId -1 ( this file ).
   Checkpoint 3 started at: 08/27/17 11:58:30 PST.
     oldest transaction references fileId -1 ( this file ).
   Checkpoint 4 started at: 08/27/17 12:03:01 PST.
     oldest transaction references fileId -1 ( this file ).
   File contains 69 records occupying 35328 bytes.

copydbf with remote nodes

You must give an NRS (network resource string) for both the source file and the destination. A local machine file specification is a valid NRS.

In the following example, the local GemStone repository file “extent0.dbf” is copied to a remote machine using a full destinationNRS. In this example, the repository file is copied to a remote machine named “node,” using remote user account “username” and “password,” with a remote filespec of “/users/path/extent0.dbf_copy,” via the standard GemStone network server gs64ldi using TCP protocol:

% copydbf $GEMSTONE/data/extent0.dbf
\!@node#auth:username@password#dbf\!/users/extent0.dbf_copy

copydbf with raw partitions

copydbf of backup files to raw partitions is not supported.

The next example copies a fresh repository extent to an existing raw disk partition. If the raw partition already contains a repository file or backup, use removedbf first to mark it as being empty.

% copydbf $GEMSTONE/bin/extent0.dbf /dev/rsd3h

Copying a transaction log from a raw partition to a file system directory generates a file name having the same form as if that transaction log had originated in a file system. If the internal fileId is 43, this example would name the destination file /dsk1/tranlogs/tranlog43.dbf:

% copydbf /dev/rsd3h /dsk1/tranlogs/

gslist

gslist [ -c ] [ -l | -p | -x ] [ -m host ]+ [ [ -nname ]+ [ -N netldiName ] [ -q ] [ -s key|-S key ] [ -t secs ] [ -u user ] [ -v ]

gslist -h | -V

-c

Removes locks left by servers that have been killed.

-h

Print usage and exit.

-l

Prints a long listing (includes pid and port).

-m host

Only list servers on machine host; default is ‘.’ which represents the local host. If not the local host, the machine host must be running a compatible version of NetLDI, and the -N argument is required if it is not running with the default name in the environment of gslist.

-n name

Only list the server name.

-N netldiName

When -m is used, -N specifies name of netldi to contact on remote host. Default is name specified in GEMSTONE_NRS_ALL environment variable, otherwise name is 'gs64ldi'.

-p

Prints only the pid (process id), or 0 if the server does not exist.

-q

(Quiet.) Don’t print any extra information; intended for use when the output will be processed by some other program.

-s key

Sort results by the given sort key. Legal key values:

 

name   sort by process name (default).

owner   sort by process owner.

time   sort by process start time.

type   sort by process type.

version   sort by process version.

-S key

Same as -s except results are sorted in reverse order.

-t secs

Wait secs seconds for server to respond (only with -v); default is 2 seconds.

-u user

Only list servers started by user.

-v

Verify the status of each server.

-V

Print the version information and exit.

-x

Prints an exhaustive listing, with each item on a separate line.

The gslist command prints information about GemStone servers. The default listing prints the following server attributes in columns:

Status

One of the following:

 

contRestore   Continous restore for hot standby (-v only)

exists   server process exists but is not verified

frozen  server is not responding (-v only)

full   server can’t accept any more clients (-v only)

killed   server process does not exist

OK   server is accepting clients (-v only)

restoreBkup server is in restore from backup (-v only)

restoreLogs  server is in restore from logs mode (-v only)

recovery   Restart after unclean shutdown in progress (-v only)

startup   server process is not yet accepting clients (-v only)

Version

GemStone version of the server.

Owner

The account name of the user who created the server.

Started

The date and time that the server was started.

Type

One of the following: Netldi, Stone, cache (shared page cache monitor), logsender, logreceiver

Name

The server’s name.

When you include the -l or -x option, the following additional columns are printed:

Pid

The process id of the server’s main process.

Port

The port number of the server’s listening socket.

The -x option prints the preceding attributes on separate lines, and adds lines for the following as appropriate:

options

Options used when the server was started.

logfile

Full path of server’s log file, if it exists.

sysconf

The GemStone system configuration file . See System Configuration File.

execonf

The GemStone executable configuration file. See Executable Configuration File.

GEMSTONE

Root of the product tree used by the server.

If many servers are reported as frozen, try increasing -t secs.

By default, status is returned for all servers on the current host. To specify a particular server, use the -n switch, or just include the server name on the command line (since the -n is optional). To specify multiple server names, include the -n name option for each server.

Remote queries

The -m option allows you to list servers on a remote host. To specify more than one remote host, include the -m host option multiple times, one for each host. Names on remote hosts are prefixed by host:, where host is the name of the remote machine.

To list servers on a remote host, gslist must be able to contact a NetLDI running on the remote machine.

  • The remote NetLDI must be a GemStone version that is compatible with the version of gslist.

This limitation applies to the remote NetLDI, but not to the Stone and other server processes on the remote host, for which gslist fetches information.

  • The remote NetLDI must be named with the default name, or the -N argument should be included to specify the name.

The default name here is the default for the environment in which gslist is running. This is either “gs64ldi”, or a name specified by $GEMSTONE_NRS_ALL.

Date and Time format

The date and time that the process started is normally printed in a format specific to gslist and fitting into the table display. To get a parse-able but potentially less readable format, you may use the environment variable GS_GSLIST_TIME_FORMAT to specify a UNIX-style date format string.

Exit status

The exit status has the following values:

0       Operation was successful.
1       No servers were found.
2       A stale lock was removed (in response to -c switch).
3, 4   An error occurred.

gslist on Windows

gslist is available for Windows, in addition to regular server platforms, as part of the Windows Client installation. gslist on Windows must be used with the -m option, specifying a hostname for a host that is running GemStone.

pageaudit

pageaudit [ gemStoneName ] [ -e exeConfig ] [ -z systemConfig ] [ -f ] [ -d ] [ -l logfile ] [-h]

gemStoneName

Name of the GemStone repository monitor; the default is gs64stone-audit. Network resource syntax is not permitted.

-d

Disable audit of data pages. Only audit Object Table pages, bitmaps, and other non-data pages.

-e exeConfig

The GemStone executable configuration file. See Executable Configuration File.

-f

Keeps running beyond the first error, if possible

-h

Print usage and exit.

-l logfilename

Write output to the file with the given name. The file is created if it does not exist. If there is an existing file with this name, the pageaudit output is appended to the end of this file.

-n numSessions

Run with the specified number of sessions. The default is numExtents + numCpus.

-systemConfig

The GemStone system configuration file. See System Configuration File.

Audit the pages in a GemStone repository, which must not be in use. pageaudit opens the repository specified by the relevant configuration files. The arguments -e exeConfig, and -z systemConfig determine which configuration files pageaudit reads.

pageaudit by default runs aggressively, using a large number of threads (based on the number of CPUs and extents for this system), in order to complete as quickly as possible; the -n option can be used to specify fewer threads, and reduce the impact on your system.

By default, all pages in the repository are verified; this includes data pages as well as Object Table, bitmap, and other pages containing internal information. Audit of data pages can be disabled using the -d option.

An error is returned if another Stone is running as gemStoneName or has opened the same repository.

When you include the -f switch, pageaudit prints all errors possible. Without -f, the default is to stop after the first error is found.

This utility can take a long time to run, so it is best to run it as a background job.

For additional information about pageaudit and a description of its output, see Page Audit.

pstack

pstack [ -b | -c | -C | -h ] processPid

processPid

The PID of a running GemStone process.

-b

Print brief C and Smalltalk stacks.

-C

Print brief C stack, omit Smalltalk stack.

-c

Print brief and full C stack, omit Smalltalk stack.

-h

Print usage and exit.

The pstack command attaches a debugger to the process with the given pid, outputs the C and Smalltalk stacks of that process to stdout, and detaches. The Smalltalk stack is printed to the Gem log or topaz linked session console.

Execution of the running process briefly pauses while the debugger is attaching, but the process will subsequently continue running normally.

pstack is similar to functions provided with some OS platforms.

By default, the stack summary is printed with one line per frame for each thread, followed by the complete stack details. The -b and -C options allow you to specify brief format stacks.

By default, both C stack and (if there is a Smalltalk context) Smalltalk stacks are printed. The -c and -C options allow you to omit the Smalltalk stack.

removedbf

removedbf dbfNRS [ -h ]

dbfNRS

The GemStone repository filename or device, as a network resource string, for the repository to be removed.

-h

Print usage and exit.

This command removes (erases) a GemStone repository file. It is provided primarily for erasing an extent or transaction log from a raw partition, but it also works on files in the file system. It does not work for disks on remote file systems.

If you specify a file in the file system, this command is equivalent to the rm command. If you specify a raw disk partition, GemStone metadata in the partition is overwritten so that GemStone will no longer think there is a repository file on the partition.

For example, to remove an extent on the raw partition /dev/rsd3h:

removedbf /dev/rsd3h 

This command does not disconnect an extent from the logical repository. To alter the configuration by disconnecting an existing extent, see To Remove an Extent.

startcachewarmer

startcachewarmer [ -d | -D ] [ -h ] [ -l limit ] [ -L path ] [ -n numSessions ] [ -s stoneName ] [ -w writeInterval ] [ -W ] [  -C midCacheSizeKb ] [ -e gemConfigPath ] [ -H stoneHost ] [ -M midCacheHost ] [ -N midCacheMaxProcs ]

-C midCacheSizeKb

The size of the mid-level cache in KB (default 75000). Only used if the -M option is specified and the mid-level cache does not exist.

-d

Reads data pages into the cache (default: only object table pages are read).

-D

Reads data pages into the UNIX file buffer cache and not the shared page cache.

-e gemConfigPath

path to a gem config file, by default gem.conf in the current directory. Used to specify a shared cache configuration, if the warmer starts a remote or mid-level cache.

-h

Print usage and exit.

-H stoneHost

The host name or IP address where the stone is running. This option should only be used when warming a remote cache.

-l cacheFullLimit

Stops cache warming if the number of free frames in the cache falls below the specified cacheFullLimit. If cacheFullLimit is -1 (the default), have the system compute the actual limit based on the size of the shared cache. If cacheFullLimit is 0, force cache warming to continue even if the shared cache is full.

-L path

Path to a writable log file directory (default: current directory)

-M midCacheHost

The host name or IP address where the mid-level cache is running or will be created. The -H option must also be specified with this option (default: no mid-level cache is used)

-numSessions

Number of worker sessions to start. The default is the number of CPUs + number of Extents, plus 1 additional master session. The cachewarmer will exit if not enough sessions are available.

-N midCacheMaxProcs

The maximum number of processes that can use the mid-level cache (default: 50). Only used if the -M option is also specified and mid-level cache does not exist.

-s stoneName

Name of the running Stone (default: gs64stone).

-W

Wait for cache warming Gems to exit before exiting this script. By default, this script spawns Gems in the background and exits immediately.

-w writeInterval

Instruct the shared page cache monitor to write the ids of all data pages in the shared cache to the working set file, at the given interval in minutes. A value of 0 means write the file only when the stone is shutdown or killed. The working set is written to /opt/gemstone/locks/stoneName~hostid.workingSet.lz4

The startcachewarmer command warms up the shared page cache on startup, by preloading object and optionally data tables into the cache. This allows the overhead of initial page loading to occur in a controlled way on system startup, rather than more gradually as the repository is in use.

The object table and dependency map pages are always loaded; data pages are loaded based on the -d flag and the presence of the working set file.

The -d and -D flags are mutually exclusive, if both are specified, then the later one is used.

Cache warming writes messages to stone log when it starts and with status when it completes. When the -W option is specified, it will also write the results to the console. If an error occurs during cache warming, details are preserved in a file named stonename_cachewarmer.log in the directory from which this utility was executed.

If a remote shared page cache is to be warmed (i.e., the -H option is used), then the remote cache will be created if it does not already exist. The configuration used to start the remote cache are controlled by the -e argument, a gem.conf in the current directory, or the GEMSTONE_EXE_CONF environment variable.

If a mid-level cache host name or IP address is specified (via -M), the mid-level cache will be created if it does not already exist. The -C and -N options will be used to specify the size and number of processes that can attach the mid-cache respectively. If the mid-cache already exists, the -C and -N options are ignored.

For greater efficiency, you can set the configuration file parameters STN_CACHE_WARMER_ARGS, GEM_CACHE_WARMER_ARGS, and GEM_CACHE_WARMER_MID_CACHE_ARGS to invoke cache warming automatically on startup.

startlogreceiver

startlogreceiver -P listeningPort -A listeningAddress -T tranlogDir+ [ -l logFile ] [ -s stoneName ] [ -p alternatePort ] [ -d ] [ -t timeoutSeconds ] [ -v ] [ -h ] [ -C certFileName ] [ -J certAuthFileName ] [ -K  keyFileName ] [ -Q passphrasestring ] [ -S ] [ -V ]

-A listeningAddress

Address that will be used to attempt connection to a logsender.

-d

Print debug tracing of tranlog read and write operations to log file. The log file will be much larger.

-l logFileOrDir

The path and filename or directory for the logged output of the logreceiver process. The default is /opt/gemstone/log/logreceiver_listeningPort.log.

-h

Print usage and exit.

-P listeningPort

Port or named service that will be used to attempt connection to a logsender.

-p alternatePort

The logreceiver listens on localhost on this port for stoplogreceiver commands. If logsender and logreceiver are run on same machine, then -p must be used to specify a port different than listeningPort specified with the -P argument.

-s stoneName

The name of the slave stone. stoneName is required for the logreceiver to be able to notify a stone in continuous restore mode that new log records have arrived. Without stoneName, logreceiver will just write tranlogs to the file system.

-T tranlogDir

Directory(s) where logreceiver writes files received from the logsender, and continuousRestoreFromArchiveLogs: will read from. At least one is required, up to 20 -T may be specified.

-t timeoutSeconds

How long the logreceiver will wait for logsender to reply to commands. The default is 60; the legal range is 5 to 1000000.

-v

Print version and exit.

Additional arguments for SSL:

-C certFileName

Certificate in PEM format that will be sent to the peer upon request.

-J certAuthFileName

Certificate authority (CA) file in PEM format to use for peer certificate verification.

-K keyFileName

Private key in PEM format for the certificate (associated with the -C certificate).

-Q passphrasestring

Private key passphrase. Required if the -K option is used and the private key is encrypted.

-S

Enable SSL mode. Must be specified to use any other SSL options and must also be specified when starting the peer process.

-V

Disable verification of the peer's certificate.

This utility starts up a logreceiver process. As part of a hot standby setup, the logreceiver process runs on the slave system to receive transaction log records, as they are generated, from a logsender process that is running on a master system.

The received transaction log records are written to files in a specified directory on the slave system. The slave system can run continuousRestoreFromArchiveLogs: to restore these transaction log records.

The logreceiver writes logging output to a file with the path and name or in the directory specified by the -l argument. If this file is a directory, the file name is logreceiver_listeningPort.log. If no -l argument is used, it writes to /opt/gemstone/log/logreceiver_listeningPort.log. If a file with the specified name exists, it is appended to. It is not deleted on process exit.

The logreceiver process will continue running until explicitly stopped using the stoplogreceiver command. If connection to the stone or the logsender process is lost, it will attempt to reconnect.

gslist will report running logreceiver processes.

To start the logsender using SSL to establish a secure connection between logsender and log receiver, both startlogsender and startlogreceiver can be provided with SSL credentials. When SSL arguments are provided, startlogreceiver will start the logreceiver in secure mode, requiring an SSL connection with the logsender. This is described under Connecting using SSL Mode

startlogsender

startlogsender -P listening port -A listeningAddress+ -T tranlogDir+ [ -l logFile ] [ -s stoneName ] [ -u ] [ -d ] [ -v ] [ -h ] [ -C certFileName ] [ -J certAuthFileName ] [ -K keyFileName ] [ -Q passphrasestring ] [ -S ] [ -V ]

-A listeningAddress

The address (es) on which the logsender will listen for connections from logreceivers. At least one is required, up to 4 may be specified.

-d

Print debug tracing of tranlog read and write operations to log file. The log file will be much larger.

-l logFileOrDir

The path and filename or directory for the logged output of the logsender process. The default is /opt/gemstone/log/logsender_listeningPort.log.

-h

Print usage and exit.

-P listeningPort

The port or named service on which on which the logsender will listen for connections from logreceivers.

-s stoneName

The name of the master stone. stoneName is required for the logsender to detect that stone has written new data to the master tranlogs. Without stone name, logsender will transmit tranlogs that it finds on the file system when it starts up.

-T tranlogDir

Directory(s) where the master stone’s transaction logs are located. Normally the same as stone's STN_TRAN_LOG_DIRECTORIES but may also include archive directories. logsender will examine these directories for new files to send. At least one is required, up to 20 -T may be specified.

-u

Do not compress tranlog files at record level before transmission.

-v

Print version and exit.

Additional arguments for SSL:

-C certFileName

Certificate in PEM format that will be sent to the peer upon request.

-J certAuthFileName

Certificate authority (CA) file in PEM format to use for peer certificate verification.

-K keyFileName

Private key in PEM format for the certificate (-C option).

-Q passphrasestring

Private key passphrase. Required if the -K option is used and the private key is encrypted.

-S

Enable SSL mode. Must be specified to use any other SSL options and must also be specified when starting the peer process.

-V

Disable verification of the peer's certificate.

This utility starts up a logsender process. As part of a hot standby setup, the logsender process runs on the master system to transmit transaction log records, as they are generated, to a logreceiver process that is running on a slave system.

The logsender writes logging output to a file with the path and name or in the directory specified by the -l argument. If this file is a directory, the file name is logsender_listeningPort.log. If no -l argument is used, it writes to /opt/gemstone/log/logsender_listeningPort.log. If a file with the specified name exists, it is appended to. It is not deleted on process exit.

The logsender process will continue running until explicitly stopped using the stoplogsender command. If connection to the stone is lost, it will attempt to reconnect.

gslist will report running logsender processes.

To start the logsender using SSL to establish a secure connection between logsender and log receiver, both startlogsender and startlogreceiver can be provided with SSL credentials. When SSL arguments are provided, startlogsender will start the logsender in secure mode, requiring an SSL connection with the logreceiver. This is described under Connecting using SSL Mode.

startnetldi

startnetldi [ netLdiName ] [ -g | [ -s ] [ -k keytab ] ] [ -a name ] [ -A addresses ]+ [ -b ] [ -d ] [ -directoryPath ] [ -l logFile ] [ -n ] [ -P portNumber ] [ -r ] [ -t timeout ]

startnetldi  -h | -v 

netLdiName

The name or port number of the GemStone network server.
If netLdiName is a numeric value equal to or less than 65535, it is interpreted as a port number. If the given port is in use, it will result in an error. Other values are interpreted as the netldi name. If the -P argument is omitted, this name is looked up in the network services database to determine the port number. Network resource syntax is not permitted. The default is gs64ldi.

-a name

Captive account; all child processes created by the NetLDI will belong to the account named name. By default, child processes belong to the client’s account.

-A addresses

Address to listen on. Up to 10 arguments are accepted. If no -A arguments are provided, listening is on the default wildcard address ::. If this default wildcard address is included, then other -A arguments are ignored. If the -A entry arguments do not include :: or ::1, then ::1 is also listened on.

-b

Maximum client connection backlog (default: 64).

-d

Debug mode; inserts more extensive messages in the log file.

-D directoryPath

Specifies a directory that will be used to compose log file paths for process log files for processes whose NRS includes the %D placeholder. When spawning a child process, the %D in the NRS is replaced with directoryPath before forking.

-g

Guest mode; no accesses are authenticated. This option is not allowed if the NetLDI’s effective user id is the root account. Not compatible with -k.

-h

Print usage and exit.

-k

Enable Kerberos and set the keytab file name; logins with empty host password will authenticate using Kerberos. Not compatible with -g.

-l logFile

The logged output of the NetLDI; the default is
/opt/gemstone/log/NetLdiName.log

-n

Do not allow any ad hoc processes to be created (ad hoc processes are ones not listed in $GEMSTONE/sys/services.dat).

-N

Use numeric IP addresses for printing peer info in logs, do not do reverse DNS lookups to get hostnames of clients.

-P portNumber

The well-known port number that netldi will use.

-r

If there is a running NetLDI (version 3.3 or above) with this name, and that NetLDI has different version than specified in the current environment, stop the running NetLDI and restart it.

-s

Secure; require authentication for all NetLDI accesses.

-t timeout

Seconds to wait for a spawned client to start, such as a Gem; default is 30 seconds.

-v

Print version and exit

This command starts a GemStone network server with the specified netLdiName and timeout (given in seconds). The server spawns GemStone processes in response to login requests from remote applications and requests for remote repository access from Stone repository monitor processes. If your machine is slow or heavily loaded, and RPC logins time out before completing, specify a larger timeout value.

Legal characters in a NetLDI name are A-Z, a-z, 0-9, and the characters period, underscore, and dash (. _ -). NetLDI names with other characters are disallowed. NetLDI names should not start with period or dash, and should include at least one letter or digit. Also, NetLDI names must not match an existing system service, such as ldap, syslog, etc.

The NetLDI listens for requests, including RPC login requests, on a specified or configured port and optionally on a specific address. During the RPC login process, it uses a separate set of ports to establish communication between the Gem and its client. If you are running over a firewall, you can specify the port using the -P option, and configure your firewall to permit access via this port.

The locations and names of log files for process started by the NetLDI are defined by NRS directives in the login parameters or by settings in the GEMSTONE_NRS_ALL. Using the -D logfile argument to startnetldi sets a variable within the NetLDI, which can be optionally specified in the login parameters or GEMSTONE_NRS_ALL using the %D pattern.

NetLDI can be configured to authenticate starting processes, or all accesses. It may configure to authenticate the UNIX userId (including by using Kerberos) or to run in guest mode, which does not authenticate. These options work in conjunction with permissions for the extent files to provide security while also ensuring the appropriate access to GemStone for authorized users. How to configure the NetLDI is described in Chapter 4, “NetLDI and Interprocess Access”.

For assistance with startup failures, refer to To Troubleshoot NetLDI Startup Failures.

netldid

$GEMSTONE/sys/netldid is the executable that is invoked by startnetldi. While startnetldi blocks until startup is complete, then returns control to the command line, executing netldid directly does not return. This can allow you to run the NetLDI as a background process.

The options described for startnetldi are also available for netldid, with the exception of -r.

startstone

startstone [ gemStoneName ] [ -l logFile ] [ -e exeConfig ] [ -z systemConfig ] [ -h | -v ] [ -R ] [ -N ]

gemStoneName

Name of the GemStone repository monitor, default is gs64stone. Network resource syntax is not permitted.

-C

startup for conversion; only applies when starting up a version that requires conversion. Refer to the Installation Guide for the specific version for details.

-e exeConfig

The GemStone executable configuration file. See Executable Configuration File.

-h

Print usage and exit.

-l logFile

The location (or filename) for the logged output of the stone; the default is (1) the setting of the GEMSTONE_LOG environment variable, if defined; (2) $GEMSTONE/data/gemStoneName.log

-N

Do not replay transaction logs as part of startup. Unless used with the -R option, and transaction logs are replayed manually, work may be lost.

-R

Start up from the most recent checkpoint and go into restore mode. This allows transaction logs to be restored. Used when restoring from backup.

-v

Print version and exit

-z systemConfig

The GemStone system configuration file. See System Configuration File.

This command opens the GemStone repository specified by the configuration files. For details on how startstone determines which the configuration file/s to use, see How GemStone Uses Configuration Files.)

Legal characters in a Stone name are A-Z, a-z, 0-9, and the characters period, underscore, and dash (. _ -). Stone names with other characters are disallowed. Stone names should not start with period or dash, and should include at least one letter or digit. Also, Stone names must not match an existing system service, such as ldap, syslog, etc.

The -N option is intended for use when the repository needs recovery, but the transaction logs specified in the configuration file cannot be found or have become corrupted. The -N forces the repository to start up anyway, even though transactions committed since the last checkpoint will be lost.A new transaction log will be initialized as part of the startup.

The -R option is used when restoring from backup. This starts up the repository at the point of the most recent checkpoint in the extents, and puts the repository into restore mode. You can then invoke Topaz to restore from transaction logs and commit the restored state.

If the extents against which Stone is being started require recovery, or if you are restoring from online extent backups, then you must specify the -N option along with the -R option; otherwise, an error will result and the repository monitor will not start.

For startup failures, refer to To Troubleshoot Stone Startup Failures.

stoned

$GEMSTONE/sys/stoned is the executable that is invoked by startstone. While startstone blocks until startup is complete, then returns control to the command line, executing stoned directly does not return. This can allow you to run the Stone as a background process.

The options described for startstone are also available for stoned.

statmonitor

statmonitor stoneName [ options, see below ]

stoneName

Required; the name of the Stone to monitor.

-A

Collect all available system statistics.

-B count

Number of persistent shared counters to sample. Maximum is 1536, default is 0.

-C

Collect system statistics for each individual CPU.

-d directory

Directory where output files are written. Cannot be used with the -f or -F options; to specify a directory with those options, include it in the filename or pattern.

-D

Collect system statistics for all disks and partitions.

-f fileName

The output file name. By default, the output filename is statmonN.out, where N is the process ID. If this file already exists, statmonitor will append an -N to the filename, where N starts at 1 and increments as needed.

To send output to stdout instead of a file, specify -f stdout.

May not be used with the -d option.

-F pattern

Pattern used to generate the file name. Values in the pattern starting with a single '%' character have the meaning described in the strftime(3) function call. Additionally, the following patterns which start with double '%' characters are also accepted:

   %%C - name of the shared page cache

   %%H - name of the host

   %%i - sample interval in seconds

   %%I - sample interval in milliseconds

   %%P - process ID of statmonitor

   %%S - name of the stone

May not be used with the -d option.

-h

With no argument, print usage and exit.

-h hours

The number of hours (default: forever).

-i interval

The interval in seconds (default: 20). Select either -i or -I.

-I intervalMs

The interval in milliseconds (default 20000; minimum 10). Select either -i or -I.

-J

Sample the Stone, shared cache monitor, and page manager only.

-k listOfTimes

List of times at which statmonitor should be restarted. The restart is performed at the next sample interval after the specified time has passed.

  • Either the -r or -R command must also be specified.
  • List must start and end with a single quote.
  • times include hours and minutes, colon separated.
  • hours are in 24-hour format.
  • Multiple times are comma separated.
  • Duplicates should not be included.

-n numAppStats

The number of application statistics (default: 0).

-N

Collect system statistics for all network interfaces.

-p sessionId

A GemStone sessionId to monitor. You may specify multiple sessions. (Default: monitor all sessions.)

-P

Sample the Stone, shared cache monitor and AIO page server threads only.

-q

Quiet mode. Only print messages if an error occurs.

-Q pid1,pid2,...

Record statistics for a list of process IDs.

-r

Restart a new output file when the current one completes. Each file will be given a unique name. This option may only be used with the -h or -t switches, which control when a restart is done.

-R

Same as -r except the output file name is regenerated for each restart if the -F option is used.

-S

Sample only the Stone and shared cache monitor.

-t times

The maximum number of samples to collect before starting a new output file (default is forever). Select either -h or -t.

-u seconds

The maximum number of seconds to wait before flushing the cached information to the output file (default: 60). If 0 then the flush will be done every interval.

-Uuid1,uid2,...

Record statistics for all processes owned by one or more UNIX user IDs.

-v

Print version and exit

-W

Collect system statistics for system memory pages (Solaris only).

-X

Run in host-only mode. Sample host system statistics only and do not attach to a shared page cache. May be combined with other flags EXCEPT: -m, -n, -p, -P, -S, or -Y.

-Y

Disable collection of all system statistics, including per-process data.

-z

Write the output in compressed gzip format.

-Z

Write the output in compressed lz4 format.

Record statistics for a repository and/or the operating system to a disk file. statmonitor runs in the background, sampling specified data at a specified interval and recording the data to a text file. The data in this file can be viewed by the graphical application VSD. See vsd and the VSD Users Guide for more information.

Statistics are collected from the shared page cache. Only data for GemStone processes attached to the shared page cache on the host on which statmonitor is running are collected. To monitor Gems on systems with remote Gem servers, you must run statmonitor both on the Stone’s machine and on the Gem server machine.

The stonename argument is used to specify the cache to monitor, both for caches that are local to the Stone and caches that are remote from the Stone with that name. Configurations in which a single machine is hosting remote caches for multiple stones that are running with the same Stone name are ambiguous and will not work correctly; this configuration is strongly discouraged.

In addition to running statmonitor from the command line, you can also specify that statmonitor be automatically started at stone startup, and the startup for remote gem caches and remote mid-level caches, to ensure statmonitor data is collected. See the configuration parameters STN_STATMONITOR_ARGS, GEM_STATMONITOR_ARGS, and GEM_STATMONITOR_MID_CACHE_ARGS.

stoplogreceiver

stoplogreceiver -P listeningPort [ -v ] [ -h ]

-h

Print usage and exit.

-P listeningPort

The port that the logreceiver is listening on for stoplogreceiver connections. If -p was used in the startlogreceiver command, that port must be specified here; otherwise the port specified by the -P argument to startlogreceiver.

-v

Print version and exit.

This utility stops a logreceiver process that was started by a previous startlogreceiver command. This may only be executed on the same node as the logreceiver is running.

stoplogsender

stoplogsender -P listeningPort [ -v ] [ -h ]

-h

Print usage and exit.

-P listeningPort

The port on which this logsender is listening. It must be the same port as specified in the -P argument of the startlogsender.

-v

Print version and exit

This utility stops a logsender process that was started by a previous startlogsender command. This may only be executed on the same node as the logsender is running.

stopnetldi

stopnetldi [ netLdiName ] [ -h ] [ -v ]

netLdiName

The name of the GemStone network server; the default is gs64ldi. Network resource syntax is not permitted.

-h

Print usage and exit.

-v

Print version and exit

Gracefully stop a GemStone network server.

If name is not specified, the name of the NetLDI to stop is taken from GEMSTONE_NRS_ALL environment variable, if defined there. If GEMSTONE_NRS_ALL does not define a NetLDI name, then a NetLDI with the default name gs64ldi is stopped.

If a portNumber was used to start the netldi process, then the portNumber can be used to stop the netldi process.

stopstone

stopstone [ gemStoneName [ gemStoneUserName [ gemStonePassword ] ] ] [ -i ] [ -t ] [ -h ]

gemStoneName

The name of the GemStone repository monitor, commonly gs64stone. Network resource syntax is not permitted.

gemStoneUserName

A privileged GemStone user account name, such as “DataCurator” or “SystemUser”.

gemStonePassword

The GemStone password for the specified gemStoneUserName.

-h

Print usage and exit.

-i

Causes any current GemStone sessions to be terminated immediately.

-t

Specifies how long to wait for other processes to detach from the cache. Default is -1, wait forever.

Gracefully shut down a GemStone repository monitor. In the process, a checkpoint is performed in which all committed transactions are written to the extents. If you specify the -i (immediate) option, the repository monitor is shut down even if there are GemStone users logged in. The -t option specifies how long to wait for all session to detach from the cache before returning; if omitted, stopstone will wait forever. If you do not supply the gemStoneName, gemStoneUserName, and gemStonePassword on the command line, this command will prompt you for them.

Because this command uses a Gem session process to connect to gemStoneName, it fails if the Gem is unable to connect for any reason, such as inability to attach a shared page cache. For assistance, refer to To Troubleshoot Session Login Failures.

topaz

topaz [ -h | -v ]

topaz [ -r ] [ -q ] [ -i | -I topazini ] [ -u useName ] [ -- other args ]

topaz -l | -L [ -q ] [ -i | -I topazini ] [ -u useName ] [ -exeConfig ] [ -systemConfig ] [ -tocSizeKB ] [ -C configParams ] [ -- other args ]

-C configParams

Provides configuration parameters, in configuration file syntax, that override settings in the configuration files. Only applies to linked sessions (RPC sessions may use the -C syntax in the Gem’s NRS).

-e exeConfig

The GemStone executable configuration file (only allowed with linked sessions). See Executable Configuration File.

-h

Print usage and exit.

-i

Ignore the initialization file, .topazini.

-I topazini

Specify a complete path and file to a topazini initialization files, and use this rather then any .topazini in the default location.

-l

Invoke the linked version of Topaz.

-L

Invoke the linked version of Topaz, and do not apply any command set gemnetid that may appear in the .topazini file or a file passed in using -I.

-q

Start Topaz in quiet mode, suppressing printout of the banner and other information.

-r

Invoke the RPC (remote procedure call) version of Topaz.

-T tocSizeKB

The GEM_TEMPOBJ_CACHE_SIZE that will be used. Overrides any settings provided in configuration files passed as arguments with the -e or -z options. Only applies to linked sessions.

-u useName

Sets the cache name, as recorded by statmonitor for viewing in VSD. This is also useful for identifying processes in OS utilities such as top or ps.

-v

Print version and exit.

-w

On Windows client only; forces terminal behavior regardless of I/O device.

-systemConfig

The GemStone system configuration file (only allowed with linked sessions). See System Configuration File.

-- otherArgs

Arbitrary text arguments otherArgs may be included after the “--” end of arguments marker, which must follow any of the above topaz arguments are included.

This command invokes various forms of topaz. The default is to invoke the remote procedure call (RPC) version of topaz; to do this explicitly, use the -r option.

To invoke the linked version of topaz, which is recommended or required for some maintenance operations, use the -l or -L option. The advantage of the -L option is that .topazini initialization file command cannot inadvertently configure the login to be RPC rather than linked.

Several topaz arguments only apply in linked topaz. The arguments -eexeConfig and -zsystemConfig determine the configuration files that linked topaz reads. For more information about this, see How GemStone Uses Configuration Files.

Settings within topaz can allow linked topaz to perform RPC logins.

Topaz is available for Windows, in addition to regular server platforms, as part of the Windows Client installation. Options are more limited since linked logins are not possible.

For further information, see the Topaz Programming Environment.

vsd

vsd [ -b color ] [ -u ] [ [ -a ] statmonDataFile+ ]

vsd -h | -v

-a

Append mode. Files following the -a are appended to the first one; the data in these files is merged so statistics are viewed as if they were a single file.

-color

Set the master background color. Color may be a hex RGB value (e.g.: #d3d3ff) or a valid color name (e.g.: white). The list of recognized color names may be found at: http://www.tcl.tk/man/tcl8.6/TkCmd/colors.htm

-h

Displays a usage line and exits.

-v

Print version information and exit.

statmonDataFile

The name of a statistics data file to load into the VSD as it is started.

This command starts VSD, the graphical tool to view and analyze statmonitor data. The default is to open an empty instance of VSD, into which you can then load one or multiple statmonitor data files. After loading data files, you may select one or multiple GemStone processes, and view charts on one or multiple statistics for these processes.

VSD is available for Windows, in addition to regular server platforms, as part of the Windows Client installation.

For a complete description of VSD, see the VSD User’s Guide.

waitstone

waitstone [ -h ] [ gemStoneName | netLdiName ] [ timeout ] [ waitForWarming ]

-h

Display a usage line and exits

gemStoneName

The name of the GemStone repository monitor.

netLdiName

The name of the GemStone netldi service.

timeout

How many seconds to wait for GemStone to initialize before reporting a problem. The default (0) means wait forever; -1 means don’t wait, try once and return the result. Only valid when specifying either gemStoneName or netLdiName.

waitForWarming

If larger than 0, block until cache warmers finish.

This command reports whether the GemStone repository gemStoneName is ready to accept logins or whether netLdiName is ready to accept requests. If neither gemStoneName nor netLdiName are specified, waitstone will report on the default stone name, gs64stone.

Waitstone checks every 0.5 seconds to see if the Stone or NetLDI is ready. When the service is ready, waitstone issues a message to stdout. If the service is not ready by the time the specified number of seconds have elapsed, waitstone reports an error.

With a -1 timeout, waitstone will make one connection attempt to the Stone or NetLDI. Note that if the stone is inaccessible, the timeout may be longer, since the configured TCP/IP timeout may apply. This can result in a 20 second timeout regardless of the specified timeout value.

Use of timeout requires that the Stone or NetLDI name is also specified.

If a positive value for the waitForWarming argument is specified, waitstone will block until cache warming completes; this is useful when cache warming is automatically run on startup. The specific value of the waitForWarming is not important. Use of the waitForWarming positional argument requires specifying each of the preceding arguments .

You may specify the gemStoneName and netLdiName arguments as a GemStone network resource string. (See Appendix C, “Network Resource Strings (NRS)”)

This command returns 0 exit status if the operation is successful; otherwise, it returns a non-zero value.

Previous chapter

Next chapter