added files for release.

This commit is contained in:
crs 2002-08-01 18:07:48 +00:00
parent 3f13217929
commit ffea42bf91
8 changed files with 5545 additions and 406 deletions

1
AUTHORS Normal file
View File

@ -0,0 +1 @@
Chris Schoeneman <crs23@bigfoot.com>

102
BUGS Normal file
View File

@ -0,0 +1,102 @@
This file lists the known bugs in synergy.
Report bugs to: synergy@groundhog.pair.com
When reporting bugs, please include the version of the operating
system you're using and what locale you use.
* Not all keystrokes are handled
Certain keystrokes are not captured by the synergy server and,
therefore, are not transmitted to secondary screens. Which keys
depends on the primary screen's platform:
Linux:
* 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)
Windows NT family (except NT prior to service pack 3)
* ctrl+alt+del
* accessibility shortcuts (e.g. pressing shift 5 times for sticky keys)
Windows 95 family (at NT prior to service pack 3)
* 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)
* Non-ASCII keystrokes unsupported
Only ASCII characters are decoded and transmitted by the server.
However, the clipboard does support Unicode.
* Screen flashes (Windows)
On Windows, the primary screen flashes when the cursor enters it.
This is a consequence of how synergy captures input.
* Slow console text entry (Windows 95 family)
Typing into a command prompt window on the Windows 95 family has
very slow visual feedback.
* Event logs (Windows NT family)
Synergy doesn't support event logs properly on the Windows NT family.
In particular, the event message is reported in the extra data portion
of the event instead of the normal message portion.
* NoInteractiveServices not handled (Windows NT family)
Synergy does not (cannot) work when the NoInteractiveServices registry
entry is set. Synergy doesn't not gracefully handle it being set.
* Incorrectly hiding screen savers in certain situations (Windows)
If turning off the screen saver on the primary screen requires a
password on Windows then all of the secondary screen screen savers
are deactivated when the password dialog appears. If the password
is not entered only the primary screen's screen saver is activated.
* Not handling strange keyboards (X11)
Synergy does not detect keyboards with unusual behavior and may
misbehave as a result. Unusual behavior includes keyboards that
don't report KeyRelease events and toggle keys that report KeyPress
when toggled on and KeyRelease when toggled off (instead of KeyPress
and KeyRelease for each physical press and release).
* Not handling mode-switch and shift-lock (X11)
Synergy neither handles the mode-switch key nor shift-lock behavior
(as opposed to caps-lock).
* Large Motif clipboard items are truncated (X11)
Synergy doesn't yet fully implement Motif's protocol for large
clipboard items. As a result it silently truncates those items.
Large depends on the X server but is probably around 256kB.
Synergy also doesn't support by-name Motif clipboard items. It
will read no data at all for those items.
* Automake isn't fully configured (Linux)
The automake configuration isn't complete so synergy won't build
properly on some (many) systems.
* Only text is supported on the clipboard
The clipboard supports Unicode and current locale encoded text but
there are numerous other data types it should support, e.g. images,
sound, raw binary data, etc.

283
COPYING Normal file
View File

@ -0,0 +1,283 @@
Synergy is copyright (C) 2002 Chris Schoeneman.
Synergy is distributed under the following license.
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

4617
ChangeLog Normal file

File diff suppressed because it is too large Load Diff

9
FAQ Normal file
View File

@ -0,0 +1,9 @@
Frequently Asked Questions about synergy.
This will be added to as questions come in.
1. ctrl+alt+del doesn't work on secondary screens.
Synergy isn't able to capture ctrl+alt+del on PC compatible
systems because it's handled completely differently than
other keystrokes. If you need to use ctrl+alt+del you'll
have to keep your other keyboards handy just for that.

352
INSTALL Normal file
View File

@ -0,0 +1,352 @@
Installation instructions for synergy.
Prerequisites for building
--------------------------
To build synergy from the sources you'll need the following:
Windows:
* VC++ 6.0 or up
Linux:
* gcc 2.95 (or up?)
* X11R4 or up headers and libraries
If building from CVS on Linux you'll also need:
* autoconf 2.52 (older versions may work)
* automake 1.5 (older versions may work)
Configuring the build
---------------------
This step is only necessary when building on Linux.
If you're building synergy from CVS you need to create the configure
script and the Makefile.in files. To do that:
% aclocal
% autoheader
% autoconf
% automake
To configure the build for your platform use the configure script:
% ./configure
For a list of options to configure use:
% ./configure --help
Building
--------
Windows:
Start VC++ and open `synergy.dsw'. Set the active configuration
(Build | Set Active Configuration) to `All - Debug' or `All - Release'.
Then build.
VC++ 6.0 cannot handle project files that lack \r\n newlines. If you
retrieved synergy via CVS then the files should be fine. But if the
workspace appears to be empty then close VC++ and add \r to each line.
A convenient way to do that is to get `fixcrlf.exe' from the Internet,
search the synergy files for `*.dsp' and drag-and-drop all the project
files onto fixcrlf.exe.
Binaries are built into ./Debug or ./Release.
Linux:
Simply enter:
% make
This will build the client and server and leave them in their
respective source directories.
Installing
----------
Windows:
There is no support for creating an installer for synergy or installing
the files in a particular location. The only requirement for installed
files is that synrgyhk.dll is in the same directory as synergyd.exe or
in one of the system directories.
Linux:
% make install
will install the client and server into /usr/local/bin unless you
specified a different directory when you ran configure.
See `Starting Automatically' for details on how to have synergy start up
automatically when the computer starts.
Configuring the Server
----------------------
The synergy server requires configuration. The configuration file is a
plain text file broken into sections. Each section has the form:
section: <name>
<args>
end
Comments are introduced by `#' and continue to the end of the line.
The file can have the following sections.
* screens
<args> is a list of screen names, one name per line, each
followed by a colon. Names are arbitrary strings but they
must be unique. The hostname of each computer is recommended.
There must be a screen name for the server and each client.
Example:
section: screens
moe:
larry:
curly:
end
This declares three screens named: moe, larry, and curly.
* links
<args> is a list of screen names just like in the `screens'
section except each screen is followed by a list of links.
Each link has the form `<left|right|up|down> = <name>'.
A link indicates which screen is adjacent in the given
direction.
Example:
section: links
moe:
right = larry
up = curly
larry:
left = moe
up = curly
curly:
down = larry
end
This indicates that screen `larry' is to the right of screen
`moe' (so moving the cursor off the right edge of moe would
make it appear at the left edge of larry), `curly' is above
'moe', `moe' is to the left of `larry', `curly' is above
`larry', and `larry' is below `curly'. Note that links do
not have to be symmetrical; moving up from moe then down
from curly lands the cursor on larry.
* aliases
<args> is a list of screen names just like in the `screens'
section except each screen is followed by a list of aliases,
one per line *not* followed by a colon. An alias is a
screen name and must be unique. During screen name lookup
each alias is equivalent to the screen name it aliases. So
a client can connect using its canonical screen name or any
of its aliases.
Example:
section: aliases
larry:
larry.stooges.com
curly:
shemp
end
Screen `larry' is also known as `larry.stooges.com' and can
connect as either name. Screen `curly' is also known as
`shemp'. (Hey, it's just an example.)
The synergy server will try certain pathnames to load the configuration
file if the user doesn't specify a path using the `--config' command
line option. `synergyd --help' reports those pathnames.
Running the Server
------------------
Run the server on the computer that has the keyboard and mouse to
be shared. You must have prepared a configuration file before
starting the server. The server should be started before the
clients but that's not required.
Run the synergy server on the server system using the following
command line:
synergyd -f --config <config-pathname>
Replace <config-pathname> with the path to the configuration file.
The `-f' option causes synergyd to run in the foreground. This is
recommended until you've verified that the configuration works.
If you didn't include the system's hostname in the configuration
file (either as a screen name or an alias) then you'll have to add
`--name <screen-name>' to the command line, where <screen-name> is
a name in the configuration file. You can use `synergyd --help'
for a list of command line options.
Running the Client
------------------
Run the client on all computers that aren't the server using the
following command line:
synergy -f --no-camp <server-hostname>
Replace <server-hostname> with the hostname or address of the
server system. The `-f' option causes synergy to run in the
foreground. The `--no-camp' prevents synergy from retrying to
connect to the server until it succeeds. Both are recommended
until you've verified that the configuration works. If you
didn't include the system's hostname in the configuration file
(either as a screen name or an alias) then you'll have to add
`--name <screen-name>' to the command line, where <screen-name>
is a name in the configuration file.
The client should quickly report `connected to server'. If it
does not but doesn't print an error and exit immediately 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 is reachable over
the network and try again.
If the client fails and exits 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.
Once all the clients are running, try moving the mouse to each
screen. Be sure to check all the configured links.
Starting Automatically
----------------------
You can setup synergy to start automatically when your computer does.
Windows:
Start the client or server normally except add `--install' as the
first option on the command line, followed by the usual options
except do not include `-f' or `--no-daemon'. This will install
synergy as a service that will be started at system boot.
On the Windows NT family you can start and stop the service at any
time using the Services control panel (under Administrative Tools
on Windows 2000 and XP). On the Windows 95 family you cannot
start or stop the service.
To uninstall the service, run the client or server with just the
`--uninstall' command line option.
Linux:
Synergy requires an X server. That means a server must be
running and synergy must be authorized to connect to that server.
It's best to have the display manager start synergy. You'll need
the necessary (probably root) permission to modify the display
manager configuration files. If you don't have that permission
you can start synergy after logging in via the .xsession file.
To have the display manager start synergy, edit the Xsetup script.
The location of this file depends on your installation. It might
be /etc/X11/xdm/Xsetup. Near the end of the file but before
anyplace the script calls exit, start the client with something
like:
/usr/bin/killall synergy
/usr/local/bin/synergy [<options>] <server-host-name>
<options> must not include `-f' or `--no-daemon'. Change the
paths as necessary. It's important to make sure no old copies
of synergy are running so they can't interfere with the new one.
To start the server use something like:
/usr/bin/killall synergyd
/usr/local/bin/synergyd [<options>] --config <config-pathname>
Again, <options> must not include `-f' or `--no-daemon'. If
the configuration pathname is one of the default locations then
you don't need the `--config' option.
Note that some display managers (xdm and kdm, but not gdm) grab
the keyboard and do not release it until the user logs in, for
security reasons. This prevents a synergy server from sharing
the mouse and keyboard until the user logs in. It doesn't
prevent a synergy client from synthesizing mouse and keyboard
input, though.
Common Command Line Options
---------------------------
-d, --debug <level> use debugging level <level>
--daemon run as a daemon (Linux) or background (Windows)
-f, --no-daemon run in the foreground
-n, --name <name> use <name> 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 only)
--uninstall uninstall service (Windows only)
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 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 synergy, this is the correct behavior.
Server Command Line Options
---------------------------
-a, --address <address> listen for connections on the given address
-c, --config <pathname> read configuration from <pathname>
<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. <hostname>
defaults to the system's hostname and <port> defaults to 24800.
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>
but note that there is no default <hostname> though there is a
default <port>.

5
NEWS Normal file
View File

@ -0,0 +1,5 @@
News about the synergy project.
* Initial version of synergy released. Supports ASCII keys, 5 button
wheel mouse, Unicode text clipboard, and screen saver synchronization.
Runs on Linux and Microsoft Windows.

582
README
View File

@ -1,427 +1,197 @@
synergy
-------
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.
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:
FIXME
The synergy project page is:
FIXME
Report bugs to:
synergy@groundhog.pair.com
system requirements
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
INSTALL -- Detailed build and installation instructions
NEWS -- News about the synergy project
PORTING -- Porting guide for developers
System Requirements
-------------------
all systems:
keyboard
mouse
TCP/IP networking
Microsoft Windows 95, Windows 98, Windows Me (the Windows 95 family):
??? MB RAM
* All operating systems:
keyboard,
mouse,
TCP/IP networking;
Microsoft Windows NT, Windows 2000, Windows XP (the Windows NT family):
??? MB RAM
* Microsoft Windows 95, Windows 98, Windows Me (the Windows 96 family);
Linux, Unix:
??? MB RAM
X Windows, revision 4 or up with the XTEST extension
use `xdpyinfo | grep XTEST' to check
* Microsoft Windows NT, Windows 2000, Windows XP (the Windows NT family);
* Linux:
X Windows version 11 revision 4 or up with the XTEST extension
(use `xdpyinfo | grep XTEST' to check for XTEST).
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
Installation
------------
See INSTALL for detailed build and installation instructions.
running 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, is the best choice
for the primary screen but Linux is good too. (This is based on the
known bugs; see BUGS for more details.)
Next you must install the software. You must install the synergy
server on the primary screen and the synergy client on all the
secondary screens. If it's easier just install both on all of the
systems.
Third, you create a configuration file for the server. Only the
server requires configuration. 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.
Finally, you start the server then all of the clients. 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.
To get a command line on Windows, choose Run... from the Start
menu. Type `cmd' if you're using the Windows NT family or
`command' if you're using the Windows 95 family and press enter.
To start the server, enter the following on the command line:
synergyd -f --config synergy.conf
To start a client, enter the following:
synergy -f <server-host-name>
where `<server-host-name>' is replaced by the name of the computer
running the synergy server.
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. 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.
Be aware that not all keystrokes can be handled by synergy. In
particular, ctrl+alt+del is not handled. You cannot use synergy
to log into a Windows NT family system that requires the user to
press ctrl+alt+del to log on. You'll need to keep that computer's
keyboard handy in order to log on.
Once the configuration is verified, see the instructions in INSTALL
under `Starting Automatically' for details on running synergy in
the background and on starting synergy automatically when you start
your computers.
Tips and Tricks
---------------
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.
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 <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 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 <address> listen for connections on the given address
-c, --config <pathname> read configuration from <pathname>
<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. <hostname>
defaults to the system's hostname and <port> defaults to 24800.
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>
but note that there is no default <hostname> though there is a
default <port>.
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 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 a key or mouse button is pressed.
* you cannot switch screens when the scroll lock it toggled on. use
* 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.
* 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
* Synergy's screen saver synchronization works best with xscreensaver
under X windows. Synergy works better with xscreensaver if it is
using 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. starting with 4.0
you must enable the corresponding option in your .xscreensaver file.
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.
* To work around the lack of ctrl+alt+del, you can configure Windows
2000 and XP to not require ctrl+alt+del to log on using the System
control panel. If you're the only user of an NT system you might
want to enable auto-logon. In any case, you should keep each
computer's keyboard handy, perhaps under the desk or on top of the
computer itself. If the system supports USB you should also be able
to attach/detach a keyboard as necessary.
* Synergy automatically converts newlines in clipboard text (Linux
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 hangs.
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. Send reports to:
synergy@groundhog.pair.com