This topic includes the following sections:
- Defining environment variables for xfServer processes
- Understanding security modes on UNIX
- xfServer configuration options
- Starting xfServer
- Stopping xfServer
Defining environment variables for xfServer processes
See Why use environment variables with xfServer? for a general discussion on the benefits of using environment variables 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.
Define your environment variables in the synrc file (in the /etc directory) and/or in the .synrc file (in each user’s $HOME directory or in the default account’s $HOME directory) on your server system. You can specify a different synrc file for each instance of xfServer by port number. To do this, name the file synrc.####, where #### is the port number, and put the file in the /etc directory. Environment variables defined in a synrc file for a specific port number take precedence over those set in the generic synrc file; environment variables set in the user’s .synrc take precedence over both the port-specific and the generic synrc.
Note that the synrc and synrc.#### files in the /etc directory are read when rsynd starts up. The .synrc file is read when a connection is made. Consequently, if you change values in either of the synrc files in the /etc directory, you must restart xfServer for the changes to take effect.
|
To include comments in the synrc file, precede the comment with a number sign (#). |
| 1. | Ensure that each client user has a valid username and password on each server machine that is running xfServer. This username will be used to generate the persona used during xfServer access. If you are running in non-secure mode with a default user account, only the default user account needs to have a valid username and password on the server machine. |
| 2. | Set up a generic synrc file in the /etc directory of the server for all client users. If desired, set up synrc files for specific instances of xfServer by specifying the port number as the file extension. (A sample synrc file is included with your installation.) |
| 3. | Put any user-specific environment variables in another file, .synrc, in the user’s $HOME directory on the server. |
|
|
A period in the filename (.synrc) is used only when the file is in the user’s $HOME directory. The period is not used when the file is in the /etc directory. (This conforms with UNIX conventions.) xfServer (rsynd) reads the synrc file only when it is first started. So, if you change any settings in this file, you must stop and restart rsynd. |
Understanding security modes on UNIX
On UNIX, xfServer can be run in trusted mode, secure mode, non-secure mode, or effective user mode
Trusted mode
Trusted mode is the default. In trusted mode, the server assumes a trusted network, where users have been properly authenticated by their individual machines.
If the RUSER environment variable (or registry setting) is set on the client, it is used: the username and encoded password (credentials) are sent to the server, where they are checked against the user’s password for 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 RUSER is not set, the username of the logged-in user is sent to the server (this is referred to as implied RUSER), and the password is not checked. If the username used to log in the client does not exist on the server, an error is generated and access to xfServer is denied.
Regardless of whether RUSER is set or implied RUSER is used, the username sent to the server is used to generate the persona used during xfServer access.
To run xfServer in trusted mode, start rsynd without any mode option. To set RUSER on the client machines, run the setruser utility. For more information on setting RUSER, see setruser utility and the RUSER environment variable.
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 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 sent to the server is used to generate the persona used during xfServer access.
To run xfServer in secure mode, start rsynd with the -s option. You must run the setruser utility on each client machine. 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.
|
Even though they are encoded, RUSER credentials should be kept confidential because they can be used with any xfServer client. |
For more information on setting RUSER, see setruser utility and the RUSER environment variable.
Non-secure mode
In non-secure mode, if RUSER is set on the client, the username is sent to the server; otherwise, the username of the logged-in user is sent. 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 run xfServer in non-secure mode, start rsynd with the -n option.
When running in non-secure mode, you have the option of specifying a default user account (with the -u option), which will be used as the persona for all clients. (See the examples below for the syntax.) 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 (this account cannot be root) specifically for use with xfServer. Rsynd will validate that the specified account is a valid account on the local machine before starting the service. If you are going to use non-secure mode, we recommend that you use a default user account.
|
|
If you are running xfServer in non-secure mode with encryption enabled, you must specify a default user account. |
There are two ways to start rsynd when using the default account option—with a password and without a password.
- This method requires that you supply the password for the default user account when starting rsynd. The password must be encoded with setruser; a clear text password is invalid. There are a couple of ways to do this. For example:
rsynd -n -u `setruser`
This command launches the setruser utility, which prompts for a username and password. After you enter the username and password, the command starts rsynd with the specified username and the encoded password. (Note that setruser must be enclosed between accent grave characters (`) as shown above.)
You can also run setruser to generate the encoded username/password string, and then include it in the start-up command, as shown in this example:
rsynd -n -u "username/\362\224c\261\351\224\374P"
Because this method does not require user input, you can put this command in a start-up file. Note that the username/password string must be enclosed in double quotation marks; failure to include the quotation marks may result in a “wrong username/password” error. For information on using setruser, see setruser utility.
- This method enables you to start rsynd from an authorized account without specifying a password:
rsynd -n -u xfServerAccount
where xfServerAccount is the username of the default user account you created for use with xfServer. This command can be executed by a user signed on as xfServerAccount or by any user with root privileges (uid=0). A password is not required; if it is passed, it is ignored.
Effective user mode
In effective user mode, security is handled by changing the user account that “owns” xfServer (rsynd). Rsynd is distributed with the setuid bit on and owned by root. When using the security mode options described above, xfServer starts as root, and then adopts the persona of the specified account. Effective user mode enables you to start (and then run) rsynd as a user other than root. In effective user mode, if RUSER is set, it is ignored; the account specified with -u is also ignored.
There are two ways to implement effective user mode:
- To ensure that rsynd always runs as a specific user regardless of who starts it, change the owner and set the setuid bit. If you start rsynd from a start-up file (e.g., the run command file [rc] or systemd [for help using systemd on Linux, see Synergex KnowledgeBase article 2522]), this method will ensure it starts as the correct user (otherwise it would start as root because the rc file runs as root). To change the owner and set the setuid bit, use the following commands:
chown xfServerAccount rsynd chmod u+s rsynd
- To run rsynd as the user who starts it, run only the first command above. This will change the owner without setting the setuid bit. When running in this mode, stopping the server with rsynd -q must be done by the user who started rsynd or by root.
|
|
If you implement effective user mode for xfServer, and you also use xfServerPlus, xfServerPlus will run as the same effective user, rather than under the account you specify with -u (or the account of the user who started rsynd, which is the behavior if you do not specify -u when starting xfServerPlus). |
xfServer configuration options
You may need to set additional xfServer options; see rsynd program for a complete list.
The default port used by 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 specify a non-default port, start rsynd with the -p option and set the SCSPORT environment variable on the client. A non-default port must be specified on both the server and the client.
By default, xfServer logs start and stop activity and errors to the file /usr/lib/rsynd.log and to syslog. Use the environment variable RSYNDLOG to specify an alternate log file name or set RSYNDLOG to SYSLOGONLY to log errors only to syslog. By default, the maximum log file size is 1MB. If the file reaches that size, information is deleted and the log is restarted. Use the RSLOGMAX environment variable to specify a larger log file size. Set RSYNDLOG and RSLOGMAX as described in Defining environment variables for xfServer processes.
Compression
Set the SCSCOMPR environment variable to a non-zero value in the synrc file on the server (see Defining environment variables for xfServer processes) 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 or in the client’s .synrc file on the server. To turn compression off, it must be turned off on both the server and the client. |
Starting xfServer
The xfServer daemon (rsynd) is a background process that must be running for xfServer to work.
|
|
When running 32-bit rsynd on 64-bit Linux, you cannot use an LDAP account to start rsynd. For this configuration, you must either use a local account or install nscd. See Synergex KnowledgeBase article 2286. |
| 1. | To enable the xfServer daemon to grant adequate resources to clients, verify that the rsynd program is owned by root. In the dbl/bin directory, enter |
chown root rsynd
| 2. | Make sure that rsynd has the set-user-ID bit set. In the same location, enter |
chmod u+s rsynd
| 3. | Add the full path name of rsynd to the start-up file (e.g., the run command file [rc] or systemd) on your server system. (The actual file name may vary depending on your operating system. See your system administrator or operating system documentation.) This will cause xfServer to start and be ready for incoming client application requests each time the server is booted. |
For example, on some machines you might add this line to the /etc/rc file:
/usr/synergyde/dbl/bin/rsynd
Stopping xfServer
There are two ways to stop the xfServer daemon (rsynd).
- To stop the xfServer daemon without killing the existing connections, use the -q option:
rsynd -q
This stops xfServer on the default port, 2330. If you are using a different port, specify the port number with the -p option.
This is the normal method for stopping rsynd. Existing connections are allowed to continue, but new connections are blocked. Use this method when you need to start a new version or configuration of rsynd on that port, or any time you want to prevent new access to the server without interrupting existing connections.
- To stop the xfServer daemon and kill all existing connections, use the -c option with -q:
rsynd -q -c
This stops xfServer on the default port, 2330. If you are using a different port, specify the port number with the -p option.
All existing connections are terminated and new connections are blocked. Use this method only when you need exclusive access to the server data.
|
|
Use this method with caution. Make sure you fully understand the effects of -q -c before stopping rsynd in this way. |
When you use -q -c, the client will be unaware that the server has been terminated until it attempts to access data on a channel that has been dropped. At this point, the client will receive a “Network problem reaching server server_name” error ($ERR_NETPROB). If you later want to reconnect to the server without terminating the client application, all channels currently open to the server must first be closed. While the server is down, any attempt to open a new channel will receive a “Synergy server on host name is not running or has been shut down” error ($ERR_NOSERVER), which can be trapped. Once the server has been restarted, a new open channel will reconnect to the server.
