Running xfServerPlus on UNIX
By default, xfServerPlus runs on port 2356.
We recommend that you set up an account with limited privileges specifically for running xfServerPlus sessions. Use either a system-level environment variable for DBLDIR or add a DBLDIR entry to the synrc file in the user directory for the new account. Clients assume the persona of the username that is specified or assumed during start-up; consequently, we recommend that you not give this account root access.
When running 32-bit rsynd on 64-bit Linux, you cannot use an LDAP account to run xfServerPlus sessions. For this configuration, you must either use a local account or install nscd. See Synergex KnowledgeBase article 100002866.
You can start xfServerPlus either with or without a password. Optionally, you can run in effective user mode.
This method of starting xfServerPlus requires that you supply the password for the account you created to run xfServerPlus sessions. The password must be encoded using the setruser utility; it cannot be entered in clear text. There are a couple of ways to specify a user password. For example:
rsynd -w -u `setruser`
This command launches the setruser utility, which prompts for a username and password. Note that setruser must be enclosed between accent grave characters (`). After you enter the username and password, the command starts rsynd with the specified username and the encoded password on the default port (2356). You can specify a non-default port with the -p option.
Optionally, you can run setruser to generate the encoded password string, and then include it in the start-up command. For example:
rsynd -w -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. (See setruser utility for more information.)
This method enables you to start xfServerPlus from an authorized account without specifying the password for the account you created to run xfServerPlus sessions. (If the password is passed, it is ignored.) The syntax is
rsynd -w -u xfspAcct
where xfspAcct is the username of the account you created to run xfServerPlus sessions. You can optionally specify a non-default port with the -p option. All clients assume the persona of xfspAcct.
This command can be executed by a user signed on as xfspAcct or by any user with root privileges (uid=0). However, if the username itself (i.e., xfspAcct) is root, xfServerPlus will return an error and will not start. If xfServerPlus starts successfully, you’ll see the message “All xfServerPlus clients will be run as user xfspAcct.”
You can also start xfServerPlus without specifying a username. The username defaults to that of the user signed on. (Presumably, this is the account you created to run xfServerPlus sessions.) The syntax is
Optionally, you can specify a non-default port with the -p option. All clients assume the persona of the user who started rsynd.
This command can be executed by any user without root authority. If start-up is successful, you’ll see the message “All xfServerPlus clients will be run as user userName.” If userName has root authority, xfServerPlus will return an error message and will not start.
In effective user mode, security is handled by changing the user account that “owns” xfServerPlus (rsynd). Rsynd is distributed with the setuid bit on and owned by root. When starting xfServerPlus as described above, xfServerPlus 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 an account is specified with -u, it is ignored.
There are two ways to implement effective user mode:
- If you change the owner and set the setuid bit, rsynd will always run as that user regardless of who starts it. If you start rsynd from a start-up file (the run command file, rc), this 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 xfspAcct rsynd chmod u+s rsynd
- If you change the owner but do not set the setuid bit (by running only the first command above), rsynd will run as the user who started it.
If you implement effective user mode for xfServerPlus, and you also use xfServer, xfServer will run as the same effective user, rather than under the account you specify with -u.
You can create more than one instance of xfServerPlus by specifying a different port (the default is 2356) for the additional session in the start-up syntax. You can use the -text option to add a description to help distinguish the sessions. For example:
rsynd -w -u xfspAcct -p 3356 -text "Session two: %s"
For the complete list of rsynd options, see rsynd program.
There are two methods for stopping xfServerPlus (rsynd).
- To stop xfServerPlus without killing the existing connections, use the -q option:
rsynd -q -w
This stops xfServerPlus on the default port, 2356. If you are using a different port, omit the -w option and specify the port number with the -p option. For example:
rsynd -q -p 2445
This is the usual method for stopping xfServerPlus. 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 xfServerPlus on that port, or any time you want to prevent new access to the server without interrupting existing connections.
- To stop xfServerPlus and kill all existing connections, use the -c option with -q:
rsynd -q -c -w
This stops xfServerPlus on the default port, 2356. If you are using a different port, omit the -w option and specify the port number with the -p option.
All existing connections are terminated, new connections are blocked, and the non-interactive runtimes (dbs.exe) started by the server are terminated. Use this method only when you need exclusive access to the server.
When you stop the server in this manner, the error returned to the client will depend on which xfNetLink you are using.
- xfNetLink Synergy will return $ERR_XFHALT if there is a call in progress when the connection goes down. On subsequent attempts to connect while the connection remains down, xfNetLink Synergy will return $ERR_XFNOCONN.
- xfNetLink Java will throw java.net.SocketException if there is a call in progress when the connection goes down. (This could be a read or a write exception, depending on whether the client was sending or receiving at the moment of failure.) On subsequent attempts to connect while the connection remains down, xfNetLink Java will throw java.net.ConnectException.
- xfNetLink .NET will throw a socket error (if the client is sending) or a signal trap error (if the client is receiving) if there is a call in progress when the connection goes down. On subsequent attempts to connect while the connection remains down xfNetLink .NET will throw a connection refused error.