Environment Variables

Previous chapter

This appendix lists the environment variables used by GemStone/S 64 Bit. The list has two parts: variables intended for public use, and variables that are reserved for internal use.

Public Environment Variables

The following environment variables are intended for use by customers. The variable GEMSTONE is required; the others may be useful in particular situations.

GEMSTONE

The location of the GemStone Object Server software, which must be a full path, beginning with a slash, such as /user3/GemStone-hppa.hpux.

GEMSTONE_ADMIN_GC_LOG_DIR

The directory location for Admin Gem logs. By default, Admin Gem log files are created in the same directory as the Stone log, which is $GEMSTONE/data. You can set this environment variable to specify that Admin Gem log files are created in a different directory.

GEMSTONE_EXE_CONF

The location of an executable-dependent configuration file; see How GemStone Processes Find Configuration Files.

GEMSTONE_GLOBAL_DIR

The location for the global GemStone logs and locks file, overriding the default /opt/gemstone/. This directory must already exist.

This directory controls visibility between GemStone processes, and must be the same for all GemStone processes that may want to interact with a given repository, including stone, gems, topaz, statmonitor, netldi, gslist, etc. GemStone processes that do not shared a common location for /gemstone/locks—either /opt/gemstone, /usr/gemstone, or a directory specified by $GEMSTONE_GLOBAL_DIR—operate as if they are in independent name spaces.

GEMSTONE_KEEP_LOG

To keep a process’s log from being deleted when the process terminates normally, unset this variable in the appropriate script, such as $GEMSTONE/sys/gemnetobject. To configure the system to keep all logs, see GS_KEEP_ALL_LOGS.

GEMSTONE_KEYRING_TABS

Set to a list of colon-separated directories containing SSL keys and certificates, for use by copydbf -V.

GEMSTONE_LIB

Specifies the directory for the gem and gem dynamic libraries. This is primarily of use in debugging low-level problems, and is used by the gemnetdebug script to specify the slow gem and gem dynamic libraries.

GEMSTONE_LOG

The location of system log files for the Stone repository monitor and its child processes. For further information, see GemStone Process Logs.

GEMSTONE_MAX_FD

Limits the number of file descriptors requested by a GemStone process. Normally, most GemStone processes raise their file descriptor limit from the default (soft) limit to the hard limit set by the operating system. Setting this variable to a positive integer sets a lower limit; a value of 0 disables attempts to change the default limit. This does not apply to the shared page cache monitor.

GEMSTONE_NRS_ALL

Sets a number of NRS directives that can be used by GemStone processes, such as the NetLDI name and log directory locations. For further information, see GEMSTONE_NRS_ALL.

GEMSTONE_RECLAIM_GC_LOG_DIR

The directory location for all Reclaim Gem logs. By default, Reclaim Gem log files are created in the same directory as the Stone log, which is $GEMSTONE/data. You can set this environment variable to specify that Reclaim Gem log files are created in a different directory.

GEMSTONE_SPCMON_STARTUP_TIMELIMIT

Internally, GemStone waits for five minutes for the shared page cache to start up and initialize. This environment variable overrides this timeout, and specifies the time, in seconds, that the Stone will wait for the shared page cache to startup before giving up.

GEMSTONE_SSL_LIB_DIR

A directory location in which to look for the SSL shared library.

GEMSTONE_SYMBOL_GEM_LOG_DIR

The directory location for SymbolGem logs. By default, Symbol Gem log files are created in the same directory as the Stone log, which is $GEMSTONE/data. You can set this environment variable to specify that Symbol Gem log files are created in a different directory.

GEMSTONE_SYS_CONF

Location of a system-wide configuration file; see How GemStone Processes Find Configuration Files.

GS_AWS_LOG_DIR

Directory where to write AWS log files if GS_AWS_LOG_LEVEL is set to 4 or above.

GS_AWS_LOG_LEVEL

Sets the logging level for the AWS services to between 0 and 6, where 0 = no logging and 6 = debug logging. GemStone starts logging calls at level 4 and higher.

GS_AZURE_LOG_DIR

A directory in which to create the azure log file

GS_AZURE_LOG_LEVEL

The level of logging. Valid values are 1, 2, 3, 4. The meanings of these values are:

1 – Verbose: Logging level for detailed troubleshooting scenarios

2 –Informational: Logging level when a function operates normally.

3 – Warning: Logging level when a function fails to perform its intended task.

4 – Error: Logging level for failures that the application is unlikely to recover from.

GS_CFTIME

If defined, it should contain a date and time format string that overrides the GemStone LOCALE-based default. See Localizing timestamps in log files.

GS_CORE_TIME_OUT

If GS_WRITE_CORE_FILE is defined, this is the number of seconds to wait before a catastrophically failing GemStone/S process writes a core file and terminates—by default, 60 seconds. To determine the cause of a problem, GemStone/S Technical Support needs a stack trace, which is usually written to the process log file prior to the process shutdown.

If you need to derive a stack trace directly from a failing (but not yet terminated) process by attaching a debugger to it, you can set this variable to increase the time available to attach the debugger.

GS_DEBUG_LDAP_DIR

If this variable is set to a directory, a process that performs LDAP calls for user login will write output to a file named GsLDAPDebug_<pid>.log in the specified directory. Sensitive information is redacted in the log file.

GS_DEBUG_LIBSSH_DIR

If this variable is set to a directory, a process that invokes libssh calls will write output to a file named GsSSHDebug_<pid>.log in the specified directory. Sensitive information is redacted in the log file.

GS_DEBUG_PAM

If this variable is set to any value, PAM debugging information will be printed to stdout.

GS_DEBUG_SHARED_MEM

If this variable is set to any value, the shared page cache monitor process will print extra debugging to its log file.

GS_DEBUG_SOCKETS

If set to any value, this environment variable will cause tracing messages to be written to stdout for bind(), connect(), getaddrinfo() and related socket calls.

GS_DEBUG_SSL_LOG_DIR

If this variable is set to a directory, a process that logs in RPC will write output of SSL calls made to a file named GsSSLDebug_<pid>.log in the specified directory. Sensitive information is redacted in the log file. This file may get very large.

GS_DEBUG_SSO_LOG_DIR

If this variable is set to a directory, a process that uses Kerberos/Single sign on will write output of Kerberos calls made to a file named GsSSODebug_<pid>.log in the specified directory. Sensitive information is redacted in the log file.

GS_DEBUG_VMGC_MKSW_MEMORY_USED_SOFT_BREAK

At the end of each mark/sweep, if the percent of memory used is greater than the threshold specified by this variable, a SoftBreak (error 6003) is generated, and the threshold is raised by 5 percent. We suggest a setting of 75%.

GS_DEBUG_VMGC_MKSW_PRINT_STACK

The mark/sweep count at which to begin printing the Smalltalk stack at each mark/sweep.

For this and all other GS_DEBUG_VMGC_* environment variables, the printout goes to the "output push" file of a linkable Topaz (topaz -l) session, for use in testing your application. If that file is not defined, the printouts go to standard output of the session’s gem or topaz -l process.

GS_DEBUG_VMGC_MKSW_PRINT_C_STACK

The mark/sweep count at which to begin printing the C stack at each mark/sweep. This variable is very expensive, consuming 2 seconds plus the cost of fork() for each printout.

GS_DEBUG_VMGC_PRINT_MKSW
The mark/sweep count at which to begin printing mark/sweeps.

GS_DEBUG_VMGC_PRINT_MKSW_MEMORY
The mark/sweep count at which to begin printing detailed memory usage (20 lines) for each mark/sweep.

GS_DEBUG_VMGC_PRINT_MKSW_MEMORY_USED
Specifies when Smalltalk stack printing starts as the application approaches OutOfMemory conditions. At the end of each mark/sweep, if the percent of memory used is greater than the threshold specified by this variable, the mark/sweep is printed, the Smalltalk stack is printed, and the threshold is raised by 5 percent. In a situation producing an OutOfMemory error, you should get several Smalltalk stacks printed in the Gem log file before the session dies. The default setting is 75%.

GS_DEBUG_VMGC_PRINT_SCAV

The scavenge count at which to begin printing scavenges. Once this takes effect, all mark/sweeps will also be printed. Be aware that printing scavenges can produce large quantities of output.

GS_DEBUG_VMGC_PRINT_TRANS

Print transaction boundaries (begin/commit/abort) in the log file.

GS_DEBUG_VMGC_SCAV_PRINT_STACK

The scavenge count at which to begin printing the Smalltalk stack at each scavenge. Be aware that this print activity can produce large quantities of output.

GS_DEBUG_VMGC_SCAV_PRINT_C_STACK

The scavenge count at which to begin printing the C stack at each scavenge. This variable is very expensive, consuming 2 seconds plus the cost of fork() for each printout.

GS_DEBUG_VMGC_VERBOSE_OUTOFMEM

Automatically call the primitive for System class>>_vmPrintInstanceCounts:0 when an OutOfMemory error occurs, and also print the Smalltalk stack. (For details about this method, see the comments in the image.) This applies to each Gem or linkable Topaz (topaz -l) process that you subsequently start.

GS_DEBUG_VMGC_VERIFY_MKSW

The mark/sweep count at which to begin verifying object memory before and after each mark/sweep.

GS_DEBUG_VMGC_VERIFY_SCAV

The scavenge count at which to begin verifying object memory before and after each scavenge. Once this takes effect, GS_DEBUG_VMGC_VERIFY_MKSW will also be in effect. Be aware that this activity uses significant amounts of CPU time.

GS_DISABLE_CHARACTER_TABLE_LOAD

Any value disables the loading of any customized Extended Character Set Character Data Tables. This feature is deprecated; see the Programming Guide for details.

GS_DISABLE_KEEPALIVE

A non-empty string disables the network keepalive facility. For further information about keepalive, see Disrupted Communications

GS_DISABLE_WARNING

A non-empty string disables a warning that GemStone is using /opt/gemstone instead of /usr/gemstone for log and lock files when both directories exist. Use of /usr/gemstone is only for compatibility with previous releases; the default location is /opt/gemstone.

GS_DISABLE_SHMDT

Disables the system call to shmdt() made on cache detach during logout.

GS_DISABLE_SIGNAL_HANDLERS

When this environment variable is enabled in the environment for a gem process, by setting it to any value, this gem sessions will not attempt to handle a SIGSEGV, SIGBUS or SIGILL signal, but will shut down immediately without attempint to print C stacks or waiting for a C debugger to attach.

GS_GSLIST_TIME_FORMAT

This can be set to UNIX-style date format string, to allow the output of the gslist utility to be displayed in a parse-able format.

GS_FORCE_CLEAN_LOG_FILE_DELETE

When set, delete GemStone log files on clean exit; affects all processes except for Stone or NetLDI logs, which are never deleted. Logs for processes that exit with errors are not affected.

GS_KEEP_ALL_LOGS

Ensure that no GemStone process log files are deleted, overriding any individual process settings for GEMSTONE_KEEP_LOG.

GS_PAGE_MGR_PRINT_REMOTE_STACKS

If this variable is set, if a remote cache page server becomes stuck, the page manager will request that the remote cache page server print its call stack to its log file.

GS_SOCK_SEND_BUF_SIZE

Sets the size of the socket send buffer for the socket between the Gem and GCI client for an RPC Gem.

GS_SOCK_RECV_BUF_SIZE

Sets the size of the socket receive buffer for the socket between the Gem and GCI client for an RPC Gem.

GS_WRITE_CORE_FILE

By default, core files are not created when a fatal error occurs. (The C level stack trace is written to the process log file prior to the process shutdown.) You can set this environment variable if you need a core file.

upgradeLogDir

The location for log files produced during the upgrade of a repository for a new version of GemStone.

System Variables Used by GemStone

GemStone uses the following system variables that exist for other purposes:

EDITOR

Used by Topaz to determine which editor to invoke.

PATH

The search path of locating executable files.

SHELL

Used to determine what shell to use for an exec, such as by System class>>performOnServer:.

Reserved Environment Variables

The following environment variables are reserved for internal use. Customers should not define these variables for use with GemStone unless specifically instructed to do so. Please refrain from using these variables for other purposes.

GCIRTL_BASELIBNAME

GEMSTONE*

All environment variable names beginning with “GEMSTONE” other than those above are reserved.

GS_*

All environment variable names beginning with “GS_” other than those above are reserved.

gs64ldi

Previous chapter