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 2> run
GsNetworkResourceString defaultGemNRSFromCurrent asString
%
!tcp@santiam#netldi:52331#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 can handle multiple and more complicated instructions, such as causing all Gem session process logs to be created with a specific name in a specific directory.
As an environment variable, it only affects processes created after it is set, and changing it may require restarting the NetLDI.
- 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.
For example, by default for an RPC login that specifies the default gemnetobject to spawn a gem, the gem log is written to the user’s home directory. To use the #dir modifier to set the current (working) directory for NetLDI child processes, use code such as the following:
$ GEMSTONE_NRS_ALL=#dir:/user2/apps/logs
$ export GEMSTONE_NRS_ALL
This causes the gemnetobject log files to be written to the directory /user2/apps/logs; if this directory is not writable, an error is generated.
However, if the RPC login parameters specify a different setting for the name attribute, for example:
topaz > set gemnetid !#dir:/someotherdir!gemnetobject
This will be used, not the setting in GEMSTONE_NRS_ALL
If the client GCI application (e.g. topaz) has a GEMSTONE_NRS_ALL set to a value that is different from the NetLDI’s GEMSTONE_NRS_ALL, the client application’s directives takes precedence.
Controlling log file names and locations
The NRS in the Gem service login parameters, or the NRS specified by a GEMSTONE_NRS_ALL statement, can be used to configure the specific directory location and log file name for Gem logs and the logs for server process on remote nodes.
The #dir and #log directives in the NRS can combine the desired directory or file names with combinations of the following patterns, to ensure each log file is unique and identifiable:
%H - home directory
%D - the value of any -D option specified for the NetLDI
%M - machine’s network node name
%N - executable’s base name, such as gemnetid for a Gem
%P - process pid
%U - user name
A #dir directive must specify an existing, writable directory and end with a / path divider. The #log directive should not be a directory.
For example, a Gem with pid 27522 running on node santiam has by default a log file named gemnetobject27522santiam.log in the user's home directory. This could be specified in an NRS using #log:%H%N%P%M.log. The syntax to specify this in a topaz login parameters would be:
set gemnetid !#log:%H%N%P%M.log!gemnetobject
To avoid the need to specify this in the login parameters for each login, it can be specified in a setting for the environment variable GEMSTONE_NRS_ALL that is set in the environment for all users.
setenv GEMSTONE_NRS_ALL "#log:%H%N%P%M.log"
“D” Pattern
Another level of control for log file locations is managed by the NetLDI. When the -D option to startnetldi is used, it sets a variable within the NetLDI that can be later accessed by using the %D pattern in the login parameter NRS for log or dir. This allows the individual Gem login parameters to remain the same, while the actual directories used can be changed at once for all users.
For example, the following respective command and environment variable settings would create Gem log files with the default name in the directory /node1/users/gsadmin/sales/logs/.
startnetldi -D /node1/users/gsadmin/sales/logs/
set gemnetid !#netldi:salesldi#log:%D/%N%P%M.log!gemnetobject
alternatively, the Gem NRS can be specified in the environment of all users:
setenv GEMSTONE_NRS_ALL "#netldi:salesldi#log:%D/%N%P%M.log"
If the desired location for log file changes, the only action required is to restart the NetLDI with the new directory. If your users log in to multiple repositories and you wish to keep the log files separate, this is easily done by using two NetLDIs with the appropriate -D arguments.
However, note that this way of managing the log file locations requires some attention:
- All Gems for which the NetLDI -D directory should be used will need to use the correct NRS. Any logins that do not use the %D within the login parameters will write their log files to the default locations.
- Care must be taken in making sure the -D is consistently used with the NetLDI, so the combination of the pattern in the NRS and the directory in the NetLDI will always produce a valid, writable path and filename; invalid log file names cause the login to fail.
If the %D is present in the NRS, and the NetLDI was not started with a -D argument, an empty string is used for %D. This means, for example, that if the -D argument is set to an absolute path and the %D in the NRS is used accordingly, then if NetLDI happens to get restarted without the -D argument, logs may attempt to get written to the root directory.
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.
% 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:
% waitstone !@oboe#auth:user@password!gs64stone
% 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 of the network resource. 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 of the network resource. It has no effect if the resource already exists. If the log name is a relative path, it is relative to the working directory. If a log name is not set, the pattern “%N%P%M.log” is used, as 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:
%H home directory
%D a directory path supplied by the NetLDI
%M machine’s network node name
%N executable’s base name, such as gemnetid for a Gem
%P process pid
%U user name
%% (escaped) %
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.