From GoBlueMich Wiki
Jump to navigation Jump to search

From the official synergy webpage: "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. It's intended for users with multiple computers on their desk since each system uses its own monitor(s)." Synergy is a very popular application in the Liquid Web office. This three-part guide details how to install synergy, configure it, and then tunnel it over SSH for a secure connection. By default, synergy transmits all keystrokes over plain text across our office network, which is NOT best practice. The problem is that synergy does not support any form of encryption, so a "tunnel" is used as a work-around. The concept of "tunneling" means that clients will be connected to your synergy server securely via SSH, and all synergy traffic will instead be piped through this SSH connection.

Template:Box Warning


Linux - Debian

sudo aptitude install synergy==Linux - Fedora==
sudo yum install synergy

Linux - Ubuntu

sudo apt-get install synergy==Linux - Gentoo==
sudo emerge -av synergy

Linux - Arch

sudo pacman -S synergy==Windows==
Download and install from:


Download and install from:


The first thing to decide is which machine will run the server, as the rest will connect as clients. I chose to make my workstation the server. The server configuration consists of customizing synergy.conf, and setting provisions for system settings.

Server Configuration - Linux

Create a configuration file in /etc called "synergy.conf":

sudo vi /etc/synergy.conf

This template can be used as a basic starting point. My setup has a laptop (HAL500), positioned left of my workstation (oscillator). The only fancy options I'm using map my mouse's back and forward buttons so that they still work on the client side. You can use this as a template for your own setup, just tweak accordingly. If you're curious about additional options that you can pass to synergy, see the external links section at the end of this document.

section: screens
section: aliases
section: links
                left = HAL500
                right =
section: options
        mousebutton(6) = keystroke(WWWBack)
        mousebutton(7) = keystroke(WWWForward)

You will need to ensure port 22 is open for SSH (or whatever your SSH port is).

sudo iptables -I INPUT -p tcp --dport 22 -j ACCEPT
sudo service iptables save

Create a new user on your Linux system for synergy and do not set a password for this user. (Setting no password will make this user unable to authenticate in your system.)

sudo useradd synergy

As the root user, "su" to the newly created user.

su synergyGenerate a DSA key (no pass-phrase)
ssh-keygen -t dsa

CD into /home/synergy/.ssh

cd /home/synergy/.sshChange the name of the file.
mv authorized_keys

The following commands will ensure permissions and ownership are correct.

chown synergy:synergy /home/synergy/.ssh
chown synergy:synergy /home/synergy/.ssh/authorized_keys
chmod 700 /home/synergy/.ssh
chmod 700 /home/synergy/.ssh/authorized_keys

Open authorized_keys for editing.

vi /home/synergy/.ssh/authorized_keys

Edit the file so that the following snippet is at the beginning. Your keyfile should start EXACTLY WHERE INDICATED!

command="/usr/bin/python -c 'import time; while 1: print time.time(); time.sleep(30.0)'",permitopen="" ORIGINAL_KEYFILE_CONTENTS_GOES_HERE (starts with ssh-dss)Save the file. Next, open the SSH daemon config for editing.
vi /etc/ssh/sshd_config

Ensure the following three lines are configured as follows. (Also uncomment these lines if they are commented out)

RSAAuthentication yes
PubkeyAuthentication yes
AuthorizedKeysFile     %h/.ssh/authorized_keys

Save the config file and restart the service.

sudo service ssh restart

Download and install sleepshell

cd /root
tar tvzf sleepshell_0.0.2.tar.gz
(cd into newly extracted directory)
make install

Make sleepshell the default environment for the synergy user

usermod -s /usr/local/bin/sleepshell synergy

Server Configuration - Windows

The Windows server setups is very straightforward, and handled entirely within the GUI. Be sure to allow synergy in the Windows public and private network firewalls (if you have them enabled). See the official Synergy homepage (linked at bottom of document) for any problems with configuring the Windows synergy server.

Server/Client Configuration Mac

The Mac software is very easy to use and very straightforward. Be sure to open any ports need ed in the Mac firewall, as ht


Client Configuration - Linux

Open TCP port 22 in your firewall

sudo iptables -I INPUT -p tcp --dport 22 -j ACCEPT
sudo service iptables save

If the synergy server is running Linux, copy the DSA key (id_dsa) that we created during the server setup into the client computer's /home/synergy/.ssh/ directory. Ensure permissions and ownership are same as before.

Client Configuration - Windows

Launch synergy from the start menu. Select "Use another computer's shared keyboard and mouse (client)". Other computer's Host Name should be set to "localhost", and close synergy for now as we're not ready to run it.

SSH Tunnel

Linux Clients

Linux comes with SSH pre-installed so no additional programs need to be installed. Also, the tunnel is initiated via command line so no further configuration is needed. The command to run your Linux client will be as follows:

synergy -c "/usr/bin/ssh -N -L 24800: -i /home/synergy/.ssh/id_dsa -l synergy YOURSERVERHOSTNAME"

Windows Clients

Copy the DSA key (id_dsa) that we created earlier to the Windows machine. Download putty.exe and puttygen.exe


PuTTY requires our id_dsa key to be converted into a key that it understands how to use. To do this, Launch puttygen.exe and select "Conversions --> Import Key" from the menu. Open the id_dsa file in the file browser and you should now see it in the puttygen window. Click "Save Private Key" to finish the conversion (no pass-phrase), and close puttygen. You should now have a new putty key saved as a .ppk file.

Launch PuTTY and create a new connection. Be sure to set the following:

Session ------------------->  Hostname: Should match server hostname in synergy.conf!
Session ------------------->  Port: 22
Session ------------------->  Close window on exit:  Always
Connection, Data ---------->  Auto-login username: synergy
Connection, SSH ----------->  Preferred SSH protocol version: 2 only
Connection, SSH, Auth ----->  Private key file for authentication:  Browse to the converted putty keyfile (.ppk)
Connection, SSH, Tunnels -->  Source port: 24800  
Connection, SSH, Tunnels -->  Destination:
Connection, SSH, Tunnels -->  Local & Auto (radio buttons)

Click "Add" to save the rule. Your rule should appear in the "Forwarded Ports" section and look exactly like this:


Click again on "Session", and enter a name for your SSH tunnel. Save this session as "synergy_tunnel". To initiate this tunnel automatically at boot-time, perform the following steps:

1.)  Create a shortcut to PuTTY on the desktop.

2.)  Right click the shortcut and select "Properties".

3.)  In the "Target" field, add your tunnel name and click OK to save it.
FORMATTING:  "C:\Program Files (x86)\Putty\putty.exe" -load "synergy_tunnel"

4.)  Move this shortcut to your Windows start menu's "Startup" folder to initiate it at boot time.  Synergy can also be configured to load at boot time via the program's interface if so desired.

Test and Troubleshooting


Testing - Linux

To start the synergy server in test mode, run the following command:

sudo synergys -f

The client can also be started in test mode. If you are unable to connect, try the following:

Check the output while starting synergys in "test" mode.
Check synergy.conf.  Synergy will not start if this is mis-configured.
Ensure the hostnames and IP addresses in synergy.conf are accurate, as these are the only IPs that have access to your synergy server.
Double check tunnel settings.  
Check server and client side firewall settings.

If all checks out, you can start the synergy server without invoking test mode. Synergy must be started like this to ensure it only listens on localhost:

sudo synergys -a

Testing - Windows

The main synergy window provides options for starting the program in test mode. Common problems include tunnel mis-configuration, and not allowing the program through Windows firewall. Please ensure that synergy is *only* listening to connections on localhost ( The wiki does not currently provide instructions for how to do this with the Windows version of Synergy.

External Links

Synergy Homepage
Synergy Button Map
Synergy for Mac
Sleepshell Homepage
Synergy Security
PuTTY SSH Tunnel guide
Mac SSH Tunnel Manager (optional)