This topic includes the following:
- Defining logical names for xfServer processes
- Understanding security modes on OpenVMS
- xfServer configuration options
- Starting xfServer
- Stopping xfServer
Defining logical names for xfServer processes
See Why use environment variables with xfServer? for a general discussion on the benefits of using logicals with xfServer. If your client application includes environment variables in the format LOGICAL:@server_name, you must define those environment variables on the server, where xfServer can find them.
Logicals can be defined at different levels using a number of different methods. It’s important to understand the hierarchy and implications of each method, as well as how they can be used together. (See Examples for an example showing how two of the methods can be used together.) The information in this section applies to both xfServer and xfServerPlus.
Understanding tables
The sections below describe methods that put logicals in the system table, the LNM$RSDMS$MGR_port table (where port is the port number rsynd is listening on), and the LNM$SYNSVR_processID table (where processID is the ID of an xfServer process).
The LNM$RSDMS$MGR_port and LNM$SYNSVR_processID tables are created when rsynd starts. The LNM$RSDMS$MGR_port table is shared by all pooled processes for a single instance of rsynd. If you run rsynd on multiple ports, there will be a separate table for each port (for example, LNM$RSDMS$MGR_2330, LNM$RSDMS$MGR_2440). The LNM$SYNSVR_processID table is specific to each xfServer process.
Tables are scanned by the session servers in this order: process table, LNM$SYNSVR_processID, LNM$RSDMS$MGR_port, job table, group table, system table. Once a logical is found in a table, the remaining tables are not searched. For example, if the logical DATA is defined in both the LNM$RSDMS$MGR_port table and the system table, the definition in the LNM$RSDMS$MGR_port table will be used.
Defining system-level logicals
You can define logicals intended for system-wide visibility in the SERVER_INIT.COM file. The SERVER_INIT.COM file is invoked in the SYNERGY_STARTUP.COM file after the connection manager daemon (rsynd) has been started. The logicals are placed in the system table. Consequently, all instances of xfServer will use the same logical definitions, and other applications on the system will also have access to these definitions.
The SERVER_INIT.COM file may contain any DCL command, so you can use this method for other xfServer-related system start-up commands. Because the SERVER_INIT.COM file is processed by DCL, you can use this method to put logicals into other tables at system start-up.
To use this method, create a file named SERVER_INIT.COM in DBLDIR and use this qualifier to define the logicals:
$ DEFINE/SYS logical_name device:[directory]
For example:
$ DEFINE/SYS DATA DKA600:[SYNERGYDE.CONNECT]
|
If you use this method for defining logicals, you should edit the SYNERGY_STARTUP.COM file to start the server with the /NOUSE_SYNRC qualifier. This tells xfServer to ignore the SYNRC.COM file in the home directory of the user when setting up logicals. See rsynd program for complete information on rsynd qualifiers. |
Defining logicals for use by all instances of xfServer
If you have several instances of xfServer running on different ports and would like them all to use the same logical definitions (but you don’t want the logicals available to all applications on the system), you can define the logicals in the DBLDIR:SYNRC.COM file. (Note that logicals defined in SYNRC.COM are case sensitive.)
Rsynd processes the DBLDIR:SYNRC.COM file when it starts up and places the logicals in the LNM$RSDMS$MGR_port table. They are then available to all session servers started by rsynd. Although the logicals are placed in the LNM$RSDMS$MGR_port table, all instances of xfServer will use the same logicals because this method does not enable you to specify a port. If you have multiple instances of xfServer, there will be multiple LNM$RSDMS$MGR_port tables, but the logical definitions will be the same for all of them.
Because DBLDIR:SYNRC.COM is opened and interpreted by rsynd (rather than DCL), you cannot place other DCL commands in this file, and any table qualifiers placed on the DEFINE command are ignored. When using this method, rsynd start-up is slower than normal because it must process SYNRC.COM.
To use this method, create a file named SYNRC.COM in DBLDIR and use this qualifier to define the logicals:
$ DEFINE logical_name device:[directory]
For example:
$ DEFINE DATA DKA600:[SYNERGYDE.CONNECT]
|
|
If you use this method for defining logicals, you should edit the SYNERGY_STARTUP.COM file to start the server with the /NOUSE_SYNRC qualifier. This tells xfServer to ignore the SYNRC.COM file in the home directory of the user when setting up logicals. See rsynd program for complete information on rsynd qualifiers. |
Defining server-specific logicals
You can define server-specific logicals in the SERVER_INIT.COM file. The SERVER_INIT.COM file is invoked in the SYNERGY_STARTUP.COM file after the connection manager daemon (rsynd) has been started. The logicals are placed in the LNM$RSDMS$MGR_port table.
This method allows you to specify a port for xfServer, which enables you to define logicals differently for separate instances of xfServer. SERVER_INIT.COM places logicals in the LNM$RSDMS$MGR_port table after DBLDIR:SYNRC.COM has already done so. Consequently, the logicals defined in SERVER_INIT.COM will override the same logicals defined in DBLDIR:SYNRC.COM.
The SERVER_INIT.COM file may contain any DCL command, so you can use this method for other xfServer-related system start-up commands. Because the SERVER_INIT.COM file is processed by DCL, you can use this method to put logicals into other tables at system start-up.
To use this method, create a file named SERVER_INIT.COM in DBLDIR and use this qualifier to define the logicals:
$ DEFINE/TABLE=LNM$RSDMS$MGR_port/USER logical_name device:[directory]
where port is the port number on which xfServer is listening. For example:
$ DEFINE/TABLE=LNM$RSDMS$MGR_2330/USER DATA DKA600:[SYNERGYDE.CONNECT]
|
|
If you use this method for defining logicals, you should edit the SYNERGY_STARTUP.COM file to start the server with the /NOUSE_SYNRC qualifier. This tells xfServer to ignore the SYNRC.COM file in the home directory of the user when setting up logicals. See rsynd program for complete information on rsynd qualifiers. |
Defining user-specific logicals
You can define user-specific logicals by placing them in the SYNRC.COM file in the home directory of the user. When a remote user logs in to a session server, that session server processes SYNRC.COM in the user’s home directory (SYS$LOGIN) and places the logicals in the LNM$SYNSVR_processID table. This table is read before the LNM$RSDMS$MGR_port table and the system table, so logicals defined in this manner override logicals defined with any of the other methods discussed above.
|
|
When you run xfServer in non-secure mode with a default user account, a single account is used as the persona for all users. Consequently, you cannot specify different logicals for individual users. This also applies to xfServerPlus because it uses a single account to run all xfServerPlus sessions. |
To use this method, create a file named SYNRC.COM in the home directory of the user who is connecting to the server, and use this qualifier to define the logicals:
$ DEFINE logical_name device:[directory]
For example:
$ DEFINE DATA DKA600:[BETTY]
This example shows you how to use the methods described in Defining logicals for use by all instances of xfServer and Defining server-specific logicals together. Say you have an accounting application with data for two customers, and the directory structure for the data is the same for both customers (only the name of the main directory differs). Within the main directory for each customer are subdirectories for AP, AR, and GL. The system consists of Windows clients connecting to an OpenVMS server.
You could set up logicals in the SERVER_INIT.COM file to access the data on two ports like this:
$ DEFINE/TABLE=LNM$RSDMS$MGR_2330/USER/TRANS=CONC CUST DKA600:[CUST_ONE.] $ DEFINE/TABLE=LNM$RSDMS$MGR_2331/USER/TRANS=CONC CUST DKA600:[CUST_TWO.]
Users who connect on port 2330 will have access to the data files for customer one, while users who connect on 2331 will have access to the data files for customer two.
Then, in the DBLDIR:SYNRC.COM file, set up logicals for the subdirectories of CUST_ONE and CUST_TWO. These will apply to all rsynds. For example:
$ DEFINE AP CUST:[AP] $ DEFINE AR CUST:[AR] $ DEFINE GL CUST:[GL]
On the Windows client, set SCSPORT to either 2330 or 2331, and set up logicals for AP, AR, and GL that point to the server. For example:
set SCSPORT=2331 set MY_AP=AP:@vms_server set MY_AR=AR:@vms_server set MY_GL=GL:@vms_server
Within the Synergy application, there is code to open the file named MY_AP:ap.ism. As defined above, this logical indicates xfServer access and will attempt to open AP:ap.ism on the server. On the OpenVMS server, it is translated as CUST:[AP]AP.ISM. Then, because the client connected on port 2331, this is translated as DKA600:[CUST_TWO.AP]AP.ISM, and the file is opened.
Understanding security modes on OpenVMS
On OpenVMS, xfServer can be run in secure mode or non-secure mode. In both secure and non-secure mode, each client user must have a valid username and password on each server machine that is running xfServer. If you are running in non-secure mode with a default user account, only the default user account needs to have a username and password on the server machine.
Secure mode
In secure mode, the client sends the username and encoded password (credentials) to the server, where they are checked against the user’s password on the user’s account on the server. The absence of a password is considered a failure. If authentication fails, an error is generated and access to xfServer is denied. If authentication succeeds, the username is used to generate the persona used during xfServer access.
To start xfServer in secure mode, include the /SECURE option on the command line in the SYNERGY_STARTUP.COM file. You must run the setruser utility on each client. On a Windows client, setruser will generate the encoded password for RUSER and set RUSER in the registry. (RUSER can also be set in the environment on Windows; the environment setting takes precedence over a registry setting.) On a UNIX client, setruser will generate the encoded password for RUSER, which you can then use to set the RUSER environment variable. For more information on setting RUSER, see setruser utility and the RUSER environment variable.
|
Even though they are encoded, RUSER credentials should be kept confidential because they can be used with any xfServer client. |
Non-secure mode
Non-secure mode is the default. If the RUSER environment variable (or registry setting on a Windows client) is set on the client, the username is sent to the server; otherwise, the username of the logged-in user is sent (this is referred to as implied RUSER). No password is checked. If the user doesn’t have an account on the server, an error is generated and access to xfServer is denied. If the user does have an account on the server, it is used to generate the persona used during xfServer access.
To start xfServer in non-secure mode, you can specify /NOSECURE on the command line in the SYNERGY_STARTUP.COM file if you like, but it is not required since non-secure is the default.
When running in non-secure mode, you have the option of specifying a default user account (with the /DEFAULT_USER option), which will be used as the persona for all clients. If you choose to use a default user account, you do not need to set RUSER on the clients (if it is set, it is ignored) nor create an account for each client on the server. To use the default account option, we recommend that you create an account on the server with limited privileges specifically for use with xfServer. Rsynd will validate that the specified account is a valid account on the local machine before starting the process. This account cannot have the privileges listed below unless the /ALLOW_PRIVILEGED qualifier is specified in the start-up command. We recommend that you not allow these privileges because they give end users privileges at the system administrator level.
|
ALTPRI |
DOWNGRADE |
SYSNAM |
|
BYPASS |
EXQUOTA |
SYSPRV |
|
CMEXEC |
READALL |
VOLPRO |
|
CMKRNL |
SECURITY |
WORLD |
|
DETACH |
SETPRV |
|
|
|
If you are running xfServer in non-secure mode with encryption enabled, you must specify a default user account. |
To start xfServer in non-secure mode with a default user, include the following options on the command line in the SYNERGY_STARTUP.COM file:
/NOSECURE /DEFAULT_USER=user_name
where user_name is the account that you created to use with xfServer. Note that you must specify the /NOSECURE option on the command line when you are using a default user account.
xfServer configuration options
The default port for xfServer is 2330. If you are running multiple instances of xfServer on the same machine, each will need to run on a different port. To start xfServer on a non-default port, in the SYNERGY_STARTUP.COM command file specify the following option:
/PORT=nnnn
A non-default port must be specified on both the server and the client. Use the SCSPORT environment variable on the client system to specify the port for xfServer. (For a Windows client, set SCSPORT in the registry.)
By default, logging of rsynd errors and some status messages is enabled (/LOG_LEVEL=ENABLE). Because this level of logging is a program default, it is not necessary to include this qualifier on the start-up command line in the SYNERGY_STARTUP.COM file. To send these messages to a log file, use the /OUTPUT qualifier on the start-up command line and specify a log file name. By default, messages are logged to the file node_rsynd_port.log in DBLDIR.
To log additional status information and start/stop messages, use the /LOG_LEVEL=FULL qualifier on the start-up command line in conjunction with /OUTPUT.
To send messages to the operator console in addition to the log file, use the /LOG_LEVEL=OPERATOR qualifier on the start-up command line and set REPLY/ENABLE=NETWORK on your operator terminal. You can use the OPERATOR setting with either regular or full logging. For example, if you want to enable full logging and send messages to the operator console, use /LOG_LEVEL=(FULL, OPERATOR).
To turn logging off completely, use /LOG_LEVEL=NONE.
To enable logging of data regarding clients that connect to the OpenVMS server, use /CLIENT_LOGFILE. This creates a file named node_SRVR_pid.log in DBLDIR. If /CLIENT_LOGFILE is not set (or /NOCLIENT_LOGFILE is set), client logs are created only when there is an error.
Compression
Set the SCSCOMPR logical to a non-zero value in the DBLDIR:SYNRC.COM or SERVER_INIT.COM file (see Defining server-specific logicals) to compress data records sent between xfServer and its clients. This option compresses blanks, nulls, zeros, and repeating characters. Compression can significantly improve performance on low speed or busy networks, especially WANs.
|
|
SCSCOMPR can also be set on the client. To turn compression off, it must be turned off on both the server and the client. |
Starting xfServer
xfServer is normally started automatically at machine start-up using the SYNERGY_STARTUP.COM file. The rsynd start-up command is placed in this file when Synergy DBL is installed.
To start xfServer manually, execute the following command with the desired switches while logged into the SYSTEM account. (See rsynd program for the complete rsynd syntax.)
$ RSYND
To start xfServer manually using the switches defined in the SYNERGY_STARTUP.COM file, execute the following command while logged into the SYSTEM account:
$ @SYNERGY_STARTUP XFRESTART
xfServer can also be started from the servstat program. See servstat program for more information.
|
|
On OpenVMS, xfServer sets the current working directory to the user’s default directory and creates a SYS$SCRATCH logical to reference the user’s directory. |
Stopping xfServer
There are several ways to stop xfServer (rsynd):
- To stop xfServer without shutting down existing connections, execute the following command while logged into the SYSTEM account:
$ RSYND/SHUTDOWN/PORT=nnnn
where nnnn specifies the port number of the server system to shut down. After this command has been successfully executed, existing connections are allowed to continue, but new connections are blocked.
- To stop xfServer and shut down all existing connections, execute the following command while logged into the SYSTEM account:
$ RSYND/SHUTDOWN=ALL/PORT=nnnn
where nnnn specifies the port number of the server system to shut down. After this command has been successfully executed, all existing connections are terminated and new connections are blocked.
You can also use the servstat program to shut down xfServer. See servstat program for more information.
