How-To: Share your keyboard and mouse in realtime with Synergy
Synergy is an open source and free software project that allows one to share a keyboard and mouse across multiple monitors on separate computers and even between different operating systems. You may be a prime candidate for Synergy's superb um... synergy if you code multi-platform software, use more than one computer at home such as a laptop and a tower, or if your computers have different functions (media server, net machine, etc.). Personally we do all of the above and were in dire need of a swift way to dispose of our old keyboards and mice to make way for all sorts of fun new usb gadgetry.
Step 1: Installing Synergy
Step 2: Collecting the Screen Name of each Computer
Step 3: Setting up the Server
Step 4: Setting up the Clients
Step 5: Testing Synergy
Step 6: Auto-launching a Synergy server or Synergy clients
Step 7: Tips and Tricks
(W) = Windows instructions
(M) = Macintosh OS X instructions
(U) = Unix-like system (*nix) instructions
To participate in this How-To you will need at least two computers, each with their own monitor (or a laptop with a screen), one keyboard, one mouse, and a local network connection between the computers. You will eventually need to know the name of each machine. In some cases the IP address associated with a machine will be required. If you are planning on running these applications on Mac OS X you may need to use a text editor such as BBEdit (or the free TextWrangler) if you are not familiar with a command line text editor such as vi.
Synergy works on and between most operating systems; it works with various flavors of Windows, Macintosh OS X.2 and higher, and unix-like operating systems with X installed. In this How-To we will concentrate on installations that include Windows XP and Macintosh OS X with a brief smattering of generic *nix tips.
The usual caveats against your computer not functioning after following any of these instructions apply: use at your own risk. These instructions are provided as a friendly How-To and are not necessarily endorsed by the Synergy project.
Step 1: Installing Synergy
First, download the synergy package and install it on each machine. The newest version of all the downloads can be found on Synergy's sourceforge page. Under the "Binaries" heading the Windows download is an .exe file and the Mac build is an OSX.PPC.tar.gz file. If you are installing Synergys on a unix-like system from source, choose your compression flavor of choice (we prefer .gz on linux/bsd) under the "Sources" heading and download the package to compile Synergy yourself.
(W) The Windows installation is trivial. Double-click on the SynergyInstaller-1.x.x.exe program. Leave "Start Menu Shortcuts" selected. Choose and install location (default C:\Program Files\ is just fine). When it's done click "Close". Launch Synergy (either from C:\Program Files\Synergy or from the Windows start menu). Synergy is now installed on your machine. Read on for configuration instructions further down.
(M) For Macintosh OS X (X.2 and higher reportedly works, but we've only tested Synergy on X.3/X.4), double click on the synergy-1.x.x-x.OSX.PPC.tar.gz file to uncompress it. Open the resulting synergy-x.x.x folder. On your computer create a new folder in your home directory called bin. The home directory is otherwise known as ~/ or more specifically on mac os x /Users/yourname/ where "yourname" is your login name. Copy the "synergyc" and "synergys" binary files to the new folder /Users/yourname/bin/. Copy the "synergy.conf" file to your home directory (~/ or /Users/yourname/).
Launch the Mac OS X Terminal application (/Applications/Utilities/Terminal). Type:
PATH=$PATH:/Users/yourname/bin/
(where "yourname" is your login name. Note that there are no spaces in the PATH command.)
If you would like to be able to run Synergy on Mac OS X from this directory we've created without having to retype the path command every time you launch the terminal, you will have to edit a hidden file. Here is how you can do this without learning to use the unix command line. Obtain a text editor of some sort (we use BBEdit, but substitute the text editor of your choice —TextWrangler is the free version of BBEdit for OS X). In BBEdit choose File > Open Hidden... and open the .bash profile located in your home directory (/Users/yourname/.bashprofile). If it does not exist, simply click cancel and File > New > Text Document. If the file already exists or if the file is blank, simply add at the bottom: PATH=$PATH:/Users/yourname/bin/ (where "yourname" is your login name. Once again, note the lack of spaces.) Now go to File > Save As and choose .bash_profile in your home directory. Important! Before saving click on "Options" and select "(generic text file)" "None" and "Unix" then click "OK". Click "Save" and then "Replace" and then "Use ." to save over the original file.
If you are feeling a bit adventurous in OS X and/or have experience with unix commands, add the path line above to ~/.bash_profile using your favorite text editor inside the terminal. We usually add a path to /usr/bin/ and /usr/local/bin/ while we're at it.
Now if all the stars are aligned, when you launch your OS X terminal and type:
syner
then hit Tab, your shell should auto-complete the word "synergy" at which point it is up to you to choose synergys or synergyc and OS X will run it.
(U) For Unix-like operating systems (Linux, BSD, et al) after downloading the sources to your directory of choice and unpacking them, dance the standard *nix three-step:
./configure
make
make install
On FreeBSD5.4 you may simply download and install the port: cd /usr/ports/sysutils/synergy/ make install clean
We chose to save our compiled copies of Synergy in /usr/local/bin/ on our linux based systems; by default on FreeBSD5.4 they are placed in /usr/X11R6/bin/.
Next comes the fun part, we promise!
Step 2: Collecting the Screen Name of each Computer
Now comes the crucial decision: which computer will be the "server" and which computer(s) will be the "client"(s)? The easiest way to decide is to pick the computer with your favorite keyboard and mouse attached. If you have a choice of where to plug your favorite keyboard and mouse, set the computer with the most uptime as the "server" (read: the computer that is left running the most and isn't mobile).
To prepare for "Step 2: Setting up the Server", you need to collect the "Screen Name" of each client.
(W) On Windows clients this name can be changed at will within the Synergy application interface and does not necessarily have to be the computer's name. Launch the Synergy application and click on "Advanced..." and enter your "Screen Name" and click "OK". The example shown below has the "Screen Name" set to "myservername".
(M) On Macintosh this name is most easily found by navigating to System Preferences > Sharing. Find the "Computer Name". This name plus ".local" on the end is your Synergy "Screen Name". For example the Mac OS X machine with the name "mycutecomputername" would have a Synergy "Screen Name" of "mycutecomputername.local".
(U) On Unix-like systems the Screen Name is the pre-defined screen name of the computer and is located in your internet configuration file.
Step 3: Setting up the Server
Once you have chosen which computer will become the server, you must create a Synergy configuration file on that computer. This configuration file contains the name of the server, the names of each client, and the side of the screen where the mouse will exit and enter for each computer.
(W) If the Synergy "server" computer is running a flavor of Windows, the configuration file is part of the graphical user interface included with the download you have already installed. Launch the Synergy application and choose the "Server" radio button. If you haven't already done so, choose a name for the server computer itself by clicking on "Advanced...", entering your "Screen Name" and clicking "OK". Then, under the "Screens:" text-box, click on "Add". In this example we add the computer named "mycutecomputername.local".
In most cases you only have to fill in "Screen Name:" with the exact screen name of each client and the server that will be sharing the keyboard and mouse. Note that you MUST enter the name of the server in the "Add Screen" dialog box even though you have just named it in the "Advanced..." section.
Now the names of your clients and the name of your server should appear in the "Screens:" text-box. Select the first one of the list by clicking on it and decide how it should react with the other computers as far as placement. For example, we have "1. mycutecomputername.local" selected and have decided that when we move the mouse to the left side of "mycutecomputername.local"'s screen, it should end up on "myservername". Thus, we choose "myservername" in the "Left" drop-down menu:
We must also tell Synergy that when we move the mouse out the right side of "myservername" it should end up on "mycomputername.local". We now have a central "edge" between two monitors defined: myservername on the left, and mycutecomputername.local on the right.
A simple way to understand the configuration Left/Right/Above/Below is to keep this in mind: When you exit to the _ of "Screens:", you go to the name in the drop-down menu. Another lovely thing with Synergy is that you can actually have a wrap-around screen defined: in the example above we could define the layout of "Left:" and "Right:" to both be set to "myservername" for "1. mycutecomputernamelocal" as well as vice versa. This means that when I exit "mycutecomputername.local" to the Left OR to the Right, I always end up on "myservername". This can be either useful or annoying depending on your work style. Personally I like having monitor boundaries where the mouse can not escape because I set those corners as hot corners for my screen savers with required passwords.
Note: The clients in any of the server set-up situations can be of any type of operating system. Mac and Windows and Unix-like systems mix in a lovely cocktail of single keyboard/mouse goodness.
(M) Now we will demonstrate how to set up a Mac OS X computer as the server. In BBEdit do File > Open Hidden and open /Users/yourname/synergy.conf or /Users/yourname/.synergy.conf if you have already edited this file with this How-To. Now type your server/client configuration as follows:
section: screens
mycutecomputername.local:
myservername:
end
section: links
mycutecomputername.local:
left = myservername
myservername:
right = mycutecomputername.local
end
This example assumes you have two computers with two monitors. The monitor on the left belongs to "myservername" and the monitor on the right belongs to "mycutecomputername.local". When you move the mouse to the right edge of "myservername" it enters on the left edge of "mycutecomputername.local". Replace "mycutecomputername.local" and "myservername" with the "Screen Name" of each computer. Note that you have to include the server computer as well in the list. Now in BBEdit go to File > Save As... and save the file as .synergy.conf in /Users/yourname/ (your home directory). Important! Before saving click on "Options" and select "(generic text file)" "None" and "Unix" then click "OK". Click "Save" and then "Replace" and then "Use ." to save over the original file.
Another example of a configuration file is a situation where we have two monitors next to each other on a shelf and below the left hand monitor we have a laptop:
section: screens
rightcomputer:
leftcomputer.local:
laptop:
end
section: links
rightcomputer:
left = leftcomputer.local
leftcomputer.local:
right = rightcomputer
down = laptop
laptop:
up = leftcomputer.local
end
Note that the computer monitor on the left in the example above belongs to a Mac OS X machine because it has a name that ends in ".local". Also note that any of these computers can be a server, simply save the .synergy.conf file on the server computer's home directory.
Step 4: Setting up the Clients
(W) To set up a Windows client machine, launch the Synergy application and choose the "Client" radio button. First name the client if you have not already done so by clicking on "Advanced...", entering your "Screen Name" and clicking "OK". Next enter the IP address of the Synergy server machine and click "Start". For example if the Synergy server machine has an IP address of 192.168.1.3 your Synergy window would look like this:
A dialog box will pop up: "Synergy was successfully started. Use the task manager or tray icon to terminate it." Click "OK" in this box. Minimize the synergy status window. When you want to quit synergy on this client, close the synergy status window or alternatively log your user out of Windows.
(M/U) To set up a client on a Macintosh or a Unix-like system, you don't have to do anything special besides installing (see Step 1). To launch a client see Step 5.
Step 5: Testing Synergy
Launch the Synergy server:
(W)For Windows based servers simply start the Synergy application. (M/U)For Mac OS X and *nix computers start a terminal and type: synergys then press the return/enter key. Synergys runs in the background by default. If you get the error: command not found, go back to the installation instructions in Step 1.
Next launch the Synergy clients:
(W)On Windows this is once again achieved by launching the Synergy application.
(M/U)Mac OS X or *nix based clients are launched by opening a terminal and typing:
synergyc
where the network address is the IP address of your Synergy server. For example, if your Synergy server has an IP address of 192.168.1.3 you would type this in the terminal to launch the client:
synergyc 192.168.1.3
and press the return/enter key.
Your mouse should now be able to travel across your monitors/screens. If it does, congratulations! For trouble-shooting help see Step 7.
Step 6: Auto-launching a Synergy server or Synergy clients
You may end up adoring Synergy. This usually means you don't want to have to launch the server and then each of the clients every time you log-in, reboot, or move a computer. In this section we'll show you how to auto-launch on Windows and Mac OS X. A brief coverage for unix-like systems is at the end of this section.
(W)For Windows launch the Synergy program. Click on the "Automatic Startup: Configure..." button. By default Synergys is set up to auto-launch when your user name logs in. If this is the case the last sentence of this window will read: "Synergy is configured to start automatically when you log in." If you would like to manually launch Synergy instead, click on "When you Log In: Uninstall" and then "Close". This method works for both Synergy servers and Synergy clients.
(M)The way to auto-launch for Mac OS X is slightly convoluted. We will try to be as clear as possible. Keep in mind this example is to auto-launch a Synergy server. For the client auto-launch example see the next part of this section. There are two main steps to configure Synergy to auto-launch on Mac OS X. The first is to add the Terminal application to your Login Items. Go to System Preferences > Accounts > Login Items. Click on the "+" symbol and choose Applications > Utilities > Terminal and click on "Add". Now "Terminal" should have been added to the list of Applications in Login Items. Check the "Hide" checkbox to the left of the Terminal icon in the list to hide the auto-launched terminal and quit your System Preferences. (NOTE: Login Items may have a different name in OS X.3/X.2 but should work similarly.)
Secondly we will set up the Terminal to auto-launch synergys (Synergy server). Launch the Terminal (Applications > Utilities > Terminal) and open a new window (File > New Shell). Next go to File > Save As and name the file launchsynergy after navigating to the following directory: /Users/yourname/Library/Application Support/Terminal/ Check the "Open this file when Terminal starts up" checkbox. (*) Choose the "Execute this command (specify complete path)" radio button and enter the path:
b/Users/yourname/bin/synergys
Then delete the leading "b". (We have to add and then delete a leading letter because when you start with a leading slash OS X.4 forces us to change the "Where" save-to path instead of the "Execute this command" path. This is a bug.) Check the "Execute command in a shell" checkbox (if you do not check this, no application will be launched, this is another bug in OS X) and then click "Save":
To verify that everything works, quit the Terminal application then relaunch it. You should see something like:
Last login: Mon Aug 8 18:57:29 on ttyp1
Welcome to Darwin!
mycutecomputername:~ yourname$ /Users/yourname/bin/synergys
mycutecomputername:~ yourname$
This means that synergys has been launched and is running in the background. You can verify this by typing in the terminal:
top
and hitting the return/enter key. You should see synergys listed near the top of the "Command" column. To quit "top" type the letter "q". To make synergys stop at any time after launching, in a terminal type:
killall synergys
and hit the enter/return key or log-out of your user name or shutdown the computer.
To auto-launch synergyc (Synergy client) on Mac OS X follow the instructions above until the star (***) then:
Choose the "Execute this command (specify complete path)" radio button and enter the path:
b/Users/yourname/bin/synergyc 192.168.1.2
Then delete the leading "b" and instead of 192.168.1.2 use the IP address of your Synergy server. Check the "Execute command in a shell" checkbox and then click "Save":
To verify that the synergyc is working, quit the Terminal then relaunch it. You should see something like:
Last login: Mon Aug 8 18:57:29 on ttyp1
Welcome to Darwin!
mycutecomputername:~ yourname$ /Users/yourname/bin/synergyc 192.168.1.2
mycutecomputername:~ yourname$
This means that synergyc has been launched and is running in the background. You can verify this by typing in the terminal: top and hitting the return/enter key. You should see synergyc listed near the top of the "Command" column. To quit "top" type the letter "q". To make synergyc stop at any time after launching, in a terminal type: killall synergyc and hit the enter/return key or log-out of your user name or shutdown the computer.
(U)The auto-launch for unix-like systems can be achieved in many ways. The simplest way is to include "synergys" or "synergyc " in the script that launches your window manager and auto-launches other applications. For example, on FreeBSD5.4, our fluxbox window manager is launched by the config file /usr/X11R6/lib/X11/xinit/xinitrc the end of which is:
# start some programs
#
startfluxbox &
synergyc 192.168.1.2 &
aterm -geometry 93x21+5+5
# this script launches the synergy client when the x window session is launched
Step 7: Tips and Tricks
Static IP addresses are your friends. Try to get a fixed IP address assigned to each machine. This is practically necessary for auto-launching clients and servers.
If you have a screen "edge" you have defined that doesn't seem to allow the mouse to "pass through" it, make sure you have accurately defined the IP address of the server when you launched the client. Next make sure your "Screen Names" in the server set up are all correctly spelled. Thirdly make sure you can ping the server from the client and the client from the server. If not, perhaps you have a network cable unplugged or have misconfigured your network settings.
If you have a screen "edge" that behaves backwards or differently than the way you thought it would, simply replace Left with Right or Above with Below in the configuration file (see Step 3).
Synergy may create vulnerabilities on your computer. If you are concerned about this read the Synergy Network Security Guide on Synergy's homepage.
It is handy to keep the extra old keyboards and mice on hand when having trouble auto-launching (see Step 6) and when initially setting up Synergy. Some operating systems may not appreciate having only a USB keyboard plugged in when booting in certain modes and may actually require a PS2 keyboard plugged in to boot. An easy trick if you are ready to ditch your keyboard on a finicky computer is to plug one of those cheap green PS2 male to USB A female adapters in the PS2 port in the computer to trick it into thinking there is a keyboard plugged in. These little adapters often come free with most USB keyboards to allow backward compatibility with older machines and to free up USB ports. Ask your friends, they may have an extra one of these adapters laying around.
Another note about extra keyboards: If you have an operating system that requires you to log in, you will need a keyboard physically attached to the computer to type your name and password. The instructions for auto-launching (Step 6) are only to auto-launch on a per-user basis. If you would like to launch a Synergy client or Synergy server when the computer boots, please see the Autostart Guide on Synergy's homepage.
If you have a keyboard that behaves weirdly with respect to capslock/numlock/ctrl/alt, etc. see the "A screen can have the following options:" section here. These settings can also be set in the graphical Windows Synergy application window under the "Add" dialog under "Options" and "Modifiers".
Enjoy your glorious multi-monitor multi-platform single-keyboard+mouse party!
