Network Resource Strings (NRS)
The network resource string (NRS) is a GemStone-specific way to format a string that contains:
- unique identifiers for a GemStone file or process within a networked environment, such as the node and name of a running Stone.
- specific instructions for performing actions, such as spawning a Gem process.
- configuration details and arguments, such as authentication information or locations for writing log files.
A basic understanding of NRS to compose login parameters is unavoidable, for any but the most simple configurations. However, NRS has a number of features and syntactical elements and a full understanding is not needed.
A.1 Using NRS
The primary use for NRS by applications and end users are in login parameters, to specify the Stone, and for RPC logins, to specify the Gem service. Some utility commands also accept NRS in order to perform operations remotely.
The following table provides the most common formats for NRS syntax for Stone and Gem services. In these examples, you may use the IP address instead of the hostname, and the NetLDI listening port instead of the NetLDI name.
GsNetworkResourceString
This GemStone Smalltalk class provides a programmatic API to construct correctly formatted NRS strings. The resulting string is in the most complete form, including default information, not in the most simplified form that you can enter as a parameter.
For example, the following expression recreates the NRS that can be used for the gemnetid parameter, based on the current RPC session.
topaz 1> run
GsNetworkResourceString defaultGemNRSFromCurrent asString
%
!@santiam#netldi:54321#task!gemnetobject
GEMSTONE_NRS_ALL
The environment variable GEMSTONE_NRS_ALL determines which modifiers GemStone will use by default in each NRS it processes on your behalf.
This is frequently used to configure a specific NetLDI name when the default NetLDI name is not used, avoiding having to specify the NetLDI name in every NRS. For example,
$ GEMSTONE_NRS_ALL="#netldi:devldi"
$ export GEMSTONE_NRS_ALL
GEMSTONE_NRS_ALL may include any or all of the directives #netldi, #dir, and #log, as described later in this chapter.
As an environment variable, it only affects processes created after it is set, and after making changes, you will need to restart the process before the changes take effect.
- If you set GEMSTONE_NRS_ALL before starting a NetLDI, which is a system-wide service, that setting is passed to all its children and becomes the default for all users of that service, i.e. RPC gems.
- If you set GEMSTONE_NRS_ALL before starting a Stone, an application, or a utility (such as copydbf), that setting applies only to your own processes and does not affect other users.
Because these settings are defaults, they take effect only if an explicit setting is not provided for the same modifier in a specific NRS setting or command-line argument.
Arguments to startnetldi
You may specify a default log file and working directory for child processes such as gemnetobject using the startnetldi -D argument.
The NetLDI can pick up settings in the GEMSTONE_NRS_ALL environment variable. You may also pass in an NRS directly to the NetLDI on startup, using the startnetldi -x option. These settings take precedence over the GEMSTONE_NRS_ALL.
Arguments to gemnetobject
Within the NRS that specifies the Gem service (the topaz gemnetid parameter), you may also includes additional arguments that will be passed to the gemnetobject script. See the discussion for gemnetobject here for which arguments can be used.
Using gemnetobject arguments with topaz requires that the string passed to gemnetid be enclosed in single quotes.
For example, the following includes one directive to set the NetLDI, and two gemnetobject arguments, one of which sets two configuration parameter values.
topaz > set gemnetid '!#netldi:54321!gemnetobject -T 100MB -C GEM_FREE_FRAME_CACHE_SIZE=2;GEM_HALT_ON_ERROR=2101;'
When using complex NRS, it is recommended to check the Gem log file to ensure that all settings were entered correctly. Incorrect arguments will be ignored rather than generating an error.
Controlling log file directory locations
All GemStone processes write log files to default locations, which are described in Chapter 7. The log files for processes that are forked by the NetLDI during login are described starting here.
While these processes have default log names and locations, these can be further controlled by configuring the NetLDI or the NRS used during login.
To configure the log file directory, the following options are available:
- Use the -D flag to startnetldi to specify the log file directory location for child processes. This is the recommended way to define the log file directory.
- The #dir NRS directive sets the directory for log files. Set GEMSTONE_NRS_ALL to include the #dir directive in the environment in which the NetLDI is started up, or the environment in which the client process is executing.
- Include the #dir directive in the NRS for the Gem service login parameters.
startnetldi -D defines a specific directory. However, #dir can include the following patterns, which gives many options to configure the directories for log files.
%D The value of the startnetldi -D option specified for the NetLDI that will service the request.
%M machine’s network node name
%N executable’s base name, such as gemnetobject for a Gem
The combination of -D and/or any #dir directives must result in describing an existing, writable directory. Login will fail if a log file cannot be created.
The following is the precedence:
1. If there is a directory specified by #dir in the NRS for the Gem service login parameter (gemnetid), this directory is used.
2. Otherwise, a directory specified by #dir in the GEMSTONE_NRS_ALL in the environment of the client process.
3. Otherwise, a directory specified by the -D argument to startnetldi, or by a #dir setting in the GEMSTONE_NRS_ALL in the environment where the NetLDI was started.
4. Otherwise, the home directory, “%H”.
The startnetldi -D option is the most reliable way to manage client process log file locations. This allows all log files to go to a known location, rather than the home directories of individual users; while avoiding the need to control environment variables or login parameters for each individual GemStone user.
You can easily have log files write to a new location (say, if you move the application to a different node, or from development into production), by just restarting the NetLDI with the new directory in the -D argument.
Keep in mind that -D and #dir sets the working directory for the process as well as the location in which to write log files.
Example A.1 NetLDI controls log file locations, log files have default name
os$ startnetldi -g -agsadmin -D $GEMSTONE/logs 54321
Do not include #dir in any GEMSTONE_NRS_ALL, and do not include #dir in the Gem login parameters.
A Gem with pid 27522 running on node santiam will then default to writing the log file $GEMSTONE/logs/gemnetobject27522santiam.log.
The same result comes from using the #dir directive in the GEMSTONE_NRS_ALL for the NetLDI or client environments, or in the Gem login parameters.
“%D” Pattern
When using the -D argument to startnetldi, there are additional options for controlling log file locations by including the %D pattern in NRS. In the location in which the %D appears in the NRS for #dir, the %D will be replaced by the argument to -D when composing the log file name.
Example A.2 Example using %D pattern
If you have multiple applications and want the logs for the sales application and the purchasing application to be in separate directories, you might define the following directories:
/node1/users/gsadmin/logs/sales/
/node1/users/gsadmin/logs/purchasing/
And to start the NetLDI, use the following command:
startnetldi -g -agsadmin -D /node1/users/gsadmin/logs/ 54321
In the sales application, use the Gem NRS:
set gemnetid !#netldi:54321#dir:%D/sales!gemnetobject
And in the purchasing application:
set gemnetid !#netldi:54321#dir:%D/purchasing!gemnetobject
These will write their log files in the correct subdirectory of /node1/users/gsadmin/logs/
Using %D requires that the NetLDI was started using the -D argument. If the NetLDI is inadvertently started without the -D argument, an empty string is substituted for the %D. Unless this still allows the #dir to define a writable directory, login will fail. The error will be reported in the NetLDI log file:
WARNING: %D in NRS but no -D argument to startnetldi
in #dir, %D/purchasing changed to /purchasing
Controlling log file names
The #log directive is used to specify the name of the log file, which by default for a Gem is gemnetobjectPIDNode.log (%N%P%M.log). The #log argument must not be a directory.
For backwards compatibility, you may use an absolute or partial directory as part of the #log argument, along with the log filename pattern, but this is not recommended.
Example A.3 NetLDI controls log file locations and names
os$ setenv STONENAME devstone
os$ setenv GEMSTONE_NRS_ALL "#log:Gem-$STONENAME%M%P.log"
os$ startnetldi -g -agsadmin -D $GEMSTONE/logs 54321
Do not include #dir in any GEMSTONE_NRS_ALL, nor in the Gem login parameters.
A Gem with pid 27522 running on node santiam will then default to writing the log file $GEMSTONE/logs/Gem-devstonesantiam27522.log
The same result comes from using the #log directive in the GEMSTONE_NRS_ALL for the client environment, or in the Gem login parameters.
There is some flexibility in using directories within the #log argument, and composing paths using the -D argument, for backwards compatibility.
When using -D, %D, and #dir and #log, some care must be taken in making sure the use is consistent, such that the combination will always produce a valid, writable path and filename. Invalid log file paths and names will cause login to fail, with an error in the NetLDI log file.
A.2 NRS Syntax
The BNF below provides full NRS syntax. Many of the options are used internally for interprocess communication, and are not intended for general use.
These strings may appear in the full form in places where command arguments are recorded, such as GemStone log files.
Spaces and Special Characters
An NRS can contain spaces and special characters; in particular, !, #, and @ are frequently used.
While GemStone internally ensures that space and special characters are handled correctly, you may need to escape certain characters in NRS strings that are entered at a command prompt. The specific characters and escapes may vary on different UNIX shells.
os$ copydbf $GEMSTONE/data/extent0.dbf
\!@node#auth:username@password#dbf\!/users/extent0.dbf_copy
If there is a space in the NRS, you can replace the space with a colon (:), or you can enclose the string in quotes (" ").
For example, the following network resource strings are equivalent:
os$ waitstone !@oboe#auth:user@password!gs64stone
os$ waitstone "!@oboe#auth user@password!gs64stone"
Syntax
nrs-header ::= ! [address-modifier] {keyword-modifier} [resource-modifier]!
All modifiers are optional, and defaults apply if a modifier is omitted. The value of an environment variable can be placed in an NRS by preceding the name of the variable with “$”. If the name needs to be followed by alphanumeric text, then it can be bracketed by “{” and “}”. If an environment variable named foo exists, then either of the following will cause it to be expanded: $foo or ${foo}. Environment variables are only expanded in the nrs-header. The nrs-body is never parsed.
address-modifier ::= [tcp] [@ node]
Specifies where the network resource is.
node ::= nrs-identifier
If no node is specified, the current machine’s network node name is used. The identifier may also be an Internet-style numeric address. For example:
!@120.0.0.4#server!cornerstone
nrs-identifier ::= identifier
Identifiers are runs of characters; the special characters !, #, $, @, ^ and white space (blank, tab, newline) must be preceded by a “^”. Identifiers are words in the UNIX sense.
keyword-modifier ::= ( authorization-modifier | environment-modifier)
Keyword modifiers may be given in any order. If a keyword modifier is specified more than once, the latter replaces the former. If a keyword modifier takes an argument, then the keyword may be separated from the argument by a space or a colon.
authorization-modifier ::= ( (#auth | #encrypted) [:] username [@ password] )
#auth specifies a valid OS user name on the target network. A valid OS user password is needed only if the resource type requires authentication. #encrypted is used by GemStone utilities. This type of authorization is the default.
If no OS user name is specified, the default is the current OS user. See the earlier discussion of authorization-modifier.
password ::= nrs-identifier
Only needed if the resource type requires authentication; see the earlier discussion of authorization-modifier.
environment-modifier ::= ( #netldi | #dir | #log ) [:] nrs-identifier
#netldi causes the named NetLDI to be used to service the request. If no NetLDI is specified, the default is gs64ldi. When you specify the #netldi option, the nrs-identifier is either the name of a NetLDI service or the port number at which a NetLDI is running.
#dir sets the default directory for the child processes, and the directory into which log files for child processes will be written. It has no effect if the resource already exists. If a directory is not set, the pattern “%H” (home directory) is used. (See the definition of nrs-identifier.
#log sets the name of the log file for child processes. It has no effect if the resource already exists. If a log name is not set, the pattern “%N%P%M.log” is used, with the patterns described below, and following the syntax in the definition of nrs-identifier
The argument to #dir or #log can contain patterns that are expanded in the context of the created resource. The following patterns are supported:
%D a directory path supplied by the NetLDI. This is replaced by the contents of the startnetldi -D argument.
%M machine’s network node name
%N executable’s base name, such as gemnetobject for a Gem
resource-modifier ::= ( #server | #spawn | #task | #dbf | #monitor | #file )
Identifies the intended purpose of the string in the nrs-body. An NRS can contain only one resource modifier. The default resource modifier is context sensitive. For instance, if the system expects an NRS for a database file, then the default is #dbf.
#server directs the NetLDI to search for the network address of a server, such as a Stone or another NetLDI. If successful, it returns the address. The nrs-body is a network server name. A successful lookup means only that the service has been defined; it does not indicate whether the service is currently running. A new process will not be started. (Authorization is needed only if the NetLDI is on a remote node and is running in secure mode.)
#task starts a new Gem. The nrs-body is a NetLDI service name (such as “gemnetobject”), followed by arguments to the command line. The NetLDI creates the named service by looking first for an entry in $GEMSTONE/sys/services.dat, and then in the user’s home directory for an executable having that name. The NetLDI returns the network address of the service. (Authorization is needed to create a new process unless the NetLDI is in guest mode.) The #task resource modifier is also used internally to create page servers.
#dbf is used to access a database file. The nrs-body is the file spec of a GemStone database file. The NetLDI creates a page server on the given node to access the database and returns the network address of the page server. (Authorization is needed unless the NetLDI is in guest mode).
#spawn is used internally to start the garbage collection and other service Gem processes.
#monitor is used internally to start up a shared page cache monitor.
#file means the nrs-body is the file spec of a file on the given host (not currently implemented).
nrs-body ::= unformatted text, to end of string
The nrs-body is interpreted according to the context established by the resource-modifier. No extended identifier expansion is done in the nrs-body, and no special escapes are needed.