setruser utility

The setruser utility generates the encoded string that is used to set the RUSER environment variable or registry setting on the client machine. This utility is run on the client machine. The syntax differs on Windows and UNIX.

Windows

On Windows, setruser has the following syntax:

setruser [-d] [-g] [-h] [-n]

Options

<none>

Create or update the RUSER environment variable in the registry for the current user (local setting).

-d

Delete the RUSER setting from the registry.

-g

Create or update the RUSER environment variable in the registry for all users (global setting).

-h

Display usage information.

-n

Display the encoded string to the screen without updating the registry.

Discussion

When you run setruser without any options, it will prompt you for the username and password that you have set up on the server for secure access, and then return the encoded string and use this string to set RUSER in the registry under HKEY_CURRENT_USER\ Software\Synergex. This sets RUSER for the user who is currently logged in. If RUSER is set at the global level on the machine, a message to that effect will display to inform you that the local (user-specific) setting will be used.

When you run setruser with the -g option, it will prompt you for the username and password that you have set up on the server for secure access, and then return the encoded string and use that string to set RUSER in the registry under HKEY_LOCAL_MACHINE\ Software\Synergex. (If 32-bit is installed on a 64-bit machine, you may also see it set in HKEY_LOCAL_MACHINE\ Software\Wow6432Node\Synergex.) This sets RUSER globally for all users on the machine. If there is a user-specific RUSER setting on the machine, it is not altered, and you will see a warning message that a local RUSER setting exists on the machine and will be used.

The runtime reads RUSER first from the environment. If RUSER is found there, it is used. If RUSER is not set in the environment, the runtime checks HKEY_CURRENT_USER for the logged-in user and uses the setting found there. If RUSER is not set at the user level, then the runtime checks for a global setting in HKEY_LOCAL_MACHINE.

When RUSER is set in the Synrc node in the registry, as is required when configuring xfServerPlus for remote data access, it is read into the environment when rsynd starts up, and it is therefore considered to be set in the environment.

The username “SSPI” (all uppercase) is reserved for use with Windows authentication. Setting RUSER to SSPI and not specifying a password (just press Enter at the password prompt) indicates to xfServer that Windows authentication should be used. Setting RUSER to SSPI is necessary only if there is a global RUSER setting that you want to override. (See Understanding xfServer security on Windows for detailed information about security and important user and system requirements.) If you set RUSER to SSPI and specify a password, or if you set RUSER to sspi (lowercase), it will be treated as an ordinary RUSER setting, but we do not recommend doing this, as it can lead to confusion.

To delete a local RUSER setting from the registry, run setruser with the -d option. To delete a global RUSER setting, run setruser with the -d and -g options. If there is another RUSER setting on the machine (e.g., you are deleting a local setting and a global setting still exists), a message to that effect will display.

The -n option prompts you for the username and password, and then displays the encoded string to the screen without updating the registry. You can use this string to set RUSER in the environment or pass it with the -u option to either rsynd or synd.

If you have an account with the same username on both the local machine (i.e., the client) and on a Windows domain, or on multiple domains, and you want to use a specific domain account, when prompted for the username type user_name@domain_name or domain_name\user_name. (This applies when running setruser without any options and when running it with the -n option or the -g option.) If you don’t specify the domain, xfServer will find the account on the local machine first, and then display an error because the password doesn’t match.

UNIX

The setruser utility takes no options on UNIX. When you run setruser, it will prompt you for the username and password that you have set up on the server for secure access, and then return the encoded string. Use the displayed string to set RUSER:

RUSER=setruser_value ;export RUSER

You can automate this process by executing a shell command that invokes setruser (which prompts you for the username and password), assigns the output to RUSER, and exports it. Setruser must be enclosed between accent grave characters (`) as shown below or the command will not execute.

RUSER=`setruser` ;export RUSER