NAME
synergys — synergy server
SYNOPSIS
synergys [-a address | --address address ] [-c pathname | --config
pathname ] [-d level | --debug level ] [--display display ]
[--daemon | { --no-daemon | -f } ] [-n screen-name | --name screen-
name ] [--restart | { --no-restart | -1 } ] address
synergys { -h | --help }
synergys --version
DESCRIPTION
Starts the synergys mouse/keyboard sharing server.
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.
This manual page was written for the Debian distribution because the
original program does not have a manual page. See the documentation in
/usr/share/doc/synergy/doc/index.html for most up-to-date
information.
OPTIONS
-a address --address address
listen for clients on the given address.
The argument for --address is of the form: [hostname][:port].
The hostname must be the address or hostname of an interface
on the system. The default is to listen on all interfaces.
The port overrides the default port, 24800.
-c pathname --config pathname
use the named configuration file instead.
If no configuration file pathname is provided then the first
of the following to load sets the configuration:
· ~/.synergy.conf
· /etc/synergy.conf
If no configuration file can be loaded then the configuration
uses its defaults with just the server screen.
-d level --debug level
filter out log messages with priority below level.
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, and to syslog when running as a daemon.
--display display
connect to the X server at display
--daemon run the server as a daemon.
-f --no-daemon
run the server in the foreground.
-n screen-name --name screen-name
use screen-name instead of the hostname to identify this
screen in the configuration.
This option lets the client use a name other than its
hostname for its screen.
--restart restart the server automatically if it fails.
-1 --no-restart
do not try to restart the server if it fails for some reason.
-h --help
display help and exit.
--version display version information and exit.
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. The ‘screens’ section must
appear before the ‘links’ and ‘aliases’ 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. Each screen can specify a number of
options. Options have the form ‘name = value’ and a listed one per
line after the screen name.
Example:
section: screens
moe:
larry:
halfDuplexCapsLock = true
halfDuplexNumLock = true
curly:
meta = alt
end
This declares three screens named: moe, larry, and curly. Screen
‘larry’ has half-duplex caps lock and num lock keys (see below) and
screen ‘curly’ converts the meta modifier key to the alt key.
Screen can have the following options:
· halfDuplexCapsLock = {true|false}
This computer has a caps lock key that doesn’t report a press
and a release event when the user presses it but instead
reports a press event when it’s turned on and a release event
when it’s turned off. If caps lock acts strangely on all
screens then you may need this option on the server screen.
If it acts strangely on one screen then that screen may need
the option.
· halfDuplexNumLock = {true|false}
This is identical to halfDuplexCapsLock except it applies to
the num lock key.
· xtestIsXineramaUnaware = {true|false}
This option works around a bug in the XTest extension when
used in combination with Xinerama. It affects X11 clients
only. Not all versions of the XTest extension are aware of
the Xinerama extension. As a result, they do not move the
mouse correctly when using multiple Xinerama screens. This
option is currently true by default. If you know your XTest
extension is Xinerama aware then set this option to false.
· Modifier keys:
shift = {shift|ctrl|alt|meta|super|none}
ctrl = {shift|ctrl|alt|meta|super|none}
alt = {shift|ctrl|alt|meta|super|none}
meta = {shift|ctrl|alt|meta|super|none}
super = {shift|ctrl|alt|meta|super|none}
Map a modifier key pressed on the server’s keyboard to a
different modifier on this client. This option only has an
effect on a client screen; it’s accepted and ignored on the
server screen.
You can map, say, the shift key to shift (the default), ctrl,
alt, meta, super or nothing. Normally, you wouldn’t remap
shift or ctrl. You might, however, have an X11 server with
meta bound to the Alt keys. To use this server effectively
with a windows client, which doesn’t use meta but uses alt
extensively, you’ll want the windows client to map meta to
alt (using ‘meta = alt’).
links
<args> is a list of screen names just like in the ‘screens’ section
except each screen is followed by a list of links, one per line. 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.)
options
<args> is a list of lines of the form ‘name = value’. These set the
global options.
Example:
section: options
heartbeat = 5000
switchDelay = 500
end
You can use the following options:
· heartbeat = N
The server will expect each client to send a message no less
than every N milliseconds. If no message arrives from a
client within 3N seconds the server forces that client to
disconnect.
If synergy fails to detect clients disconnecting while the
server is sleeping or vice versa, try using this option.
· switchDelay = N
Synergy won’t switch screens when the mouse reaches the edge
of a screen unless it stays on the edge for N milliseconds.
This helps prevent unintentional switching when working near
the edge of a screen.
· switchDoubleTap = N
Synergy won’t switch screens when the mouse reaches the edge
of a screen unless it’s moved away from the edge and then
back to the edge within N milliseconds. With the option you
have to quickly tap the edge twice to switch. This helps
prevent unintentional switching when working near the edge of
a screen.
· screenSaverSync = {true|false}
If set to false then synergy won’t synchronize screen savers.
Client screen savers will start according to their individual
configurations. The server screen saver won’t start if there
is input, even if that input is directed toward a client
screen.
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. ‘synergys --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:
synergys -f [--config config-pathname]
Replace config-pathname with the path to the configuration file. See
OPTIONS for the default locations of the configuration file. The ‘-f’
option causes synergys 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 ‘synergys --help’ for a list of command line options.
See ‘Starting Automatically on Unix’ below for running synergy
automatically when the X server starts.
CONFIGURE SYNERGY TO START AUTOMATICALLY
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 start the server use something like:
killall synergys
synergys [<options>] --config <config-pathname>
<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.
NETWORK SECURITY
Synergy has no built-in support for encryption or authentication. The
server accepts connections from any computer. The server and clients
send all data unencrypted which means the clipboard and mouse and
keyboard events (e.g. typed passwords) are easily examined by anyone
listening on the network. Therefore, do not run synergy on untrusted
networks except as follows.
You can use SSH (secure shell) to provide strong authentication and
encryption to synergy without modifying either SSH or synergy. On
Linux and Unix a free implementation of SSH called OpenSSH is available
at http://www.openssh.com/. On Windows you can use the Cygwin version
of OpenSSH.
ssh -f -N -L 24800:server-hostname:24800 server-hostname
where server-hostname is the name or address of the SSH and synergy
server host. 24800 is the default synergy port; replace it with
whichever port you use if you don’t use the default. Once ssh
authenticates with the server, start the synergy client as usual except
use ‘localhost’ or ‘127.0.0.1’ for the server address. Synergy will
then pass all communication through SSH which encrypts it, passes it
over the network, decrypts it, and hands it back to synergy.
Authentication is provided by SSH’s authentication.
FILES
~/.synergy.conf, /etc/synergy.conf
SEE ALSO
synergyc(1), ssh(1)
AUTHOR
This manual page was written by Daniel Lutz <danlutz@debian.org> for
the Debian system. Edited by Titus Barik <barik@ieee.org>.