source: trunk/synergy/doc/autostart.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: 14.4 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 Autostart Guide</title>
9</head>
10<body class="main">
11<p>
12</p><h3>Starting synergy automatically</h3><p>
13</p><p>
14You can configure synergy to start automatically when the computer
15starts or when you log in. The steps to do that are different on
16each platform. Note that changing these configurations doesn't
17actually start or stop synergy. The changes take effect the next
18time you start your computer or log in.
19</p><p>
20</p><h4>Windows</h4><p>
21</p><p>
22Start synergy and click the <span class="code">Configure...</span> button
23by the text <span class="code">Automatic Startup</span>. The
24<span class="code">Auto Start</span> dialog will pop up.
25If an error occurs then correct the problem and click
26<span class="code">Configure</span> again.
27</p><p>
28On the <span class="code">Auto Start</span> dialog you'll configure
29synergy to start or not start automatically when the computer starts
30or when you log in. You need Administrator access rights to start
31synergy automatically when the computer starts. The dialog will let
32you know if you have sufficient permission.
33</p><p>
34If synergy is already configured to automatically start then there
35will be two <span class="code">Uninstall</span> buttons, at most one
36of which is enabled. Click the enabled button, if any, to tell
37synergy to not start automatically.
38</p><p>
39If synergy is not configured to start automatically then there will
40be two <span class="code">Install</span> buttons. If you have
41sufficient permission to have synergy start automatically when the
42computer does then the <span class="code">Install</span> button in the
43<span class="code">When Computer Starts</span> box will be enabled.
44Click it to have synergy start for all users when the computer starts.
45In this case, synergy will be available during the login screen.
46Otherwise, click the <span class="code">Install</span> button in the
47<span class="code">When You Log In</span> box to have synergy
48automatically start when you log in.
49</p><p>
50</p><h4>Unix</h4><p>
51</p><p>
52Synergy requires an X server. That means a server must be
53running and synergy must be authorized to connect to that server.
54It's best to have the display manager start synergy. You'll need
55the necessary (probably root) permission to modify the display
56manager configuration files. If you don't have that permission
57you can start synergy after logging in via the
58<span class="code">.xsession</span> file.
59</p><p>
60Typically, you need to edit three script files. The first file
61will start synergy before a user logs in, the second will kill
62that copy of synergy, and the third will start it again after
63the user logs in.
64</p><p>
65The contents of the scripts varies greatly between systems so
66there's no one definite place where you should insert your edits.
67However, these scripts often exit before reaching the bottom so
68put the edits near the top of the script.
69</p><p>
70The location and names of these files depend on the operating
71system and display manager you're using. A good guess for the
72location is <span class="code">/etc/X11</span>. If you use kdm
73then try looking in <span class="code">/etc/kde3</span> or
74<span class="code">/usr/kde/<span class="arg">version</span>/share/config</span>.
75Typical file names are:
76</p><p>
77<span class="code">
78<table>
79<tr><td>&nbsp;&nbsp;</td> <td>&nbsp;&nbsp;</td> <td>xdm</td> <td>&nbsp;&nbsp;</td> <td>kdm</td> <td>&nbsp;&nbsp;</td> <td>gdm</td></tr>
80<tr><td>1</td> <td></td> <td>xdm/Xsetup</td> <td></td> <td>kdm/Xsetup</td> <td></td> <td>gdm/Init/Default (*)</td></tr>
81<tr><td>2</td> <td></td> <td>xdm/Xstartup</td> <td></td> <td>kdm/Xstartup</td> <td></td> <td>gdm/PostLogin/Default (*)</td></tr>
82<tr><td>3</td> <td></td> <td>xdm/Xsession</td> <td></td> <td>kdm/Xsession</td> <td></td> <td>gdm/Sessions/Default (*, **)</td></tr>
83</table>
84</span>
85</p><p>
86*) The <span class="code">Default</span> file is used if no other
87suitable file is found. <span class="code">gdm</span> will try
88<span class="arg">displayname</span> (e.g. <span class="code">:0</span>)
89and <span class="arg">hostname</span> (e.g. <span class="code">somehost</span>),
90in that order, before and instead of <span class="code">Default</span>.
91<br>
92**) gdm may use <span class="code">gdm/Xsession</span>,
93<span class="code">xdm/Xsession</span> or
94<span class="code">dm/Xsession</span> if
95<span class="code">gdm/Sessions/Default</span> doesn't exist.
96</p><p>
97For a synergy client, add the following to the first file:
98<span class="codeblock">
99 /usr/bin/killall synergyc
100 sleep 1
101 /usr/bin/synergyc [&lt;options&gt;] <span class="arg">synergy-server-hostname</span>
102</span>
103Of course, the path to synergyc depends on where you installed it
104so adjust as necessary.
105</p><p>
106Add to the second file:
107<span class="codeblock">
108 /usr/bin/killall synergyc
109 sleep 1
110</span>
111</p><p>
112And to the third file:
113<span class="codeblock">
114 /usr/bin/killall synergyc
115 sleep 1
116 /usr/bin/synergyc <span class="arg">[&lt;options&gt;]</span> <span class="arg">synergy-server-hostname</span>
117</span>
118Note that <a href="running.html#options"><span class="arg">&lt;options&gt;</span></a>
119must not include
120<span class="code">-f</span> or <span class="code">--no-daemon</span> or
121the script will never exit and you won't be able to log in.
122</p><p>
123The changes are the same for the synergy server except replace
124<span class="code">synergyc</span> with <span class="code">synergys</span>
125and use the appropriate synergys <a href="running.html#options">command
126line options</a>. Note that the
127first script is run as root so synergys will look for the configuration
128file in root's home directory then in <span class="code">/etc</span>.
129Make sure it exists in one of those places or use the
130<span class="code">--config <span class="arg">config-pathname</span></span>
131option to specify its location.
132</p><p>
133Note that some display managers (xdm and kdm, but not gdm) grab
134the keyboard and do not release it until the user logs in for
135security reasons. This prevents a synergy server from sharing
136the mouse and keyboard until the user logs in. It doesn't
137prevent a synergy client from synthesizing mouse and keyboard
138input, though.
139</p><p>
140If you're configuring synergy to start only after you log in then edit
141your <span class="code">.xsession</span> file. Add just what you
142would add to the third file above.
143</p><p>
144</p><h4>Mac OS X</h4><p>
145</p><p>
146[By Tor Slettnes]
147</p><p>
148There are three different ways to automatically start Synergy
149(client or server) on Mac OS X:
150</p><p>
151<ol>
152<li>
153 The first method involves creating a <span class="code">StartupItem</span>
154 at the system level, which is executed when the machine starts up
155 or shuts down. This script will run in the background, and
156 relaunch synergy as needed.
157</p><p>
158 <dl>
159 <dt><b>Pros:</b></dt>
160 <dd>
161 Synergy is persistent, so this allows for a multi-user
162 setup and interactive logins.
163 </dd>
164 <dt><b>Cons:</b></dt>
165 <dd>
166 The synergy process does not have access to the clipboard
167 of the logged-in user.
168 </dd>
169 </dl>
170</li>
171</p><p>
172<li>
173 The second method will launch Synergy from the
174 <span class="code">LoginWindow</span> application, once a particular
175 user has logged in.
176</p><p>
177 <dl>
178 <dt><b>Pros:</b></dt>
179 <dd>
180 The synergy process inherits the
181 <span class="code">$SECURITYSESSIONID</span> environment variable,
182 and therefore copy/paste works.
183 </dd>
184 <dt><b>Cons:</b></dt>
185 <dd>
186 Once the user logs out, synergy dies, and no remote
187 control is possible.
188 </dd>
189 </dl>
190</li>
191</p><p>
192<li>
193 The third method is to launch a startup script from the
194 "Startup Items" tab under System Preferences -> Accounts.
195</p><p>
196 <dl>
197 <dt><b>Pros:</b></dt>
198 <dd>
199 Does not require root (Administrator) access
200 </dd>
201 <dt><b>Cons:</b></dt>
202 <dd>
203 Once the user logs out, synergy dies, and no remote
204 control is possible.
205 </dd>
206 </dl>
207</li>
208</ol>
209</p><p>
210The text below describes how to implement a Synergy client using
211the first two methods simultaneously. This way, Synergy is
212always running, and the clipboard is available when someone is
213logged in. A Mac OS X Synergy server setup will be quite similar.
214</p><p>
215<b>1. Create a System Level Startup Item</b>
216</p><p>
217<ul>
218<li>
219 Open a <span class="code">Terminal</span> window, and become root:
220 <span class="userinput">
221 $ sudo su -
222 </span>
223</li>
224<li>
225 Create a folder for this item:
226 <span class="userinput">
227 # mkdir -p /Library/StartupItems/Synergy
228 </span>
229</li>
230<li>
231 In this folder, create a new script file by the same name as
232 the directory itself, <span class="code">Synergy</span>. This script
233 should contain the following text:
234</p><p>
235<span class="codeblock">
236#!/bin/sh
237. /etc/rc.common
238&nbsp;
239run=(/usr/local/bin/synergyc -n $(hostname -s) -1 -f <span class="arg">synergy-server</span>)
240&nbsp;
241KeepAlive ()
242{
243 proc=${1##*/}
244&nbsp;
245 while [ -x "$1" ]
246 do
247 if ! ps axco command | grep -q "^${proc}\$"
248 then
249 "$@"
250 fi
251&nbsp;
252 sleep 3
253 done
254}
255&nbsp;
256StartService ()
257{
258 ConsoleMessage "Starting Synergy"
259 KeepAlive "${run[@]}" &
260}
261&nbsp;
262StopService ()
263{
264 return 0
265}
266&nbsp;
267RestartService ()
268{
269 return 0
270}
271&nbsp;
272RunService "$1"
273</span>
274</p><p>
275 However, replace <span class="arg">synergy-server</span> with the actual
276 name or IP address of your Synergy server.
277</p><p>
278 Note that this scripts takes care <em>not</em> to start
279 Synergy if another instance is currently running. This
280 allows it to run in the background even when synergy is also
281 started independently, e.g. from the <span class="code">LoginWindow</span>
282 application as described below.
283</li>
284<li>
285 Make this script executable:
286 <span class="userinput">
287 # chmod 755 /Library/StartupItems/Synergy/Synergy
288 </span>
289</li>
290<li>
291 In the same folder, create a file named
292 <span class="code">StartupParameters.plist</span> containing:
293</p><p>
294<span class="codeblock">
295{
296 Description = "Synergy Client";
297 Provides = ("Synergy");
298 Requires = ("Network");
299 OrderPreference = "None";
300}
301</span>
302</li>
303</ul>
304</p><p>
305That's it! If you want to test this setup, you can run the
306startup script as follows:
307</p><p>
308<span class="userinput">
309 # /Library/StartupItems/Synergy/Synergy start
310</span>
311</p><p>
312Any errors, as well as output from Synergy, will be shown in
313your terminal window.
314</p><p>
315Next time you reboot, Synergy should start automatically.
316</p><p>
317<b>2. Run Synergy When a User Logs In</b>
318</p><p>
319Each time a user successfully logs in via the console, the
320<span class="code">LoginWindow</span> application creates a unique session
321cookie and stores it in the environment variable
322<span class="code">$SECURITYSESSIONID</span>. For copy and paste operations
323to work, Synergy needs access to this environment variable. In
324other words, Synergy needs to be launched (directly or
325indirectly) via the <span class="code">LoginWindow</span> application.
326</p><p>
327However, in order to kill any synergy processes started at the
328system level (as described above), we need root access. Thus,
329launching Synergy within the User's environment (e.g. via the
330Startup Items tab in System Preferences -> Accounts) is not an
331option that work in conjunction with the method above.
332</p><p>
333Fortunately, the <span class="code">LoginWindow</span> application provides
334a "hook" for running a custom program (as root, with the username provided as
335the first and only argument) once a user has authenticated, but
336before the user is logged in.
337</p><p>
338Unfortunately, only one such hook is available. If you have
339already installed a Login Hook, you may need to add the text
340from below to your existing script, rather than creating a new
341one.
342</p><p>
343<ul>
344<li>
345 Launch a Terminal window, and become root:
346 <span class="userinput">
347 $ sudo su -
348 </span>
349</li>
350</p><p>
351<li>
352 Find out if a LoginHook already exists:
353 <span class="userinput">
354 # defaults read com.apple.loginwindow LoginHook
355 </span>
356 This will either show the full path to a script or
357 executable file, or the text:
358 <span class="userinput">
359 The domain/default pair of (com.apple.loginwindow, LoginHook) does not exist
360 </span>
361 In the former case, you need to modify your existing script,
362 and/or create a "superscript" which in turn calls your
363 existing script plus the one we will create here.
364</p><p>
365 The rest of this text assumes that this item did not already
366 exist, and that we will create a new script.
367</li>
368<li>
369 Create a folder in which we will store our custom startup
370 script:
371 <span class="userinput">
372 # mkdir -p /Library/LoginWindow
373 </span>
374</li>
375<li>
376 In this folder, create a new script file (let's name it
377 <span class="code">LoginHook.sh</span>), containing the following text:
378</p><p>
379<span class="codeblock">
380#!/bin/sh
381prog=(/usr/local/bin/synergyc -n $(hostname -s) <span class="arg">ip-address-of-server</span>)
382&nbsp;
383### Stop any currently running Synergy client
384killall ${prog[0]##*/}
385&nbsp;
386### Start the new client
387exec "${prog[@]}"
388</span>
389</li>
390<li>
391 Make this script executable:
392 <span class="userinput">
393 # chmod 755 /Library/LoginWindow/LoginHook.sh
394 </span>
395</li>
396<li>
397 Create a login hook to call the script you just created:
398 <span class="userinput">
399 # defaults&nbsp;write&nbsp;com.apple.loginwindow&nbsp;LoginHook&nbsp;/Library/LoginWindow/LoginHook.sh
400 </span>
401</li>
402</ul>
403</p><p>
404More information on setting up login hooks can be found at
405<a target="_top" href="http://docs.info.apple.com/article.html?artnum=301446">Apple</a>.
406</p><p>
407When running the Synergy client, you may need to use the IP
408address of the Synergy server rather than its host name.
409Specifically, unless you have listed the server in your
410local <span class="code">/etc/hosts</span> file or in your local NetInfo
411database, name services (i.e. DNS) may not yet be available by the
412time you log in after power-up. <span class="code">synergyc</span> will
413quit if it cannot resolve the server name.
414</p><p>
415(This is not an issue with the previous method, because the
416<span class="code">StartupParameters.plist</span> file specifies that this
417script should not be run until "network" is available).
418</p><p>
419<b>3. Good Luck!</b>
420</p><p>
421Remember to look in your system log on both your server and your
422client(s) for clues to any problems you may have
423(<span class="code">/var/log/system.log</span> on your OS X box, typically
424<span class="code">/var/log/syslog</span> on Linux boxes).
425</p>
426</body>
427
428</html>
Note: See TracBrowser for help on using the repository browser.