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

synergy lets you easily share a single mouse and keyboard between
multiple computers through software.  it also merges each system's
clipboards into one, allowing cut-and-paste between systems.
redirecting the mouse and keyboard is as simple as moving the
mouse off the edge of your screen.


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
  synergy.linux.init                      startup script for client
  synergyd.linux.init                     startup script for server


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 "<direction> = <screen>" where <direction> is "left",
  "right", "up", or "down" and <screen> 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 <config-pathname>

  replacing <config-pathname> 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 <server-hostname>

  replacing <server-hostname> 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.  note that
there's a bug in this situation where keys may be left in the
logical pressed state;  see the "known bugs" section.

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.


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.  the DISPLAY env var
  should be set appropriately before starting synergy.  note that
  it probably will not be set when running startup scripts so you
  have to set it yourself (probably to ":0").

  if the X server goes down then all the clients connected to it
  must terminate.  synergy has to deal with this because some
  display managers will automatically restart the X server when
  a user logs out.  synergy can automatically restart itself and
  it does so by default.  the `--no-restart' option turns this
  feature off.

  some display managers also prevent any X client other than
  those they themselves start from connecting to the X server
  for security reasons.  for these display managers, synergy
  should be part of the manager's screen initialization script
  and synergy should be started with the --no-restart option
  since the display manager will do the restarting.  otherwise,
  synergy should not use the --no-restart option and it can be
  started at boot time (sometime after the network is started)
  or when the X server is started.

  finally, 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.

  to install synergy as a daemon, you'll need to add the
  appropriate lines and/or files to start synergy at boot time
  or as part of a display manager screen initialization script.
  do not use the `-f' or `--no-daemon' options.  for the server
  use the `--config' option to specify the path to the
  configuration file or just put the configuration in
  /etc/synergy.conf.

linux:
  if starting synergy from xdm's or kdm's screen initialization
  script you'll want add a line to start synergy in
  /etc/X11/xdm/Xsetup_0, probably near the bottom.  you'll also
  want to put the configuration file in /etc/synergy.conf and
  the synergy executable in /usr/sbin.  to uninstall, remove the
  added line and files.

  if starting the synergy client using init.d then:
    # /bin/cp synergy /usr/sbin/synergy
    # /bin/cp synergy.linux.init /etc/init.d/synergy
    # /sbin/chkconfig --add synergy

  if starting the synergy server using init.d then:
    # /bin/cp synergyd /usr/sbin/synergyd
    # /bin/cp synergyd.linux.init /etc/init.d/synergyd
    # /bin/cp synergy.conf /etc/synergy.conf
    # /sbin/chkconfig --add synergyd
  of course, /etc/synergy.conf should be edited your for systems.

  to manually start or stop the client
    # /etc/init.d/synergy start
    # /etc/init.d/synergy stop

  to manually start or stop the server
    # /etc/init.d/synergyd start
    # /etc/init.d/synergyd stop

  to uninstall the client:
    # /etc/init.d/synergy stop
    # /sbin/chkconfig --del synergy
    # /bin/rm /etc/init.d/synergy
    # /bin/rm /usr/sbin/synergy

  to uninstall the server:
    # /etc/init.d/synergyd stop
    # /sbin/chkconfig --del synergyd
    # /bin/rm /etc/synergy.conf
    # /bin/rm /etc/init.d/synergyd
    # /bin/rm /usr/sbin/synergyd
 

common command line options
---------------------------
  -d, --debug <level>   use debugging level <level>
      --daemon          run as a daemon (linux,unix) or background (windows)
  -f, --no-daemon       run in the foreground
  -n, --name <name>     use <name> instead of the hostname
      --restart         automatically restart on unexpected failures
  -1, --no-restart      do not restart on unexpected 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.


server command line options
---------------------------
  -a, --address <address>  listen for connections on the given address
  -c, --config <pathname>  read configuration from <pathname>

an address has one of the following forms:
  <hostname>
  :<port>
  <hostname>:<port>
<hostname> is a hostname or address of a network interface on the
server system.  <port> is a port number from 1 to 65535.


client command line options
---------------------------
  --camp                   retry connection to server until successful
  --no-camp                try connection to server only once
  <address>                address of server

see the "server command line options" for a description of <address>.


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:
  * screen savers are not handled
  * non-ASCII characters are not supported
  * keys may be left in the logical pressed state on a client if it
    terminates while the mouse is on that client.  physically pressing
    and releasing the key fixes the problem.
  * plain text is the only supported clipboard format

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
  * hook DLL sometimes not properly shutdown.  this is usually only
    a problem when forcibly killing the synergy server then trying
    to restart it.  logging off and on should fix it.

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:
  * one thread may linger if the application crashes.
    use kill or killall to terminate this process (threads are
    processes under linux) before restarting.
  * 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


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.