source: trunk/synergy/doc/running.html@ 3232

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

synergy v1.3.1 sources (zip).
File size: 16.8 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 User Guide</title>
9</head>
10<body class="main">
11<p>
12</p><h3>Running Synergy</h3><p>
13</p><p>
14Synergy lets you use one keyboard and mouse across multiple computers.
15To do so it requires that all the computers are connected to each other
16via TCP/IP networking. Most systems come with this installed.
17</p><p>
18</p><h4>Step 1 - Choose a server</h4><p>
19</p><p>
20The first step is to pick which keyboard and mouse you want to share.
21The computer with that keyboard and mouse is called the "primary
22screen" and it runs the synergy server. All of the other computers
23are "secondary screens" and run the synergy client.
24</p><p>
25</p><h4>Step 2 - Install the software</h4><p>
26</p><p>
27Second, you install the software. Choose the appropriate package
28and install it. For example, on Windows you would run
29<span class="code">SynergyInstaller</span>. You must install the
30software on all the computers that will share the mouse and keyboard
31(clients and server). On OS X you'll just have a folder with some
32documentation and two programs. You can put this folder anywhere.
33</p><p>
34</p><h4>Step 3 - Configure and start the server</h4><p>
35</p><p>
36Next you configure the server. You'll tell synergy the name of
37the primary and secondary screens, which screens are next to which,
38and choose desired options. On Windows there's a dialog box for
39setting the configuration. On other systems you'll create a simple
40text file.
41</p><p>
42<a name="asymmetric"></a>
43Note that when you tell synergy that screen <span class="code">A</span>
44is to the left of screen <span class="code">B</span> this does <b>not</b>
45imply that <span class="code">B</span> is to the right of
46<span class="code">A</span>. You must explicitly indicate both
47relations. If you don't do both then when you're running synergy you'll
48find you're unable to leave one of the screens.
49</p><p>
50<b>Windows</b><br>
51On Windows run synergy by double clicking on the
52<span class="code">synergy</span> file. This brings up a dialog.
53Configure the server:
54<ul>
55<li>Click the <span class="code">Share this computer's keyboard and mouse (server)</span> radio button
56<li>Click the <span class="code">Screens &amp; Links Configure...</span> button
57<li>Click the <span class="code">+</span> button to add the server to the
58 <span class="code">Screens</span> list
59 <ul>
60 <li>Enter the name of server (the computer's name is the recommended name)
61 <li>Optionally enter other names the server is known by
62 <li>Click <span class="code">OK</span>
63 </ul>
64<li>Use the <span class="code">+</span> button to add your other computers
65 <ul>
66 <li>Using a computer's name as its screen name is recommended
67 <li>Choose desired screen options on the <span class="code">Add Screen</span> dialog
68 </ul>
69<li>Use the controls under <span class="code">Links</span> to link screens together
70 <ul>
71 <li>Click (once) on the server's name in the <span class="code">Screens</span> list
72 <li>Choose the screen to the left of the server; use <span class="code">---</span>
73 if there is no screen to the left of the server
74 <li>Choose the screens to the right, above and below the server
75 <li>Repeat the above steps for all the other screens
76 </ul>
77<li>Click <span class="code">OK</span> to close the <span class="code">Screens &amp; Links</span> dialog
78<li>Use <span class="code">Options...</span> to set desired options
79<li>If the server's screen name is not the server's computer name:
80 <ul>
81 <li>Click <span class="code">Advanced...</span>
82 <li>Enter the server's screen name next to
83 <span class="code">Screen Name</span>
84 <li>Click <span class="code">OK</span>
85 </ul>
86</ul>
87</p><p>
88Now click <span class="code">Test</span>. The server will start and
89you'll see a console window with log messages telling you about synergy's
90progress. If an error occurs you'll get one or more dialog boxes telling
91you what the errors are; read the errors to determine the problem then
92correct them and try <span class="code">Test</span> again. See Step 5
93for typical errors.
94</p><p>
95<b>Unix or Mac OS X</b><br>
96Create a text file named <span class="code">synergy.conf</span> with the
97following:
98<pre>
99 section: screens
100 <span class="arg">screen1</span>:
101 <span class="arg">screen2</span>:
102 end
103 section: links
104 <span class="arg">screen1</span>:
105 right = <span class="arg">screen2</span>
106 <span class="arg">screen2</span>:
107 left = <span class="arg">screen1</span>
108 end
109</pre>
110Replace each occurrence of <span class="arg">screen1</span> with the host name
111of the primary screen computer (as reported by the
112<span class="code">hostname</span> program) and <span class="arg">screen2</span>
113with the host name of a secondary screen computer. In the above example,
114<span class="arg">screen2</span> is to the right of
115<span class="arg">screen1</span> and <span class="arg">screen1</span> is to the
116left of <span class="arg">screen2</span>. If necessary you should replace
117<span class="code">right</span> and <span class="code">left</span> with
118<span class="code">left</span>, <span class="code">right</span>,
119<span class="code">up</span>, or <span class="code">down</span>. If you
120have more than two computers you can add those too: add each computer's host
121name in the <span class="code">screens</span> section and add the
122appropriate links. See the <a href="configuration.html">configuration
123guide</a> for more configuration possibilities.
124</p><p>
125Now start the server. Normally synergy wants to run "in the background."
126It detaches from the terminal and doesn't have a visible window, effectively
127disappearing from view. Until you're sure your configuration works, you
128should start synergy "in the foreground" using the <span class="code">-f</span>
129command line option.
130</p><p>
131On unix type the command below in a shell. If synergys is not in your
132PATH then use the full pathname.
133<pre>
134 synergys -f --config synergy.conf
135</pre>
136On OS X open Terminal in the Utilities folder in the Applications folder.
137Drag the synergys program from the synergy folder onto the Terminal window.
138The path to the synergys program will appear. Add the following to the
139same line, type a space at the end of the line but don't press enter:
140<pre>
141 -f --config
142</pre>
143Now drag the synergy.conf file onto the Terminal window and press enter.
144Check the reported messages for errors. Use ctrl+c to stop synergy if
145it didn't stop automatically, correct any problems, and start it again.
146</p><p>
147</p><h4>Step 4 - Start the clients</h4><p>
148</p><p>
149Next you start the client on each computer that will share the server's
150keyboard and mouse.
151</p><p>
152<b>Windows</b><br>
153On Windows run synergy by double clicking on the
154<span class="code">synergy</span> file. This brings up a dialog.
155Configure the client:
156<ul>
157<li>Click the <span class="code">Use another computer's shared keyboard and mouse (client)</span> radio button
158<li>Enter the server's computer name next to <span class="code">Other Computer's Host Name</span>
159 <ul>
160 <li>This is not the server's screen name, unless you made that the
161 server's host name as recommended
162 </ul>
163<li>If the client's screen name is not the client's computer name:
164 <ul>
165 <li>Click <span class="code">Advanced...</span>
166 <li>Enter the client's screen name next to <span class="code">Screen Name</span>
167 <li>Click <span class="code">OK</span>
168 </ul>
169</ul>
170</p><p>
171Now click <span class="code">Test</span>.
172</p><p>
173<b>Unix or Mac OS X</b><br>
174To start a client on unix, enter the following:
175<pre>
176 synergyc -f <span class="arg">server-host-name</span>
177</pre>
178where <span class="arg">server-host-name</span> is replaced by the host
179name of the computer running the synergy server. If synergyc is not in
180your PATH then use the full pathname.
181</p><p>
182On OS X open Terminal in the Utilities folder in the Applications folder.
183Drag the synergyc program from the synergy folder onto the Terminal window.
184The path to the synergys program will appear. Add the following to the
185same line and press enter:
186<pre>
187 -f <span class="arg">server-host-name</span>
188</pre>
189</p><p>
190When you added the client to the server's configuration you chose a
191name for the client. If that name was not client's host name then
192you must tell the client the name you used. Instead of the above
193command use this instead:
194<pre>
195 synergyc -f --name <span class="arg">name</span> <span class="arg">server-host-name</span>
196</pre>
197where <span class="arg">name</span> is the name for the client in
198the server's configuration. (On OS X drag the synergyc program to the
199Terminal window rather than typing synergyc.)
200</p><p>
201</p><h4>Step 5 - Test</h4><p>
202</p><p>
203Clients should immediately report a successful connection or one or
204more error messages. Some typical problems and possible solutions are
205below. See the <a href="trouble.html">troubleshooting</a> and the
206<a href="faq.html">FAQ</a> pages for more help.
207<ul>
208<li>failed to open screen (X11 only)
209</p><p>
210 Check permission to open the X display;<br>
211 check that the DISPLAY environment variable is set<br>
212 use the <span class="code">--display</span> command line option.
213</p><p>
214<li>address already in use
215</p><p>
216 Another program (maybe another copy of synergy) is using the synergy port;
217 stop the other program or choose a different port in the
218 <span class="code">Advanced...</span> dialog. If you change the port
219 you must make the same change on all of the clients, too.
220</p><p>
221<li>connection forcefully rejected
222</p><p>
223 The synergy client successfully contacted the server but synergy wasn't
224 running or it's running on a different port. You may also see this if
225 there's a firewall blocking the host or port. Make sure synergy is
226 running on the server and check for a firewall.
227</p><p>
228<li>already connected
229</p><p>
230 Check that the synergy client isn't already running.
231</p><p>
232<li>refused client
233</p><p>
234 Add the client to the server's configuration file.
235</p><p>
236<li>connection timed out
237</p><p>
238 Check that <span class="arg">server-host-name</span> is correct.<br>
239 Check that you don't have a firewall blocking the server or synergy port.
240</p><p>
241<li>connection failed
242</p><p>
243 Check that <span class="arg">server-host-name</span> is correct.
244</p><p>
245</ul>
246If you get the error "<span class="code">Xlib: No protocol specified</span>"
247you're probably running synergy as root while logged in as another user.
248X11 may prevent this for security reasons. Either run synergy as the same
249user that's logged in or (not recommended) use
250<nobr>"<span class="code">xhost +</span>"</nobr> to allow anyone to connect
251to the display.
252</p><p>
253When successful you should be able to move the mouse off the appropriate
254edges of your server's screen and have it appear on a client screen.
255Try to move the mouse to each screen and check all the configured links.
256Check the mouse buttons and wheel and try the keyboard on each client.
257You can also cut-and-paste text, HTML, and images across computers (HTML
258and images are not supported on OS X yet).
259</p><p>
260</p><h4>Step 6 - Run</h4><p>
261</p><p>
262Once everything works correctly, stop all the clients then the server.
263Then start the server with the <span class="code">Start</span> button
264on Windows and without the <span class="code">-f</span> option on Unix
265and Mac OS X. Finally start the clients similarly. On Windows before
266clicking <span class="code">Start</span> you may want to set the
267<span class="code">Logging Level</span> to
268<span class="code">Warning</span> so the logging window doesn't pop
269up (because you currently can't close it, just minimize it).
270</p><p>
271You can also configure synergy to start automatically when your computer
272starts or when you log in. See the <a href="autostart.html">autostart
273guide</a> for more information.
274</p><p>
275</p><h4><a name="options"></a>Command Line Options Guide</h4><p>
276</p><p>
277<b><a name="commonOptions"></a>Common Command Line Options</b><br>
278The following options are supported by <span class="code">synergys</span>
279and <span class="code">synergyc</span>.
280<table>
281 <tr>
282 <td>&nbsp;</td><td><span class="code">-d,</span></td>
283 <td><span class="code">--debug <span class="arg">level</span></span></td>
284 <td>&nbsp;&nbsp;</td><td>use debugging level <span class="arg">level</span></td>
285 </tr>
286 <tr>
287 <td>&nbsp;</td><td><span class="code"></span></td>
288 <td><span class="code">--daemon</span></td>
289 <td></td><td>run as a daemon (Unix) or background (Windows)</td>
290 </tr>
291 <tr>
292 <td>&nbsp;</td><td><span class="code">-f,</span></td>
293 <td><span class="code">--no-daemon</span></td>
294 <td></td><td>run in the foreground</td>
295 </tr>
296 <tr>
297 <td>&nbsp;</td><td><span class="code">&nbsp;</span></td>
298 <td><span class="code">--display <span class="arg">display</span></span></td>
299 <td>&nbsp;&nbsp;</td><td>connect to X server at <span class="arg">display</span> (X11 only)</td>
300 </tr>
301 <tr>
302 <td>&nbsp;</td><td><span class="code">-n,</span></td>
303 <td><span class="code">--name <span class="arg">name</span></span></td>
304 <td></td><td>use <span class="arg">name</span> instead of the hostname</td>
305 </tr>
306 <tr>
307 <td>&nbsp;</td><td><span class="code"></span></td>
308 <td><span class="code">--restart</span></td>
309 <td></td><td>automatically restart on failures</td>
310 </tr>
311 <tr>
312 <td>&nbsp;</td><td><span class="code">-1,</span></td>
313 <td><span class="code">--no-restart</span></td>
314 <td></td><td>do not restart on failure</td>
315 </tr>
316 <tr>
317 <td>&nbsp;</td><td><span class="code">-h,</span></td>
318 <td><span class="code">--help</span></td>
319 <td></td><td>print help and exit</td>
320 </tr>
321 <tr>
322 <td>&nbsp;</td><td><span class="code"></span></td>
323 <td><span class="code">--version</span></td>
324 <td></td><td>print version information and exit</td>
325 </tr>
326</table>
327</p><p>
328Debug levels are from highest to lowest: <span class="code">FATAL</span>,
329<span class="code">ERROR</span>, <span class="code">WARNING</span>,
330<span class="code">NOTE</span>, <span class="code">INFO</span>,
331<span class="code">DEBUG</span>, <span class="code">DEBUG1</span>, and
332<span class="code">DEBUG2</span>. Only messages at or above the given
333level are logged. Messages are logged to a terminal window when
334running in the foreground. Unix logs messages to syslog when running
335as a daemon. The Windows NT family logs messages to the event log
336when running as a service. The Windows 95 family shows FATAL log
337messages in a message box and others in a terminal window when running
338as a service.
339</p><p>
340The <span class="code">--name</span> option lets the client or server
341use a name other than its hostname for its screen. This name is used
342when checking the configuration.
343</p><p>
344Neither the client nor server will automatically restart if an error
345occurs that is sure to happen every time. For example, the server
346will exit immediately if it can't find itself in the configuration.
347On X11 both the client and server will also terminate if the
348connection to the X server is lost (usually because it died).
349</p><p>
350<b>Server Command Line Options</b><br>
351</p><p>
352<pre>
353 synergys [options]
354</pre>
355The server accepts the <a href="#commonOptions">common options</a> and:
356</p><p>
357<table>
358 <tr>
359 <td>&nbsp;</td><td><span class="code">-a,</span></td>
360 <td><span class="code">--address <span class="arg">address</span></span></td>
361 <td>&nbsp;&nbsp;</td><td>listen for connections on address <span class="arg">address</span></td>
362 </tr>
363 <tr>
364 <td>&nbsp;</td><td><span class="code">-c,</span></td>
365 <td><span class="code">--config <span class="arg">pathname</span></span></td>
366 <td>&nbsp;&nbsp;</td><td>read configuration from <span class="arg">pathname</span></td>
367 </tr>
368</table>
369</p><p>
370<span class="arg">address</span> has one of the following forms:
371<pre>
372 <span class="arg">hostname</span>
373 :<span class="arg">port</span>
374 <span class="arg">hostname</span>:<span class="arg">port</span>
375</pre>
376<span class="arg">hostname</span> is a hostname or IP address of a network
377interface on the server system (e.g. <span class="code">somehost</span>
378or <span class="code">192.168.1.100</span>). <span class="arg">port</span>
379is a port number from 1 to 65535. <span class="arg">hostname</span> defaults to
380the system's hostname and <span class="arg">port</span> defaults to 24800.
381</p><p>
382<b>Client Command Line Options</b><br>
383</p><p>
384<pre>
385 synergyc [options] <span class="arg">address</span>[:<span class="arg">port</span>]
386</pre>
387<span class="arg">address</span> is the hostname or IP address of
388the server and <span class="arg">port</span> is the optional network
389port on the server to connect to. The client accepts the
390<a href="#commonOptions">common options</a>.
391</p>
392</body>
393
394</html>
Note: See TracBrowser for help on using the repository browser.