NAME¶
synergys - synergy server
SYNOPSIS¶
synergys [
-a address |
--address
address ] [
-c pathname |
--config
pathname ] [
--crypto-pass password ]
[
-d level |
--debug level ] [
--display display ] [
--daemon |
{ --no-daemon
| -f } ] [
-l log-file |
--log
log-file ] [
-n screen-name |
--name
screen-name ] [
--no-tray ] [
--no-xinitthreads ] [
--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.
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.
- --crypto-pass password
- use password as the password for authenticating to the synergy
server.
- -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.
- -l log-file --log log-file
- write log messages to log-file
- -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.
- --no-tray
- disable the system tray icon.
- --no-xinitthreads
- disable Xlib threading support.
This option may fix some crashing issues with Synergy.
- --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.
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¶
By default, Synergy does not secure its communications in any way. This is
dangerous, as all clipboard and mouse and keyboard events (e.g. typed
passwords) are easily examined by anyone listening on the network.
To turn on encryption and authentication support, use the
--crypto-pass
option on both client and server. In this mode, the connection will be
encrypted, and the server will check the client's password against the one it
was started with.
If this level of security is not sufficient for some reason (see the BUGS
section below for a possible reason), you can use SSH (secure shell) to
provide strong authentication and encryption to synergy. SSH is available on
Debian systems in the "openssh-server" and
"openssh-client" packages, or from
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.
BUGS¶
The cryptography support is fairly new, and to the extent it has been tested, it
has not done well. Users are advised to further secure their synergy sessions
using methods such as the SSH method described in the NETWORK SECURITY section
above until its security has been verified independently.
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> and Jeff Licquia
<licquia@debian.org>.