synergy ------- synergy: [noun] a mutually advantageous conjunction of distinct elements synergy lets you easily share a single mouse and keyboard between multiple computers, each with its own display, using software only. redirecting the mouse and keyboard is as simple as moving the mouse off the edge of your screen. synergy merges the clipboards of all the systems into one, allowing cut-and-paste between systems. it also synchronizes screensavers so they all start and stop together and, if screen locking is enabled, only one screen requires a password to unlock them all. system requirements ------------------- all systems: keyboard mouse TCP/IP networking Microsoft Windows 95, Windows 98, Windows Me (the Windows 95 family): ??? MB RAM Microsoft Windows NT, Windows 2000, Windows XP (the Windows NT family): ??? MB RAM Linux, Unix: ??? MB RAM X Windows, revision 4 or up with the XTEST extension use `xdpyinfo | grep XTEST' to check manifest -------- linux windows ----- ------- README README this file synergy synergy.exe the synergy client synergyd synergyd.exe the synergy server synrgyhk.dll the synergy hook dll synergy.conf synergy.conf sample configuration file running synergy --------------- synergy is simple to configure. the server uses a configuration file and command line options while the client uses only command line options. it's recommended that both the client and server be run in the foreground until the configuration is verified to work. step 1: create a configuration file edit the sample configuration file. there are two sections you must fill in and a third optional section. you should delete the existing lines inside the sections. in the "screens" section, add a line for each computer you'll be using (server and clients). put the hostname of the computer followed by a colon (with no space in between). the computers can be listed in any order. in the "links" section you define how screens are connected. each screen is listed as in the "screens" section except following each screen is a list of links to other screens in the form " = " where is "left", "right", "up", or "down" and is a screen listed in the "screens" section. as an example, if we have "left=foo" under the "bar" screen then screen "foo" is on the left of screen "bar". the user will be able to move the mouse off the left edge of "foo" and will appear on the opposite (right) edge of "bar". note that it's entirely possible to have one-way (asymmetric) links and screens with only links into them. the latter should be avoided since there's no way to move the mouse off those screens. in the "aliases" section you can list other names for each screen. this is especially useful for dealing with fully qualified domain names versus simple hostnames. step 2: start the server the server is the system with the mouse and keyboard to be shared. each platform has its own tradeoffs when running as the server. see the release notes below for more information. run the synergy server on the server system using the following command line: synergyd -f --config replacing with the path to the configuration file. you can use `synergyd --help' for a list of command line options. step 3: start the clients on each client system start the synergy client using the following command line: synergy -f --debug INFO --no-camp replacing with the hostname or address of the server system. the client should quickly report `connected to server'. if it does not but doesn't print an error and exit immeditately then it's trying to connect to the server but cannot. it will time out in 30 seconds and exit (use ctrl+c to exit earlier). you should check that the server is running and try again. otherwise, if the client doesn't connect it should print an error describing the problem. here are typical problems and possible solutions: failed to open screen: check permission to open the X display; check that the DISPLAY environment variable is set. already connected: check that synergy isn't already running. refused client: add client to the server's configuration file. connection failed: check server-hostname; the server cannot open the desired port, stop the program using that port (24800) and restart the server. step 4: verify the configuration once the clients are connected, use the mouse to check that the screens are properly linked. moving the mouse off the edge of a screen with a link should cause it to appear on the opposite edge of the linked-to screen. using synergy ------------- using synergy is very easy. once clients have connected to the server all you do to redirect keyboard and mouse input to a screen (i.e. switch screens) is move the mouse cursor off the edge of the screen you're on. which edges go to which screens depends on the configuration. clients can be connected and disconnected at any time. until a client is connected, switching to it works as if you switched to it then moved all the way across it in the same direction and switched to the next screen. this repeats until you reach a connected screen. if there is no connected screen in that direction then the mouse will not leave the starting screen. disconnecting a client while the mouse is on it causes the mouse to instantly jump to the center of the server screen. the clipboard is automatically transferred between screens. if you copy on one screen you just switch to another screen and paste. note that X Windows has two major clipboards: the primary selection and the clipboard. synergy supports both. however, Microsoft Windows only supports the clipboard. the Windows clipboard is transferred to both the X primary selection and the clipboard. whichever X clipboard was changed last becomes the Windows clipboard. end-of-line sequences (LF on linux and unix, CRLF on Windows) are automatically converted as necessary. the clipboards are transferred using Unicode; if your platforms and applications understand Unicode then you should be able to cut and paste any Unicode character. synergy synchronizes screensavers. the screensavers on client screens are disabled when they connect to the server. when the primary screen's screensaver starts, the screensaver on each secondary screen starts too. all the secondary screensavers are stopped when the primary screensaver stops. moving the mouse or pressing a key will stop the primary screensaver, regardless of which screen the mouse was on when the screensavers started. if the primary screensaver requires a password to unlock then the user is prevented from switching to the secondary screens until the primary screen is unlocked. installing as a daemon/service ------------------------------ synergy can run in the foreground or as a daemon/service. it's recommended that you run it in the foreground until you've sorted out your configuration. on the Windows NT family you cannot run a service directly. instead you install the service then run or stop it via the Services control panel. on the Windows 95 family, you can use the `--daemon' command line option to start synergy as a service or you can install the service and restart your computer. in the text below, except where noted, synergy refers to the client and/or the server. windows: to install synergy just run one of the following: synergy --install [other command line options] synergyd --install [other command line options] the client/server is installed as a service and the command line is saved and used when starting the service. the system will expect to find the program wherever it was when you used the --install option so make sure it's not on a network share from another system because the network share will not be available at boot time. synergyd will also try to load synrgyhk.dll so that should be in the same directory as synergyd.exe. note that when installing the client you must provide the server hostname argument. to change the arguments you must first uninstall then reinstall. you must also install the configuration file along with the server. it's recommended that you put it in the windows directory (e.g. C:\WINNT) and call it "synergy.sgc". the server will automatically find this file. however, you can also use the --config command line option and specify an *absolute* path to the file. remember that this file must be accessible when the system starts up, before network shares are mapped. to uninstall use: synergy --uninstall synergyd --uninstall linux, unix: before starting synergy as a daemon you should understand that synergy requires an X server that it can connect to. synergy can start before the X server does and will repeatly attempt to connect to the X server until it succeeds. however, if the server requires authorization then it's unlikely that synergy will ever succeed. so, in general, synergy should be (re)started by the X display manager. some display managers (xdm and kdm, but not gdm) grab the keyboard and do not release it until the user logs in, also for security reasons. this prevents a synergy server from sharing the mouse and keyboard until the user logs in but it doesn't prevent a synergy client from synthesizing mouse and keyboard input. you should modify xdm's Xsetup script to start the synergy client or server. for example, somewhere near the bottom of Xsetup (but someplace before anywhere the script calls exit) you might add: /usr/bin/killall synergy /usr/sbin/synergy 192.168.1.101 this assumes synergy is installed in /usr/sbin. these lines make sure any already running synergy is terminated and starts a fresh copy. it's important to kill old copies so that you don't end up with multiple synergy instances fighting each other or, at the very least, using up system resources. to start the synergy server you might use: /usr/bin/killall synergyd /usr/sbin/synergyd --config /root/synergy.conf assuming synergyd is installed in /usr/sbin. if you've put the configuration data in /etc/synergy.conf then you don't need the --config option. another option is to put the synergy startup in .Xsession in your home directory. that allows users without root access to start synergy when they login. in this case synergy will not be running while on the login screen. common command line options --------------------------- -d, --debug use debugging level --daemon run as a daemon (linux,unix) or background (windows) -f, --no-daemon run in the foreground -n, --name use 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 --install install as a service (windows) --uninstall uninstall service (windows) 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 screen configuration. on X11 both the client and server will also terminate if the connection to the X server is lost. since xdm will normally restart the server and then synergy this is the correct behavior. server command line options --------------------------- -a, --address
listen for connections on the given address -c, --config read configuration from
has one of the following forms: : : is a hostname or address of a network interface on the server system. is a port number from 1 to 65535. defaults to the system's hostname and defaults to 24800. client command line options --------------------------- --camp retry connection to server until successful --no-camp try connection to server only once
address of server see the "server command line options" for a description of
but note that there is no default though there is a default . release notes ------------- synergy does not yet fully capture all possible input or have full control over the mouse and keyboard on all platforms. each platform has its own limitations and these limitations may influence your choice for the server. the following lists enumerate the limitations of each platform. a key (combination) that cannot be captured is not detected by synergy. a key (combination) that cannot be blocked will be passed through to the server system even when the mouse is on a client system. if a key cannot be captured then it also cannot be blocked. windows 95 family, windows NT prior to service pack 3: * cannot capture: * ctrl+alt+del * ctrl+esc * alt+[shift+]tab * alt+[shift+]esc * windows+E * windows+[ctrl+]F * windows+[shift+]M * windows+R * windows+F1 * windows+tab * windows+break * accessibility shortcuts (e.g. press shift 5 times for sticky keys) * the individual keys are captured but the dialogs still appear * cannot synthesize: * accessibility shortcuts windows NT family (except NT prior to SP3): * cannot block: * ctrl+alt+del * accessibility shortcuts (e.g. press shift 5 times for sticky keys) * the individual keys are captured but the dialogs still appear * cannot synthesize: * accessibility shortcuts linux, unix: * cannot capture: * ctrl+alt+del * ctrl+alt+backspace (only if used by the X server) * ctrl+alt+keypad_plus (only if used by the X server) * ctrl+alt+keypad_minus (only if used by the X server) * keyboard/mouse grabs prevent switching screens for their duration * some display managers grab the keyboard until login currently, the windows NT family (except NT prior to SP3) makes the best server. known bugs ---------- all: * non-ASCII keyboard characters are not supported windows: * screen flashes when entering the screen * synergy may interfere with desktop switcher programs. however, synergy understands and handles multiple desktops. * there should be a control panel * there should be a taskbar icon windows 95 family: * typing into a console window can be slow windows NT family: * the event viewer reports a message lookup error for synergy logs. however, the full synergy message is in the extra data portion of the event dialog. * does not gracefully handle NoInteractiveServices being enabled linux: * some keyboards have toggle keys that toggle on on key press and toggle off on the key release after the next key press. synergy doesn't handle these properly. * shift-lock (as opposed to caps-lock) is not supported * large (~256k) motif clipboard items are not copied properly tips and tricks --------------- * a screen can be its own neighbor. that allows a screen to "wrap". for example, if a configuration linked the left and right sides of a screen to itself then moving off the left of the screen would put the mouse at the right of the screen and vice versa. * you cannot switch screens when a key or mouse button is pressed. * you cannot switch screens when the scroll lock it toggled on. use this to prevent unintentional switching. * turn off mouse driven virtual desktop switching on X windows. it will interfere with synergy. use keyboard shortcuts instead. * synergy's screensaver synchronization works best with xscreensaver under X windows. synergy works better with xscreensaver if it is using of the screensaver extensions. prior to xscreensaver 4.0 you can use `-mit-extension', `-sgi-extension', or `-xidle-extension' command line options to enable an extension. starting with 4.0 you must enable the corresponding option in your .xscreensaver file.