Using xfServer on Windows

This topic includes the following sections:

 

During installation, xfServer is installed with default settings for port, logging, security, and connection recovery. The installation program also registers xfServer in the Windows registry using the default service name (SynSrv) and port (2330), and then starts it.

You can modify the default settings for SynSrv or add additional xfServer services using the Synergy Configuration Program.

Note

When you’re running xfServer, you can use the Monitor utility (synxfmon.exe) to find out which files are open, who opened them, whether those files are locked, and whether any client contexts are being held. See Monitor utility for Windows (synxfmon).

Modifying the SynSrv xfServer service

Before modifying any xfServer service, verify that no users are currently connected. The service must be stopped and restarted for changes to take effect, so any users would be disconnected. In addition, if connection recovery is enabled and there are client contexts being held, they will be deleted.

You can use the import/export feature to set up xfServer (and xfServerPlus) services. See Importing and exporting settings (Windows).

You must be logged on using an account that has administrator privileges to modify settings and to register and start an xfServer service.

Important

Do not attempt to issue rsynd commands from the command line while the Synergy Configuration Program is running.
1. Start the Synergy Configuration Program (from the Windows Control Panel, select Synergy Control Panel > Synergy Configuration Program) and go to the xfServer/xfServerPlus tab.
2. Select the service SynSrv in the list of services and click the Modify Service button.
3. Modify the fields in the xfServer Information dialog box. You cannot change the service name. If you do not want to use the default service name, you must remove this service and add a new one with the desired name.

Port number

Enter the port you want xfServer to run on. Valid ports are in the range 1024 through 65535. The default is 2330.

If you use a non-default port for the server, you must use SCSPORT to specify it on all the clients.

Display name

Enter a display name for this service. This is the name that displays in the Windows Services console. If you leave this field blank, it defaults to “Synergy/DE xfServer ####”, where #### is the port number.

Secure/Restricted/Non-secure

Indicate if you want to run xfServer in secure mode, restricted mode, non-secure mode, or run as user. The default is secure. See Understanding xfServer security on Windows for a detailed explanation of security modes.

Username

If you selected “Run as user”, enter the username for the account that you created to use with xfServer. This account can be either a local account or a domain controller account; it cannot be a member of the administrators group. If there is an account with the same username on both the local machine and on a Windows domain, or on multiple domains, and you want to use a specific domain account, you must explicitly specify the domain name in the format user_name@domain_name or domain_name\user_name.

Note

The xfServer account must be assigned the user right “Log on as a service.” If it is not assigned, when you try to register rsynd you will see the error “Invalid username or password (1385:Logon failure: the user has not been granted the requested logon type at this computer.)” (This user right can be assigned in the Windows Local Security Policy app, accessed through Control Panel > Administrative Tools.)

Password

If you selected “Run as user”, enter the password for the account that you created to use with xfServer. You will need to re-enter this password whenever you change the service settings.

Compress data packets

Indicate whether you want 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.

Note

Compression can also be set on the client with the SCSCOMPR environment variable. To turn compression off, it must be turned off on both the server and the client.

Enable logging

Select this option to enable event logging, which logs all user connections. Rsynd always logs its version, start/stop information, and errors to the event log, regardless of whether this option is enabled. To view event logs, use the Windows Event Viewer and choose the application event log.

Verbose logging

Select this option to enable more verbose event logging. In addition to user connections, the event log will also show informational messages, which may be helpful when troubleshooting. Due to the number of events that could potentially be logged, you will probably want to turn off verbose logging when you are done troubleshooting.

Enable encryption

Select this option to enable encryption of data between client and server. See Using client/server encryption for details on this feature.

Certificate specification/pem file

Specify the certificate file (.pem file) or the Windows Certificate Store specification. For a .pem file, use either the full path or a logical. The default filename is DBLDIR:rsynd.pem, but you may choose another name and place the file anywhere you like. (Note that the resolved path displays rather than “DBLDIR”.) For a Windows Certificate Store specification, paste the formatted string into this field. For details on this string, see the -cert=filename argument in the rsynd syntax topic.

Allow startup with invalid pem file certificate

Select this option to allow rsynd to start when there is an invalid/expired .pem file. By default, rsynd logs the error and terminates. If this option is checked, it still logs the error (in the event log), but does not terminate, allowing you time to troubleshoot the problem.

Security level

Displays the currently selected protocols. To change this setting, click the Change button to display the Security Compliance Level dialog. The default is “Always use current default”, which means that the available protocols may change with the version of Synergy. If you don’t want the available protocols to change when you upgrade xfServer, clear the check box and explicitly select the minimum protocol you’d like to be available. As of Synergy/DE 11, level 1 is no longer available. See Understanding cipher suites and protocols for more information.

Enable connection recovery

Select this option to enable the client to recover the connection and the session context after an unexpected socket disconnect, and then select the type of connection recovery desired, Slave or Master. See Using connection recovery (Windows) for details on this feature.

Select profile

Select the desired connection recovery profile, Default, Mobile, or Mobile2 to indicate the time, in seconds, for the four connection recovery parameters. Alternatively, select Custom and define your own set of time values.

4. If you want to modify environment variables for xfServer, click the Environment Settings button and see Defining environment variables for xfServer services for instructions.
Tip

If you create files without specifying a path (i.e., you rely on a default path), you may want to set the RSFILPATH environment variable to indicate where you want the files to go. You can use the Synergy Configuration Program to set RSFILPATH.

5. Click OK in the xfServer Information dialog box.
6. Click Apply in the Synergy Configuration Program. If the service is currently running, the Synergy Configuration Program stops it and then restarts it with the new settings. See the xfServer Start-up and Shutdown Codes table for status and error codes that may occur.

Adding a new xfServer service

You can run multiple xfServer services; each service must have a different port, service name, and display name. You must have administrator privileges to register and start an xfServer service.

1. Start the Synergy Configuration Program and go to the xfServer/xfServerPlus tab.
2. Click the Add xfServer Service button.
3. In the Service name field, enter a name for this service. This name will display on the list of services on the xfServer/xfServerPlus tab and in the registry.
4. Values in the remaining fields default from the <Default> entry. Change them as necessary. See step 3 above for detailed field information and see Using the < Default > entry for information on setting default values for new services.
5. If you want to modify environment variables for xfServer, click the Environment Settings button and see Defining environment variables for xfServer services for instructions.
6. Click OK. The new service displays in the list of services.
7. Click Apply to register the new service.
8. If desired, start the service now by clicking the Start Service button. You can also start the service later; see Starting xfServer.

Using the < Default > entry

The <Default> entry, which displays in the Services list on the xfServer/xfServerPlus tab of the Synergy Configuration Program, can be used to set default values for some xfServer and xfServerPlus settings and for environment variables used by xfServer and xfServerPlus. To modify the settings for the <Default> entry, select <Default> in the list of services and click the Modify button.

The following settings are applied to all newly created xfServer services. Existing services are not affected.

The following data encryption settings are applied to all newly created xfServer and xfServerPlus services. Existing services are not affected.

Environment variables are applied to all existing xfServer and xfServerPlus services as well as to any new services that you create. See Defining environment variables for xfServer services for more information on environment variables.

Understanding xfServer security on Windows

On Windows, xfServer can be run in secure mode, restricted mode, non-secure mode, or run-as-user mode.

What are RUSER security and Windows authentication security?

RUSER security secures the connection between client and server using username and password credentials supplied by the client. The credentials are passed to xfServer for authentication. The username will be used to generate the persona used during xfServer access. This is referred to as “RUSER security” because the credentials are defined on the client using the RUSER environment variable or registry setting.

Important

Even though they are encoded, RUSER credentials should be kept confidential because they can be used with any xfServer client.

Windows authentication security uses the Windows operating system to authenticate Windows clients. No credentials are passed from the client to xfServer. Rather, the local security authority is used to establish a security context between client and server. We recommend that you use Windows authentication security rather than RUSER security if possible.

Secure mode

Overview

Secure mode enables you to use both RUSER security and Windows authentication security.

On either a Windows or Unix client, if the RUSER environment variable (or registry setting) is set to a username and password, RUSER security will be used. The client sends the username and encoded password to the server, where it is checked against the user’s name and password on the server. If authentication fails, an error will be generated and access to xfServer will be denied.

On a Windows client, if RUSER is not set, Windows authentication will be used. Windows authentication uses the same security as is used when a user logs into a domain account and has access to the resources in that domain. A Windows client logged into a domain can have access to any xfServer running within that domain. Access to individual files and folders is controlled by the user’s account on the domain, as set up by the Windows system administrator. No credentials are passed to the server. If Windows authentication fails, access to xfServer will be denied.

On a Unix client, if RUSER is not set, an error will be generated and access to xfServer will be denied.

Benefits

Secure mode is of particular benefit when you have both Windows and Unix clients connecting to a Windows server. The Windows clients can use Windows authentication, requiring less setup, while the Unix clients can use RUSER security.

Setting up

To use RUSER security, 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. Do not set RUSER in synergy.ini or synuser.ini.) On a Unix client, setruser will generate the encoded password for RUSER, which you can then use to set the RUSER environment variable. In addition, there must be a matching username and password on the server machine or on a Windows domain where the server machine is a member. (For more information, see setruser utility and the RUSER environment variable.)

To use Windows authentication, the client user must have an account on a Windows domain, and the xfServer machine must belong to the same domain or trusted domain. Ideally, RUSER should not be set. However, if there is a global RUSER setting on the client machine, you can ensure that Windows authentication is used instead of RUSER security by running setruser and specifying “SSPI” (all uppercase) for the username (don’t specify a password; just press Enter when prompted for it).

Running the server

In the Synergy Configuration Program, select “Secure” for data access. This is the default. (See Modifying the SynSrv xfServer service for details.)

If you are starting xfServer from the command line, you can specify the -s option when you register the service, or you can just not specify a security option at all, as -s is the default. (See rsynd program for details on command-line options.)

Restricted mode

Overview

Restricted mode uses Windows authentication exclusively. Consequently, the server and all the clients must be Windows machines. Once a user has successfully logged into the Windows domain, that user can be granted access to any xfServer within the domain. Access to individual files and folders is controlled by the user’s account on the domain, as set up by the Windows system administrator. If RUSER is set, it is ignored.

Benefits

One of the advantages to restricted mode, in addition to the ease of implementation, is that you can guarantee that no user credentials (username and password) are sent over the network.

Setting up

There is no special set-up required on the clients; the clients and the xfServer machine must all be on the same domain.

Running the server

In the Synergy Configuration Program, select “Restricted” for data access. (See Modifying the SynSrv xfServer service for details.)

If you are starting xfServer from the command line, specify the -sspi option when you register the service. (See rsynd program for details on command-line options.)

Non-secure mode

Overview

In non-secure mode all clients take on the persona of the service, which is the SYSTEM account. No credentials are checked.

Benefits

This mode requires no setup and it can be used with both Windows and Unix clients.

Setting up

No extra setup is required on the client side or the server side to run in non-secure mode.

Note

If you are running xfServer in non-secure mode you cannot use encryption.

Running the server

In the Synergy Configuration Program, select “Non-secure” for data access.

If you are starting xfServer from the command line, specify the -n option when you register the service. (See rsynd program for details on command-line options.)

Run-as-user mode

Overview

Run-as-user mode supports both Windows and Unix clients. In this mode, the rsynd service is registered using the specified username and password, and so it runs as that user, rather than as the SYSTEM account. Access to individual files and folders is controlled by the account used to register rsynd.

Benefits

Run-as-user mode is easy to implement, supports both Windows and Unix clients, and requires no setup on the clients. The xfServer user account is simple to set up and can be used to restrict users’ access on the server.

Setting up

There is no special set-up required on the clients.

You must create a user account for xfServer to run under. We recommend that you set up an account with limited privileges specifically for use with xfServer. This account can be on the xfServer machine (a local account), or it can be a domain controller account. The account cannot be a member of the administrators group.

The account for xfServer must be assigned the user right “Log on as a service.” If it is not assigned, when you try to register rsynd you will see the error “Invalid username or password (1385:Logon failure: the user has not been granted the requested logon type at this computer.” (This user right can be assigned in the Windows Local Security Policy app, accessed through Control Panel > Administrative Tools.)

Running the server

In the Synergy Configuration Program, select “Run as user” for data access, then specify the username and password for the account you created for use by xfServer. You will need to supply the password every time you make a change in this dialog.

From the command line, specify the -u option, followed by the username/password of the xfServer account, when you register the service. (See rsynd program for details on command-line options.)

Note

You can use the system accounts “NT Authority\LocalService” and “NT Authority\NetworkService” if desired. These accounts do not have a password. In SynConfig, just leave the Password field blank. On the command you will need to enclose the username in double quotation marks (because it includes a space) and include the slash (but not a password). For example:

rsynd -r -u "NT Authority\LocalService/"

Defining environment variables for xfServer services

See Why use environment variables with xfServer? for a general discussion of 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.

The recommended method for defining environment variables for xfServer is to use the Synergy Configuration Program, which writes the settings to the Windows registry. (xfServer cannot read environment variables set in the environment; they must be set in the registry.) Using the Synergy Configuration Program, you can define environment variables for all xfServer services or for a specific instance of xfServer. Environment variables can also be defined for a specific user, but you must do so by manually editing the registry; see Defining environment variables for a specific user.

Before adding or changing environment variables, you should verify that no users are currently connected. The service must be stopped and restarted for environment variable changes to take effect, so any users would be disconnected and any saved client contexts lost.

Defining environment variables for all services

Environment variables set in this manner will apply to all instances of xfServer and xfServerPlus, both existing and newly created.

Note

If an environment variable is already set for a specific service (see Defining environment variables for a specific service), and you set that same environment variable for “all services”, the service-specific setting will not be overridden. If your goal is to use the “all services” setting, you must delete the service-specific setting.
1. Start the Synergy Configuration Program and go to the xfServer/xfServerPlus tab.
2. Select <Default> from the list of services, click the Modify Service button, and then click the Environment Settings button. Only the top portion of the Environment Settings dialog box is enabled.
3. When you are through, click OK in the Environment Settings dialog box.
4. Click OK in the xfServer Information dialog box, and click Apply in the Synergy Configuration Program. If any services are currently running, the Synergy Configuration Program will prompt you before stopping and then restarting them with the new settings.

Defining environment variables for a specific service

Environment variables set in this manner will apply only to a specific instance of xfServer and will override settings made for all services.

1. Start the Synergy Configuration Program and go to the xfServer/xfServerPlus tab.
2. Select the desired service, click the Modify Service button, and then click the Environment Settings button. Use the lower portion of the Environment Settings dialog (labeled “Settings for service name”) to set environment variables for the selected service.
3. When you are through, click OK in the Environment Settings dialog box.
4. Click OK in the xfServer Information dialog box, and click Apply in the Synergy Configuration Program. If the service is currently running, the Synergy Configuration Program will prompt you before stopping and then restarting it with the new settings.

Defining environment variables for a specific user

Environment variables defined for a specific user will override environment variables set for all xfServer services and those set for a specific xfServer service. The user must have an account on the server machine; it cannot be a domain account. Note that environment variables set at the user level are read when a connection is made. This is in contrast to environment variables set at the server level, which are read when xfServer starts.

Note

You cannot define environment variables at this level from the Synergy Configuration Program; they must be defined manually in the registry. We recommend backing up (exporting) the affected registry branch before making any changes.

1. Log onto the server machine as the user for whom you wish to set the environment variable.
2. Run regedit.
3. Navigate to HKEY_CURRENT_USER\SOFTWARE\Synergex\Synergy xfServer\Synrc. This registry key is created the first time the user accesses xfServer. If it is not present, you will need to create the key manually.
4. Add a new environment variable.
5. Navigate to HKEY_LOCAL_MACHINE\ SOFTWARE\Synergex\Synergy xfServer\service_name\Default and set ENABLEUSERHIVE to 1 in that location. This registry setting is required for user-specific environment variable settings.

Starting xfServer

The default service SynSrv is started automatically when you install. However, there may be times when you need to start it manually. You must have administrator privileges to start xfServer.

To start xfServer manually, do any of the following:

net start service_name

where service_name is the name of the xfServer service to be started. The default service name is SynSrv.

The following codes, which may occur when starting or stopping xfServer, can be used to check failure conditions programmatically. With the exception of 12, they may also display in a message window or on the command line under certain conditions. xfServer returns 0 (zero) for all successful operations, such as when the service has been successfully registered, started, or stopped.

xfServer Start-up and Shutdown Codes

Code

What it means

2

You must be logged on using an account that has administrator privileges to register or unregister the service.

3

The specified account does not exist on the machine.

5

User not found on local machine.

6

The username specified for the default user account for xfServer or for running xfServerPlus sessions belongs to the administrators group. This is not permitted. Check the Windows Event Viewer for more information.

7

No username/password specified. Check the Windows Event Viewer for more information.

12

Service registration error.

13

Invalid option specified. If SSPI security is enabled (restricted mode), this error may indicate the machine is no longer a part of the domain. Check the Windows Event Viewer for more information.

14

Encryption is required but not available. Check the Windows Event Viewer for more information.

15

Port is in use. It might be the case that you are attempting to start a service that is already running. Check the Windows Event Viewer for more information.

Stopping xfServer

Before stopping or removing (unregistering) a service, you should verify that no users are connected because all connections are lost. You must have administrator privileges to stop xfServer.

Note

You can close a specific xfServer connection with the Monitor utility for Windows (synxfmon).

To stop xfServer, do one of the following:

net stop service_name

where service_name is the name of the xfServer service to be stopped. The default service name is SynSrv.

rsynd -q

This stops the default xfServer, SynSrv, on the default port, 2330. Use the -c option to specify a different service name; use the -p option to specify a non-default port.

To both stop and unregister xfServer, do one of the following:

rsynd -x

This stops and unregisters the default xfServer, SynSrv, on the default port, 2330. Use the -c option to specify a different service name; use the -p option to specify a non-default port.