Control Everything from One Place with Synergy

What is synergy? The dictionary defines it as an “advantageous conjunction of distinct elements”. The Synergy utility achieves this conjunction by transparently sharing a single keyboard and mouse between two or more computers using a TCP/IP network. Synergy also shares selected text and clipboard selections with full ICCCM (Inter-Client Communication Conventions Manual) and Unicode support. It automatically translates linefeeds between UNIX and Windows formats, enabling cut and paste across systems as easily as within a single system. In addition, it forces screensavers to activate and deactivate in concert. In short, each computer uses its own display(s), and you simply roll the mouse off the edge of one display to jump to another. So, it's almost like having one big desktop spread across multiple computers.

Synergy provides a software replacement for keyboard/mouse (KM) switchboxes. It currently runs on Linux and Windows and has preliminary support for Solaris; any combination of these platforms works. This article describes how to install and configure Synergy between two (or more) Linux boxes. Configuration usually takes only a few minutes.

First, download the latest stable version of Synergy from SourceForge (sourceforge.net/projects/synergy2). Then follow the usual steps:

tar xzf synergy-X.Y.Z.tar.gz
cd synergy-
./configure
make
su -c 'make install'

where X.Y.Z is the version number. You can install a prebuilt RPM instead, which is also available from the site. Executables are installed in /usr/local/bin unless you provided a different location to configure. Repeat this process on each computer to be connected or simply copy over the binaries (synergyc and synergys).

Next, choose the server, the system with the keyboard and mouse physically connected to it. This system requires a Synergy configuration file that names the server, the computers that may connect (the clients) and their virtual screen arrangement. It's a plain-text file with two required and one optional sections. Here's an example configuration file:

section: screens
  guava:
  mango:
end
section: links
  guava:
    right = mango
    up    = guava
  mango:
    left  = guava
end
section: aliases
  guava:
    guava.tropical-fruit.org
  mango:
    mango.tropical-fruit.org
end

The screens section simply lists the server hostname and the hostnames of all permitted clients. The links section describes the virtual adjacency of the computers. For example, guava lists mango as being located to its right, so when the mouse moves off the right edge of guava it appears at the opposite (i.e., left) edge of mango. Each computer can have at most one of each of the following directions listed: left, right, up and down. A computer also can link to itself; in this example, moving off the top of guava will move the mouse to the bottom of guava.

Links are not automatically symmetric. Making the jump to mango reversible requires that guava is listed as being to the left of mango. This feature becomes more useful with more than two computers. For example, a third computer, banana, could be up from guava and mango, but only one of those could be down from banana.

The third section, aliases, is optional. Clients provide their hostname (or a name specified on the command line) to the server when connecting, so the server can find them in the configuration. Some systems report their fully qualified domain name, others list only their hostname, depending on their network configuration. The aliases section, as it suggests, provides a list of names that each computer is known as. The above configuration permits mango to connect as mango or mango.tropical-fruit.com. The server also checks the aliases when looking up its own name.

You may have noticed the configuration file doesn't indicate whether guava or mango is the server. That's because doing so isn't necessary. This configuration works as is with either system as the server. For this example, we'll assume guava is the server. Prepare a configuration file for your particular setup using the above example as a template, and save it to $HOME/.synergy.conf.

Now start the Synergy server:

synergys -f -1

We cover the meaning of the options later on. The server logs some messages to the shell, and if all goes well, it's ready and waiting for connections. Any links from the server to itself in the configuration should work at this point. On guava we could move the mouse off the top edge of the screen, and it would jump to the bottom edge.

With the server running, you're ready to connect a client system. On your other system (mango in our example) start the client with:

synergyc -f -1 --no-camp guava

replacing guava with the hostname or network address of your server. The client also logs some messages to the shell and either connects to the server or quits with an error. If it connected successfully you can now use the mouse, keyboard and clipboard between the two systems. Test any other clients in the same way.

If the command-line options are invalid or the configuration file has an error, Synergy writes an error message to the shell and quits. If the server or client fails for some other reason, you'll receive a log message prefixed by ERROR or FATAL briefly describing the problem. Space here doesn't permit a complete list of errors, but the message should provide enough information to diagnose the problem.

The command-line options used above indicate that the client and server should run in the foreground, messages should be logged to the shell (-f) and the system should quit when a nonpermanent error occurs (-1). By default, both the client and server run in the background, messages are logged to syslog and the system waits a few seconds then retries after non-permanent errors. The --no-camp option tells the client to quit after the server forcefully closes a successful connection. Normally the client cleans up then tries connecting again; more on that below. A few other options are available; use --help to see a list.

Once you've tested the server and client(s), you'll probably want them to start automatically in the future. Synergy requires an X server, so starting it before the X server starts won't work. The easiest way to start Synergy automatically is to add a line to your $HOME/.xsession or similar X session startup script. Typically, you'd run the Synergy server from .xsession with no arguments and run the client with the server hostname as the only argument. They'd run in the background and quit when the X server quits or restarts.

The problem with this setup is Synergy isn't running during the login screen, which is managed by XDM or one of the eqivalents such as GDM or KDM. If you have the necessary permissions, you can reconfigure your display manager to start Synergy when the X server starts. First, copy $HOME/.synergy.conf to /etc/synergy.conf (no leading dot on the latter) so the display manager can find it. Then edit the display manager's Xsetup script; different distributions put this file in different places so you may have to search for it. Near the end of the script but before any call to exit add two lines. You can use either:

/usr/bin/killall synergyc
/usr/local/bin/synergyc guava

replacing guava with the hostname of your server to start the client, or:

/usr/bin/killall synergys
/usr/local/bin/synergys

Without the --no-camp option, the client tries connecting to the server every 60 seconds until it succeeds, so the client can start before the server. You can exploit this feature on a laptop: run the client on the laptop all the time. When it's attached to your home network, it'll connect to the Synergy server within 60 seconds. Then you can use the server's keyboard and mouse instead of the laptop's.

Finally, an important note about security. As of this writing, Synergy has no authentication and no encryption safeguards. Because it transmits all mouse and keyboard input, including passwords, do not use Synergy on or across untrusted networks. Future versions of Synergy will address this shortcoming.