Synergy
=======

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

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 display.

Redirecting the mouse and keyboard is as simple as moving the mouse
off the edge of your screen.  Synergy also merges the clipboards of
all the systems into one, allowing cut-and-paste between systems.
Furthermore, it synchronizes screen savers so they all start and stop
together and, if screen locking is enabled, only one screen requires
a password to unlock them all.

Synergy is open source and released under the GNU Public License (GPL).

The synergy home page is:
http://synergy2.sourceforge.net/

The synergy project page is:
http://sourceforge.net/projects/synergy2/

Report bugs to:
http://sourceforge.net/tracker/?func=add&group_id=59275&atid=490467


Please see the following files for more information:
AUTHORS   -- The list of synergy's authors
BUGS      -- A list of known bugs and limitations
COPYING   -- The license synergy is release under
FAQ       -- Frequently asked questions about synergy
HISTORY   -- A brief history of synergy
INSTALL   -- Detailed build and installation instructions
NEWS      -- News about the synergy project
PORTING   -- Porting guide for developers
TODO      -- List of things to add to synergy


System Requirements
-------------------

* All operating systems:
  keyboard,
  mouse,
  TCP/IP networking;

* Microsoft Windows 95, Windows 98, Windows Me (the Windows 95 family);

* Microsoft Windows NT, Windows 2000, Windows XP (the Windows NT family);

* Mac OS X 10.3 (10.2 may work);

* Unix:
  X Windows version 11 revision 4 or up with the XTEST extension
    (use `xdpyinfo | grep XTEST' to check for XTEST).

In this document, "Unix" means any of the following:  Linux, Solaris,
Irix.  Synergy may compile and run on other Unix variants, too.  Patches
for other platforms are welcome (including patches that package binaries);
See the contact information available off of the synergy home page or use
the patch page on sourceforge.

The Mac OS X port is incomplete.  It does not synchronize the screen saver,
only text clipboard data works (i.e. HTML and bitmap data do not work),
non-US English keyboards are untested and probably don't work, and there
may be problems with mouse pointer and mouse wheel acceleration.  Other
problems should be filed as bugs (see BUGS).


Installation
------------

See INSTALL for detailed build and installation instructions and for
more information on configuring synergy.


Quick Start
-----------
Synergy lets you use one keyboard and mouse across multiple computers.
To do so it requires that all the computers are connected to each other
via TCP/IP networking.  Most systems come with this installed.

The first step is to pick which keyboard and mouse you want to share.
The computer with that keyboard and mouse is called the "primary
screen" and it runs the synergy server.  All of the other computers
are "secondary screens" and run the synergy client.  The Windows NT
family, starting with NT 4 with service pack 3, and Unix are the best
choices.  The Windows version provides a convenient GUI for
configuration.

Second, you install the software.  Choose the appropriate package
and install it.  On Windows you should run SynergyInstaller.  You
must install the software on all the computers that will share the
mouse and keyboard.

Third, you configure and start the server.
  Windows
  -------
  Run `synergy' by double clicking on it.  This brings up a dialog.
  Configure the server:

  * Click the `Server' radio button
  * Click `Add' to add the server to the `Screens' list
    * Enter the name of server (the computer's name is recommended)
    * Enter other names the server is known by
    * Click OK
  * Use `Add' to add your other computers
    * Using a computer's name as its screen name is recommended
  * Use the controls under `Layout' to link screens together
    * Click (once) on the server's name in the `Screens' list
    * Choose the screen to the left of the server
      * Use `---' if there is no screen to the left of the server
    * Choose the screens to the right, above and below the server
    * Repeat the above steps for all the other screens
  * Use `Options...' to set desired options.
  * If the server's screen name is not the server's computer name:
    * Click `Advanced...'
    * Enter the server's screen name next to `Screen Name'
    * Click `OK'

  Now click `Test'.  The server will start and you'll see a console window
  with log messages telling you about synergy's progress.  If an error
  occurs you'll get a dialog box telling you synergy is about to quit;
  read the log messages to determine the problem then correct it and try
  `Test' again.

  Unix or MacOS X
  ---------------
  Create a text file named synergy.conf with the following:

	section: screens
	   <screen1>:
	   <screen2>:
	end
	section: links
	   <screen1>:
		   right = <screen2>
	   <screen2>:
		   left = <screen1>
	end

  Replace each occurrence of `<screen1>' with the host name of the
  primary screen computer and `<screen2>' with the host name of a
  secondary screen computer.  In the above example, <screen2> is to
  the right of <screen1> and <screen1> is to the left of <screen2>.
  If necessary you should replace `right' and `left' with `left',
  `right', 'up', or `down'.  If you have more than two computers
  you can add those too:  add each computer's host name in the
  `screens' section and add the appropriate links.

  Now start the server.  Normally synergy wants to run "in the
  background."  It detaches from the terminal and doesn't have a
  visible window, effectively disappearing from view.  Until you're
  sure your configuration works you should start synergy "in the
  foreground" using the `-f' command line option:

    synergys -f --config synergy.conf

  Check the reported messages for errors.  Use ctrl+c to stop synergy,
  correct any problems, and start it again.

Finally, start the clients.
  Windows
  -------
  Run `synergy' on the client by double clicking on it.  Configure the
  client:

  * Click the `Client' radio button
  * Enter the server's computer name in `Server Host Name'
    * Do not use any of the server's screen names, unless one of those
      is also the computer name
  * If the client's screen name is not the client's computer name:
    * Click `Advanced...'
    * Enter the client's screen name next to `Screen Name'
    * Click `OK'
  * Click `Test'

  If an error occurs you'll get a dialog box telling you synergy is
  about to quit;  read the log messages to determine the problem then
  correct it and try `Test' again.

  Unix or MacOS X
  ---------------

  To start a client, enter the following:

	synergyc -f <server-host-name>

  where `<server-host-name>' is replaced by the name of the computer
  running the synergy server.  If an error is reported use ctrl+c to
  stop synergy, fix the error, and try again.

Both the client and server should immediately report the connection
or an error.  If successful, you should now be able to move the
mouse off the appropriate edge of your server's screen and have it
appear on the client's screen.  If you're running the synery server
on Windows 95, 98, or Me then make sure the synergy log window is
not the active window;  just click on another window, like synergy's
`Running Test...' window, if it is.  Use the mouse and keyboard
normally except use the edge of the screens to jump to other screens.
You can also cut-and-paste across computers.  Currently, only text
transfers between computers.  Start the remaining clients.

Once the configuration is verified, see the instructions in INSTALL
under `Starting Automatically on ...' for details on running synergy
in the background and on starting synergy automatically when you start
your computers.


Tips and Tricks
---------------
* Be aware that not all keystrokes can be handled by synergy.  In
  particular, ctrl+alt+del is not handled.  However, synergy can
  convert ctrl+alt+pause into ctrl+alt+del on the client side.
  (Synergy must be installed as a service on the client for this to
  work on the Windows NT family.)  Some non-standard keys may not
  work, especially "multimedia" buttons, though several are
  correctly handled.

* 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 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 screen saver synchronization works best with xscreensaver
  under X windows.  Synergy works better with xscreensaver if it is
  using one of the screen saver extensions.  Prior to xscreensaver 4.0
  you can use `-mit-extension', `-sgi-extension', or `-xidle-extension'
  command line options to enable an extension (assuming your server has
  the extension).  Starting with 4.0 you must enable the corresponding
  option in your .xscreensaver file.

* Synergy automatically converts newlines in clipboard text (Unix
  expects \n to end each line while Windows expects \r\n).

* Clients can be started and stopped at any time.  When a screen is
  not connected, the mouse will jump over that screen as if the mouse
  had moved all the way across it and jumped to the next screen.

* A client's keyboard and mouse are fully functional while synergy is
  running.  You can use them in case synergy locks up.

* Strong authentication and encryption is available by using SSH.  See
  the INSTALL file for more information.  Synergy does not otherwise
  provide secure communications and it should not be used on or over
  untrusted networks.

* Synergy doesn't work if a 16-bit Windows application has the focus
  on Windows 95/98/Me.  This is due to limitations of Windows.  One
  commonly used 16-bit application is the command prompt (command.exe)
  and this includes synergy's log window when running in test mode.


Bug Reports
-----------

Synergy is being improved all the time but we can only fix problems
that we know about.  Please let us know of any problems you encounter,
including confusing or unhelpful documentation.  File reports at:

  http://sourceforge.net/tracker/?func=add&group_id=59275&atid=490467