source: trunk/synergy/doc/configuration.html@ 3003

Last change on this file since 3003 was 2749, checked in by bird, 19 years ago

synergy v1.3.1 sources (zip).
File size: 23.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
2<html>
3<head>
4 <meta HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
5 <meta name="keywords" content="Virtual Screen, Open Source, Software" />
6 <meta name="description" content="Mouse and Keyboard Sharing" />
7 <link rel="stylesheet" type="text/css" href="synergy.css" media="screen" />
8 <title>Synergy Configuration Guide</title>
9</head>
10<body class="main">
11<p>
12</p><h3>Synergy Configuration File Format</h3><p>
13</p><p>
14The synergy server requires configuration. It will try certain
15pathnames to load the configuration file if you don't specify a
16path using the <span class="code">--config</span> command line
17option. <span class="code">synergys --help</span> reports those
18pathnames.
19</p><p>
20The configuration file is a plain text file. Use any text editor
21to create the configuration file. The file is broken into sections
22and each section has the form:
23<span class="codeblock">
24 section: <span class="arg">name</span>
25 <span class="arg">args</span>
26 end
27</span>
28Comments are introduced by <span class="code">#</span> and continue to
29the end of the line. <span class="arg">name</span> must be one of the
30following:
31<ul class="code">
32<li>screens
33<li>aliases
34<li>links
35<li>options
36</ul>
37See below for further explanation of each section type. The
38configuration file is case-sensitive so <span class="code">Section</span>,
39<span class="code">SECTION</span>, and <span class="code">section</span>
40are all different and only the last is valid. Screen names are the
41exception; screen names are case-insensitive.
42</p><p>
43The file is parsed top to bottom and names cannot be used before
44they've been defined in the <span class="code">screens</span> or
45<span class="code">aliases</span> sections. So the
46<span class="code">links</span> and <span class="code">aliases</span>
47must appear after the <span class="code">screens</span> and links
48cannot refer to aliases unless the <span class="code">aliases</span>
49appear before the <span class="code">links</span>.
50</p><p>
51</p><h4>screens</h4><p>
52</p><p>
53<span class="arg">args</span> is a list of screen names, one name per
54line, each followed by a colon. Names are arbitrary strings but they
55must be unique. The hostname of each computer is recommended. (This
56is the computer's network name on win32 and the name reported by the
57program <span class="code">hostname</span> on Unix and OS X. Note
58that OS X may append <span class="code">.local</span> to the name you
59gave your computer; e.g. <span class="code">somehost.local</span>.)
60There must be a screen name for the server and each client. Each
61screen can specify a number of options. Options have the form
62<span class="code"><span class="arg">name</span> =
63<span class="arg">value</span></span> and are listed one per line
64after the screen name.
65</p><p>
66Example:
67<span class="codeblock">
68 section: screens
69 moe:
70 larry:
71 halfDuplexCapsLock = true
72 halfDuplexNumLock = true
73 curly:
74 meta = alt
75 end
76</span>
77This declares three screens named <span class="code">moe</span>,
78<span class="code">larry</span>, and <span class="code">curly</span>.
79Screen <span class="code">larry</span> has half-duplex Caps Lock and
80Num Lock keys (see below) and screen <span class="code">curly</span>
81converts the meta modifier key to the alt modifier key.
82</p><p>
83A screen can have the following options:
84<ul>
85<li><span class="code">halfDuplexCapsLock = {true|false}</span>
86</p><p>
87 This computer has a Caps Lock key that doesn't report a
88 press and a release event when the user presses it but
89 instead reports a press event when it's turned on and a
90 release event when it's turned off. If Caps Lock acts
91 strangely on all screens then you may need to set this
92 option to <span class="code">true</span>
93 on the server screen. If it acts strangely on one
94 screen then that screen may need the option set to
95 <span class="code">true</span>.
96</p><p>
97<li><span class="code">halfDuplexNumLock = {true|false}</span>
98</p><p>
99 This is identical to <span class="code">halfDuplexCapsLock</span>
100 except it applies to the Num Lock key.
101</p><p>
102<li><span class="code">halfDuplexScrollLock = {true|false}</span>
103</p><p>
104 This is identical to <span class="code">halfDuplexCapsLock</span>
105 except it applies to the Scroll Lock key. Note that, by default,
106 synergy uses Scroll Lock to keep the cursor on the current screen. That
107 is, when Scroll Lock is toggled on, the cursor is locked to the screen
108 that it's currently on. You can use that to prevent accidental switching.
109 You can also configure other hot keys to do that; see <a href="#lockCursor">
110 lockCursorToScreen</a>.
111</p><p>
112<li><span class="code">switchCorners = &lt;corners&gt;</span>
113</p><p>
114 See <a href="#corners">switchCorners</a> below.
115</p><p>
116<li><span class="code">switchCornerSize = N</span>
117</p><p>
118 See <a href="#cornerSize">switchCornerSize</a> below.
119</p><p>
120<li><span class="code">xtestIsXineramaUnaware = {true|false}</span>
121</p><p>
122 This option works around a bug in the XTest extension
123 when used in combination with Xinerama. It affects
124 X11 clients only. Not all versions of the XTest
125 extension are aware of the Xinerama extension. As a
126 result, they do not move the mouse correctly when
127 using multiple Xinerama screens. This option is
128 currently <span class="code">true</span> by default. If
129 you know your XTest extension is Xinerama aware then set
130 this option to <span class="code">false</span>.
131</p><p>
132<li><span class="code">shift = {shift|ctrl|alt|meta|super|none}<br>
133 ctrl = {shift|ctrl|alt|meta|super|none}<br>
134 alt = {shift|ctrl|alt|meta|super|none}<br>
135 meta = {shift|ctrl|alt|meta|super|none}<br>
136 super = {shift|ctrl|alt|meta|super|none}</span>
137</p><p>
138 Map a modifier key pressed on the server's keyboard to
139 a different modifier on this client. This option only
140 has an effect on a client screen; it's accepted and
141 ignored on the server screen.
142</p><p>
143 You can map, say, the shift key to shift (the default),
144 ctrl, alt, meta, super or nothing. Normally, you
145 wouldn't remap shift or ctrl. You might, however, have
146 an X11 server with meta bound to the Alt keys. To use
147 this server effectively with a windows client, which
148 doesn't use meta but uses alt extensively, you'll want
149 the windows client to map meta to alt (using
150 <span class="code">meta = alt</span>).
151</p><p>
152</ul>
153</p><p>
154</p><a name="aliases"></a><h4>aliases</h4><p>
155</p><p>
156 <span class="arg">args</span> is a list of screen names just like
157 in the <span class="code">screens</span> section except each screen
158 is followed by a list of aliases, one per line, <b>not</b> followed
159 by a colon. An alias is a screen name and must be unique. During
160 screen name lookup each alias is equivalent to the screen name it
161 aliases. So a client can connect using its canonical screen name
162 or any of its aliases.
163</p><p>
164 Example:
165<span class="codeblock">
166 section: aliases
167 larry:
168 larry.stooges.com
169 curly:
170 shemp
171 end
172</span>
173 Screen <span class="code">larry</span> is also known as
174 <span class="code">larry.stooges.com</span> and can connect as
175 either name. Screen <span class="code">curly</span> is also
176 known as <span class="code">shemp</span> (hey, it's just an example).
177</p><p>
178</p><h4>links</h4><p>
179</p><p>
180 <span class="arg">args</span> is a list of screen names just like
181 in the <span class="code">screens</span> section except each screen
182 is followed by a list of links, one per line. Each link has the
183 form <span class="code">{left|right|up|down}[&lt;range&gt;]</span> =
184 <span class="code">name[&lt;range&gt;]</span>. A link indicates which
185 screen is adjacent in the given direction.
186</p><p>
187 Each side of a link can specify a range which defines a portion
188 of an edge. A range on the direction is the portion of edge you can
189 leave from while a range on the screen is the portion of edge you'll
190 enter into. Ranges are optional and default to the entire edge. All
191 ranges on a particular direction of a particular screen must not
192 overlap.
193</p><p>
194 A &lt;range&gt; is written as <span class="code">(&lt;start&gt;,&lt;end&gt;)</span>.
195 Both <span class="code">start</span> and <span class="code">end</span>
196 are percentages in the range 0 to 100, inclusive. The start must be
197 less than the end. 0 is the left or top of an edge and 100 is the
198 right or bottom.
199</p><p>
200 Example:
201<span class="codeblock">
202 section: links
203 moe:
204 right = larry
205 up(50,100) = curly(0,50)
206 larry:
207 left = moe
208 up(0,50) = curly(50,100)
209 curly:
210 down(0,50) = moe
211 down(50,100) = larry(0,50)
212 end
213</span>
214 This indicates that screen <span class="code">larry</span> is to
215 the right of screen <span class="code">moe</span> (so moving the
216 cursor off the right edge of <span class="code">moe</span> would
217 make it appear at the left edge of <span class="code">larry</span>),
218 the left half of
219 <span class="code">curly</span> is above the right half of
220 <span class="code">moe</span>,
221 <span class="code">moe</span> is to the left of
222 <span class="code">larry</span> (edges are not necessarily symmetric
223 so you have to provide both directions), the right half of
224 <span class="code">curly</span> is above the left half of
225 <span class="code">larry</span>, all of <span class="code">moe</span>
226 is below the left half of <span class="code">curly</span>, and the
227 left half of <span class="code">larry</span> is below the right half of
228 <span class="code">curly</span>.
229</p><p>
230 <a name="asymmetric"></a>Note that links do not have to be
231 symmetrical; for instance, here the edge between
232 <span class="code">moe</span> and <span class="code">curly</span>
233 maps to different ranges depending on if you're going up or down.
234 In fact links don't have to be bidirectional. You can configure
235 the right of <span class="code">moe</span> to go to
236 <span class="code">larry</span> without a link from the left of
237 <span class="code">larry</span> to <span class="code">moe</span>.
238 It's possible to configure a screen with no outgoing links; the
239 cursor will get stuck on that screen unless you have a hot key
240 configured to switch off of that screen.
241</p><p>
242</p><h4>options</h4><p>
243</p><p>
244 <span class="arg">args</span> is a list of lines of the form
245 <span class="code">name = value</span>. These set the global
246 options.
247</p><p>
248 Example:
249<span class="codeblock">
250 section: options
251 heartbeat = 5000
252 switchDelay = 500
253 end
254</span>
255</p><p>
256 You can use the following options:
257<ul>
258<li><span class="code">heartbeat = N</span>
259</p><p>
260 The server will expect each client to send a message no
261 less than every <span class="code">N</span> milliseconds.
262 If no message arrives from a client within
263 <span class="code">3N</span> seconds the server forces that
264 client to disconnect.
265</p><p>
266 If synergy fails to detect clients disconnecting while
267 the server is sleeping or vice versa, try using this
268 option.
269</p><p>
270<li><span class="code"><a name="corners"></a>switchCorners = &lt;corners&gt;</span>
271</p><p>
272 Synergy won't switch screens when the mouse reaches the edge of
273 the screen if it's in a listed corner. The size of all corners
274 is given by the <span class="code">switchCornerSize</span>
275 option.
276</p><p>
277 Corners are specified by a list using the following names:
278 <ul>
279 <li><span class="code">none</span> -- no corners
280 <li><span class="code">top-left</span> -- the top left corner
281 <li><span class="code">top-right</span> -- the top right corner
282 <li><span class="code">bottom-left</span> -- the bottom left corner
283 <li><span class="code">bottom-right</span> -- the bottom right corner
284 <li><span class="code">left</span> -- top and bottom left corners
285 <li><span class="code">right</span> -- top and bottom right corners
286 <li><span class="code">top</span> -- left and right top corners
287 <li><span class="code">bottom</span> -- left and right bottom corners
288 <li><span class="code">all</span> -- all corners
289 </ul>
290</p><p>
291 The first name in the list is one of the above names and defines
292 the initial set of corners. Subsequent names are prefixed with
293 + or - to add the corner to or remove the corner from the set,
294 respectively. For example:
295</p><p>
296 <span class="code">
297 all -left +top-left
298 </span>
299</p><p>
300 starts will all corners, removes the left corners (top and bottom)
301 then adds the top-left back in, resulting in the top-left,
302 bottom-left and bottom-right corners.
303</p><p>
304<li><span class="code"><a name="cornerSize"></a>switchCornerSize = N</span>
305</p><p>
306 Sets the size of all corners in pixels. The cursor must be within
307 <span class="code">N</span> pixels of the corner to be considered
308 to be in the corner.
309</p><p>
310<li><span class="code">switchDelay = N</span>
311</p><p>
312 Synergy won't switch screens when the mouse reaches the
313 edge of a screen unless it stays on the edge for
314 <span class="code">N</span>
315 milliseconds. This helps prevent unintentional
316 switching when working near the edge of a screen.
317</p><p>
318<li><span class="code">switchDoubleTap = N</span>
319</p><p>
320 Synergy won't switch screens when the mouse reaches the
321 edge of a screen unless it's moved away from the edge
322 and then back to the edge within <span class="code">N</span>
323 milliseconds. With
324 the option you have to quickly tap the edge twice to
325 switch. This helps prevent unintentional switching
326 when working near the edge of a screen.
327</p><p>
328<li><span class="code">screenSaverSync = {true|false}</span>
329</p><p>
330 If set to <span class="code">false</span> then synergy
331 won't synchronize screen savers. Client screen savers
332 will start according to their individual configurations.
333 The server screen saver won't start if there is input,
334 even if that input is directed toward a client screen.
335</p><p>
336<li><span class="code">relativeMouseMoves = {true|false}</span>
337</p><p>
338 If set to <span class="code">true</span> then secondary
339 screens move the mouse using relative rather than absolute
340 mouse moves when and only when the cursor is locked to the
341 screen (by Scroll Lock or a <a href="#lockCursor">configured
342 hot key</a>).
343 This is intended to make synergy work better with certain
344 games. If set to <span class="code">false</span> or not
345 set then all mouse moves are absolute.
346</p><p>
347<li><span class="code">keystroke(<span class="arg">key</span>) = <span class="arg">actions</span></span>
348</p><p>
349 Binds the key combination <span class="arg">key</span> to the
350 given <span class="arg">actions</span>. <span class="arg">key</span>
351 is an optional list of modifiers (<span class="code">shift</span>,
352 <span class="code">control</span>, <span class="code">alt</span>,
353 <span class="code">meta</span> or <span class="code">super</span>)
354 optionally followed by a character or a key name, all separated by
355 <span class="code">+</span> (plus signs). You must have either
356 modifiers or a character/key name or both. See below for
357 <a href="#keynames">valid key names</a>.
358</p><p>
359 Actions are described <a href="#actions">below</a>.
360</p><p>
361 Keyboard hot keys are handled while the cursor is on the primary
362 screen and secondary screens. Separate actions can be assigned
363 to press and release.
364</p><p>
365<li><span class="code">mousebutton(<span class="arg">button</span>) = <span class="arg">actions</span></span>
366</p><p>
367 Binds the modifier and mouse button combination
368 <span class="arg">button</span> to the given
369 <span class="arg">actions</span>. <span class="arg">button</span>
370 is an optional list of modifiers (<span class="code">shift</span>,
371 <span class="code">control</span>, <span class="code">alt</span>,
372 <span class="code">meta</span> or <span class="code">super</span>)
373 followed by a button number. The primary button (the
374 left button for right handed users) is button 1, the middle button
375 is 2, etc.
376</p><p>
377 Actions are described <a href="#actions">below</a>.
378</p><p>
379 Mouse button actions are not handled while the cursor is on the
380 primary screen. You cannot use these to perform an action while
381 on the primary screen. Separate actions can be assigned to press
382 and release.
383</p><p>
384</ul>
385 You can use both the <span class="code">switchDelay</span> and
386 <span class="code">switchDoubleTap</span> options at the same
387 time. Synergy will switch when either requirement is satisfied.
388</p><p>
389<a name="actions">Actions</a> are two lists of individual actions separated
390by commas. The two lists are separated by a semicolon. Either list can be
391empty and if the second list is empty then the semicolon is optional. The
392first list lists actions to take when the condition becomes true (e.g. the
393hot key or mouse button is pressed) and the second lists actions to take
394when the condition becomes false (e.g. the hot key or button is released).
395The condition becoming true is called activation and becoming false is
396called deactivation.
397Allowed individual actions are:
398<ul>
399<li><span class="code">keystroke(<span class="arg">key</span>[,<span class="arg">screens</span>])</span>
400<li><span class="code">keyDown(<span class="arg">key</span>[,<span class="arg">screens</span>])</span>
401<li><span class="code">keyUp(<span class="arg">key</span>[,<span class="arg">screens</span>])</span>
402</p><p>
403 Synthesizes the modifiers and key given in <span class="arg">key</span>
404 which has the same form as described in the
405 <span class="code">keystroke</span> option. If given,
406 <span class="arg">screens</span> lists the screen or screens to
407 direct the event to, regardless of the active screen. If not
408 given then the event is directed to the active screen only.
409</p><p>
410 <span class="code">keyDown</span> synthesizes a key press and
411 <span class="code">keyUp</span> synthesizes a key release.
412 <span class="code">keystroke</span> synthesizes a key press on
413 activation and a release on deactivation and is equivalent to
414 a <span class="code">keyDown</span> on activation and
415 <span class="code">keyUp</span> on deactivation.
416</p><p>
417 <span class="arg">screens</span> is either <span class="code">*</span>
418 to indicate all screens or a colon (:) separated list of screen
419 names. (Note that the screen name must have already been encountered
420 in the configuration file so you'll probably want to put actions at
421 the bottom of the file.)
422</p><p>
423<li><span class="code">mousebutton(<span class="arg">button</span>)</span>
424<li><span class="code">mouseDown(<span class="arg">button</span>)</span>
425<li><span class="code">mouseUp(<span class="arg">button</span>)</span>
426</p><p>
427 Synthesizes the modifiers and mouse button given in
428 <span class="arg">button</span>
429 which has the same form as described in the
430 <span class="code">mousebutton</span> option.
431</p><p>
432 <span class="code">mouseDown</span> synthesizes a mouse press and
433 <span class="code">mouseUp</span> synthesizes a mouse release.
434 <span class="code">mousebutton</span> synthesizes a mouse press on
435 activation and a release on deactivation and is equivalent to
436 a <span class="code">mouseDown</span> on activation and
437 <span class="code">mouseUp</span> on deactivation.
438</p><p>
439<li><a name="lockCursor"></a><span class="code">lockCursorToScreen(<span class="arg">mode</span>)</span>
440</p><p>
441 Locks the cursor to or unlocks the cursor from the active screen.
442 <span class="arg">mode</span> can be <span class="code">off</span>
443 to unlock the cursor, <span class="code">on</span> to lock the
444 cursor, or <span class="code">toggle</span> to toggle the current
445 state. The default is <span class="code">toggle</span>. If the
446 configuration has no <span class="code">lockCursorToScreen</span>
447 action and Scroll Lock is not used as a hot key then Scroll Lock
448 toggles cursor locking.
449</p><p>
450<li><span class="code">switchToScreen(<span class="arg">screen</span>)</span>
451</p><p>
452 Jump to screen with name or alias <span class="arg">screen</span>.
453</p><p>
454<li><span class="code">switchInDirection(<span class="arg">dir</span>)</span>
455</p><p>
456 Switch to the screen in the direction <span class="arg">dir</span>,
457 which may be one of <span class="code">left</span>,
458 <span class="code">right</span>, <span class="code">up</span> or
459 <span class="code">down</span>.
460</p><p>
461</ul>
462</p><p>
463Examples:
464<ul>
465<li><span class="code">keystroke(alt+left) = switchInDirection(left)</span>
466</p><p>
467 Switches to the screen to left when the left arrow key is pressed
468 in combination with the Alt key.
469</p><p>
470<li><span class="code">keystroke(shift+control+alt+super) = switchToScreen(moe)</span>
471</p><p>
472 Switches to screen <span class="code">moe</span> when all of the
473 Shift, Control, Alt, and Super modifier keys are pressed together.
474</p><p>
475<li><span class="code">keystroke(alt+f1) = ; lockCursorToScreen(toggle)</span>
476</p><p>
477 Toggles locking the cursor to the screen when Alt+F1 is released.
478</p><p>
479<li><span class="code">mousebutton(2) = mouseDown(control+1) ; mouseUp(control+1)</span>
480</p><p>
481 While on a secondary screen clicking the middle mouse button will
482 become a Control click of the primary button.
483</p><p>
484<li><span class="code">keystroke(super+f1) = keystroke(super+L,larry), keystroke(control+alt+delete,curly)</span>
485</p><p>
486 Pressing Super+F1 (on any screen) will synthesize Super+L on screen
487 <span class="code">larry</span> and Control+Alt+Delete on screen
488 <span class="code">curly</span>.
489</p><p>
490</ul></span>
491</p><p>
492<a name="keynames">Valid key names</a> are:
493<span class="code"><ul>
494<li>AppMail
495<li>AppMedia
496<li>AppUser1
497<li>AppUser2
498<li>AudioDown
499<li>AudioMute
500<li>AudioNext
501<li>AudioPlay
502<li>AudioPrev
503<li>AudioStop
504<li>AudioUp
505<li>BackSpace
506<li>Begin
507<li>Break
508<li>Cancel
509<li>CapsLock
510<li>Clear
511<li>Delete
512<li>Down
513<li>Eject
514<li>End
515<li>Escape
516<li>Execute
517<li>F1
518<li>F2
519<li>F3
520<li>F4
521<li>F5
522<li>F6
523<li>F7
524<li>F8
525<li>F9
526<li>F10
527<li>F11
528<li>F12
529<li>F13
530<li>F14
531<li>F15
532<li>F16
533<li>F17
534<li>F18
535<li>F19
536<li>F20
537<li>F21
538<li>F22
539<li>F23
540<li>F24
541<li>F25
542<li>F26
543<li>F27
544<li>F28
545<li>F29
546<li>F30
547<li>F31
548<li>F32
549<li>F33
550<li>F34
551<li>F35
552<li>Find
553<li>Help
554<li>Home
555<li>Insert
556<li>KP_0
557<li>KP_1
558<li>KP_2
559<li>KP_3
560<li>KP_4
561<li>KP_5
562<li>KP_6
563<li>KP_7
564<li>KP_8
565<li>KP_9
566<li>KP_Add
567<li>KP_Begin
568<li>KP_Decimal
569<li>KP_Delete
570<li>KP_Divide
571<li>KP_Down
572<li>KP_End
573<li>KP_Enter
574<li>KP_Equal
575<li>KP_F1
576<li>KP_F2
577<li>KP_F3
578<li>KP_F4
579<li>KP_Home
580<li>KP_Insert
581<li>KP_Left
582<li>KP_Multiply
583<li>KP_PageDown
584<li>KP_PageUp
585<li>KP_Right
586<li>KP_Separator
587<li>KP_Space
588<li>KP_Subtract
589<li>KP_Tab
590<li>KP_Up
591<li>Left
592<li>LeftTab
593<li>Linefeed
594<li>Menu
595<li>NumLock
596<li>PageDown
597<li>PageUp
598<li>Pause
599<li>Print
600<li>Redo
601<li>Return
602<li>Right
603<li>ScrollLock
604<li>Select
605<li>Sleep
606<li>Space
607<li>SysReq
608<li>Tab
609<li>Undo
610<li>Up
611<li>WWWBack
612<li>WWWFavorites
613<li>WWWForward
614<li>WWWHome
615<li>WWWRefresh
616<li>WWWSearch
617<li>WWWStop
618<li>Space
619<li>Exclaim
620<li>DoubleQuote
621<li>Number
622<li>Dollar
623<li>Percent
624<li>Ampersand
625<li>Apostrophe
626<li>ParenthesisL
627<li>ParenthesisR
628<li>Asterisk
629<li>Plus
630<li>Comma
631<li>Minus
632<li>Period
633<li>Slash
634<li>Colon
635<li>Semicolon
636<li>Less
637<li>Equal
638<li>Greater
639<li>Question
640<li>At
641<li>BracketL
642<li>Backslash
643<li>BracketR
644<li>Circumflex
645<li>Underscore
646<li>Grave
647<li>BraceL
648<li>Bar
649<li>BraceR
650<li>Tilde
651</ul></span>
652Additionally, a name of the form <span class="code">\uXXXX</span> where
653<span class="code">XXXX</span> is a hexadecimal number is interpreted as
654a unicode character code.
655Key and modifier names are case-insensitive. Keys that don't exist on
656the keyboard or in the default keyboard layout will not work.
657</p>
658</body>
659
660</html>
Note: See TracBrowser for help on using the repository browser.