Synergy

by bobjensen — last modified Dec 23, 2008 05:32 PM

synergy: [noun] a mutually advantageous conjunction of distinct elements

Synergy lets you easily share a single mouse and keyboard between multiple computers with different operating systems, each with its own display, without special hardware. To do so it requires that all the computers are connected to each other via TCP/IP networking. Most systems come with this installed. It's intended for users with multiple computers on their desk since each system uses its own monitor(s).

Redirecting the mouse and keyboard is as simple as moving the mouse off the edge of your screen. Synergy also merges the clipboards of all the systems into one, allowing cut-and-paste between systems. Furthermore, it synchronizes screen savers so they all start and stop together and, if screen locking is enabled, only one screen requires a password to unlock them all. Learn more about how it works.

Synergy is open source and released under the GNU Public License (GPL).

System Requirements

Microsoft Windows 95, Windows 98, Windows Me (the Windows 95 family)
Microsoft Windows NT, Windows 2000, Windows XP (the Windows NT family)
Mac OS X 10.2 or higher(The Mac OS X port is incomplete. It does not synchronize the screen saver, only text clipboard data works (i.e. HTML and bitmap data do not work), the cursor won't hide when not on the screen, and there may be problems with mouse wheel acceleration. Other problems should be filed as bugs.)
Unix ("Unix" includes Linux (even Fedora), Solaris, Irix and other variants. Synergy has only been extensively tested on Linux and may not work completely or at all on other versions of Unix. Patches are welcome (including patches that package binaries) at the patches page.)
- X Windows version 11 revision 4 or up
- XTEST extension, to check for XTEST
```
xdpyinfo | grep XTEST
```
All systems must support TCP/IP networking.

Running Synergy

Because of the number of steps involved in getting Synergy fully set up you it is suggested that you start at the top of this document and follow the steps through to completion only skipping steps that do not apply to your network set up.

I don't run Windows or Mac OS X so I will not be covering installation or configuration on these operating systems initially. I have a friend with some windows machines that has agreed to let me do some testing on his network. The Synergy site on sourceforge has information for setting up Synergy on these Operating Systems.

Step 1 - Choose a server

The first step is to pick which keyboard and mouse you want to share. The computer with that keyboard and mouse is called the "primary screen" and it runs the Synergy server. All of the other computers are "secondary screens" and run the Synergy client.

Step 2 - Install the software

Install the software on all the Fedora machines, the same package is required for the server and client:

su -c "yum install synergy"

Step 3 - Configure and start the server

If you will not have a Fedora Synergy server move on to Step 4.

Next you configure the server. You'll tell Synergy the name of the primary and secondary screens, which screens are next to which, and choose desired options. On Fedora systems you'll create a simple text file.

Note that when you tell Synergy that screen A is to the left of screen B this does not imply that B is to the right of A. You must explicitly indicate both relations. If you don't do both then when you're running Synergy you'll find you're unable to leave one of the screens.

Create a text file named synergy.conf, I put this file in /etc/, with the following:

section: screens
   screen1:
   screen2:
end
section: links
   screen1:
       right = screen2
   screen2:
       left = screen1
end

Replace each occurrence of screen1 with the host name of the primary screen computer (as reported by the hostname program) and screen2 with the host name of a secondary screen computer. In the above example, screen2 is to the right of screen1 and screen1 is to the left of screen2. If necessary you should replace right and left with left, right, up, or down. If you have more than two computers you can add those too: add each computer's host name in the screens section and add the appropriate links. See the configuration guide for more configuration possibilities.

Now start the server. Normally Synergy wants to run "in the background." It detaches from the terminal and doesn't have a visible window, effectively disappearing from view. Until you're sure your configuration works, you should start Synergy "in the foreground" using the -f command line option.

On unix type the command below in a shell. If synergys is not in your PATH then use the full pathname.

synergys -f --config synergy.conf

Step 4 - Start the client(s)

If you will not have a Fedora Synergy client move on to Step 5.

Next you start the client on each computer that will share the server's keyboard and mouse.

To start a client on Fedora, enter the following:

synergyc -f server-host-name

where server-host-name is replaced by the host name of the computer running the Synergy server. If synergyc is not in your PATH then use the full pathname.

When you added the client to the server's configuration you chose a name for the client. If that name was not client's host name then you must tell the client the name you used. Instead of the above command use this instead:

synergyc -f --name name server-host-name

where name is the name for the client in the server's configuration.

Step 5 - Test

Clients should immediately report a successful connection or one or more error messages. Some typical problems and possible solutions are below. See the troubleshooting and the FAQ pages for more help.

failed to open screen (X11 only)
Check permission to open the X display;
check that the DISPLAY environment variable is set
use the --display command line option.
address already in use
Another program (maybe another copy of Synergy) is using the Synergy port; stop the other program or choose a different port in the Advanced... dialog. If you change the port you must make the same change on all of the clients, too.
connection forcefully rejected
The Synergy client successfully contacted the server but Synergy wasn't running or it's running on a different port. You may also see this if there's a firewall blocking the host or port. Make sure Synergy is running on the server and check for a firewall.
already connected
Check that the Synergy client isn't already running.
refused client
Add the client to the server's configuration file.
connection timed out
Check that server-host-name is correct.
Check that you don't have a firewall blocking the server or Synergy port.
connection failed
Check that server-host-name is correct.

If you get the error "Xlib: No protocol specified" you're probably running Synergy as root while logged in as another user. X11 may prevent this for security reasons. Either run Synergy as the same user that's logged in or (not recommended) use "xhost +" to allow anyone to connect to the display.

When successful you should be able to move the mouse off the appropriate edges of your server's screen and have it appear on a client screen. Try to move the mouse to each screen and check all the configured links. Check the mouse buttons and wheel and try the keyboard on each client. You can also cut-and-paste text, HTML, and images across computers (HTML and images are not supported on OS X yet).

Step 6 - Run

Once everything works correctly, stop all the clients then the server. Then start the server with the Start button on Windows and without the -f option on Unix and Mac OS X. Finally start the clients similarly. On Windows before clicking Start you may want to set the Logging Level to Warning so the logging window doesn't pop up (because you currently can't close it, just minimize it).

You can also configure Synergy to start automatically when your computer starts or when you log in. See steps 8 and 9 below for more information.

Command Line Options Guide

Common Command Line Options
The following options are supported by synergys and synergyc.

-d, --debug level use debugging level level

--daemon
run as a daemon (Unix) or background (Windows)

-f, --no-daemon
run in the foreground

--display display connect to X server at display (X11 only)

-n, --name name
use name instead of the hostname

--restart
automatically restart on failures

-1, --no-restart
do not restart on failure

-h, --help
print help and exit

--version
print version information and exit

Debug levels are from highest to lowest: FATAL, ERROR, WARNING, NOTE, INFO, DEBUG, DEBUG1, and DEBUG2. Only messages at or above the given level are logged. Messages are logged to a terminal window when running in the foreground. Unix logs messages to syslog when running as a daemon. The Windows NT family logs messages to the event log when running as a service. The Windows 95 family shows FATAL log messages in a message box and others in a terminal window when running as a service.

The --name option lets the client or server use a name other than its hostname for its screen. This name is used when checking the configuration.

Neither the client nor server will automatically restart if an error occurs that is sure to happen every time. For example, the server will exit immediately if it can't find itself in the configuration. On X11 both the client and server will also terminate if the connection to the X server is lost (usually because it died).

Server Command Line Options
synergys [options]
The server accepts the common options and:

-a, --address address listen for connections on address address

-c, --config pathname read configuration from pathname

address has one of the following forms:
hostname
:port
hostname:port
hostname is a hostname or IP address of a network interface on the server system (e.g. somehost or 192.168.1.100). port is a port number from 1 to 65535. hostname defaults to the system's hostname and port defaults to 24800.

Client Command Line Options
synergyc [options] address[:port]
address is the hostname or IP address of the server and port is the optional network port on the server to connect to. The client accepts the common options.

Step 7 - Autostart basics

Synergy requires an X server. That means a server must be running and Synergy must be authorized to connect to that server. It's best to have the display manager start Synergy. You'll need the necessary (probably root) permission to modify the display manager configuration files. If you don't have that permission you can start Synergy after logging in via the .xsession file.

Typically, you need to edit three script files. The first file will start Synergy before a user logs in, the second will kill that copy of Synergy, and the third will start it again after the user logs in.

The contents of the scripts varies greatly between systems so there's no one definite place where you should insert your edits. However, these scripts often exit before reaching the bottom so put the edits near the top of the script.

The location and names of these files depend on the operating system and display manager you're using. A good guess for the location is /etc/X11. If you use kdm then try looking in /etc/kde3 or /usr/kde/version/share/config. Typical file names are:

	xdm	kdm	gdm
1	xdm/Xsetup	kdm/Xsetup	gdm/Init/Default (*)
2	xdm/Xstartup	kdm/Xstartup	gdm/PostLogin/Default (*)
3	xdm/Xsession	kdm/Xsession	gdm/Sessions/Default (, *)

*) The Default file is used if no other suitable file is found. gdm will try displayname (e.g. :0) and hostname (e.g. somehost), in that order, before and instead of Default.
**) gdm may use gdm/Xsession, xdm/Xsession or xdm/Xsession if gdm/Sessions/Default doesn't exist.

In Fedora gdm is the default so that is what I will be covering in this document. If someone would like to supply me with the files need for kdm I will gladly add that information to this document. For gdm the three files we will edit are in /etc/gdm. The files are Init/Default, PostLogin/Default and Xsession (Xsession is a symlink to /etc/X11/xinit/Xsession).

Step 8 - Configure the server to autostart

If you do not have a Fedora Synergy server move on to Step 9.

If you're configuring Synergy to start only after you log in then edit your .xsession file. Add just what you would add to the third file below.

For a Synergy client, add the following to the first (/etc/gdm/Init/Default) file:

/usr/bin/killall synergys
sleep 1
/usr/bin/synergys [<options>*] synergy-server-hostname

Of course, the path to synergys depends on where you installed it so adjust as necessary.

Add to the second (/etc/gdm/PostLogin/Default) file:

/usr/bin/killall synergys
sleep 1

And to the third (/etc/gdm/Xsession) file:

/usr/bin/killall synergys
sleep 1
/usr/bin/synergys [<options>*] synergy-server-hostname

*)Note that <options> must not include -f or --no-daemon or the script will never exit and you won't be able to log in.

The changes are the same for the Synergy server except replace synergyc with synergys and use the appropriate synergys command line options. Note that the first script is run as root so synergys will look for the configuration file in root's home directory then in /etc. Make sure it exists in one of those places or use the --config config-pathname option to specify its location.

Note that some display managers (xdm and kdm, but not gdm) grab the keyboard and do not release it until the user logs in for security reasons. This prevents a Synergy server from sharing the mouse and keyboard until the user logs in. It doesn't prevent a Synergy client from synthesizing mouse and keyboard input, though.

Step 9 - Configure the client(s) to autostart

If you do not have a Fedora Synergy client you are done.