Debian Codegraph @

doc/web/man/distccd_1.html

raw
1 <HTML>
2 <!-- this file was generated by troffcvt and tc2html -->
3 <HEAD>
4 <TITLE>
5 distccd manual page
6 </TITLE>
7 </HEAD>
8 <BODY>
9 <H1>
10 distccd manual page<BR>
11 </H1>
12 <P>
13 <H2>
14 Table of Contents
15 </H2>
16 <!-- INSERT TOC HERE, MAYBE -->
17 <!-- TOC BEGIN -->
18 <UL>
19 <LI>
20 <A HREF=#TOC_1> NAME</A>
21 <LI>
22 <A HREF=#TOC_2> SYNOPSIS</A>
23 <LI>
24 <A HREF=#TOC_3> DESCRIPTION</A>
25 <LI>
26 <A HREF=#TOC_4> STANDALONE SERVER</A>
27 <LI>
28 <A HREF=#TOC_5> RUNNING FROM INIT</A>
29 <LI>
30 <A HREF=#TOC_6> RUNNING FROM INETD</A>
31 <LI>
32 <A HREF=#TOC_7> TERMINATING DISTCCD</A>
33 <LI>
34 <A HREF=#TOC_8> OPTIONS</A>
35 <LI>
36 <A HREF=#TOC_9> SEARCH PATHS</A>
37 <LI>
38 <A HREF=#TOC_10> DIAGNOSTICS</A>
39 <LI>
40 <A HREF=#TOC_11> ENVIRONMENT VARIABLES</A>
41 <LI>
42 <A HREF=#TOC_12> SEE ALSO</A>
43 <LI>
44 <A HREF=#TOC_13> BUGS</A>
45 <LI>
46 <A HREF=#TOC_14> LICENCE</A>
47 <LI>
48 <A HREF=#TOC_15> AUTHOR</A>
49 </UL>
50 <!-- TOC END -->
51 <BR>
52 <H2>
53 <A NAME=TOC_1>
54 NAME</A>
55 </H2>
56 distccd - distributed C/C++ compiler server<BR>
57 <H2>
58 <A NAME=TOC_2>
59 SYNOPSIS</A>
60 </H2>
61 <B>distccd --daemon</B> <I> [OPTIONS]</I><BR>
62 <H2>
63 <A NAME=TOC_3>
64 DESCRIPTION</A>
65 </H2>
66 <I>distccd</I> is the server for the distcc(1) distributed compiler.
67 It accepts and runs compilation jobs for network clients.<BR>
68 <P>
69 distcc can run over either TCP or a connection command such as
70 ssh(1). TCP connections are fast but relatively insecure. SSH
71 connections are secure but slower.<BR>
72 <P>
73 For SSH connections, distccd must be installed on the volunteer
74 but should not run as a daemon -- it will be started over SSH
75 as needed. SSH connections have several advantages: neither the
76 client nor server listens on any new ports; compilations run with
77 the privileges of the user that requested them; unauthorized users
78 cannot access the server; and source and output is protected in
79 transit.<BR>
80 <P>
81 For TCP connections, distccd can run either from an inetd-style
82 program, or as a standalone server. Standalone mode is recommended
83 because it is slightly more efficient and allows distccd to regulate
84 the number of incoming jobs. The <B> --listen</B> and <B> --allow</B>
85 options can be used for simple IP-based access control.<BR>
86 <P>
87 distcc may be started either by root or any other user. If run
88 by root, it gives away privileges and changes to the user specified
89 by the <B> --user</B> option, or the user called &quot;distcc&quot;,
90 or the user called &quot;nobody&quot;.<BR>
91 <P>
92 distccd does not have a configuration file; it's behaviour is
93 controlled only by command-line options and requests from clients.<BR>
94 <H2>
95 <A NAME=TOC_4>
96 STANDALONE SERVER</A>
97 </H2>
98 The recommended method for running distccd is as a standalone
99 server. distccd will listen for network connections and fork several
100 child processes to serve them.<BR>
101 <P>
102 If you installed distcc using a packaged version you may be able
103 to start the server using the standard mechanism for your operating
104 system, such as<BR>
105 <UL>
106 <P>
107 # service distcc start<BR>
108 </UL>
109 <P>
110 To start distccd as a standalone service, run a command like this
111 either as root or an ordinary user:<BR>
112 <UL>
113 <P>
114 # distccd --daemon<BR>
115 </UL>
116 <H2>
117 <A NAME=TOC_5>
118 RUNNING FROM INIT</A>
119 </H2>
120 distccd may be run as a standalone daemon under the control of
121 another program like init(8) or daemontools. The super-server
122 starts distccd when the system boots, and whenever it exits.<BR>
123 <P>
124 distccd should be started just as for a standalone server, except
125 that the <B> --no-detach</B> option should be used so that the
126 super-server can monitor it.<BR>
127 <P>
128 For example, to add distccd as a process to Linux sysvinit, add
129 this line to <I> /etc/inittab</I><BR>
130 <UL>
131 <P>
132 dscc:2345:respawn:/usr/local/bin/distccd --verbose --no-detach
133 --daemon<BR>
134 </UL>
135 <H2>
136 <A NAME=TOC_6>
137 RUNNING FROM INETD</A>
138 </H2>
139 distccd may be started from a network super-server such as inetd
140 or xinetd. In this case inetd listens for network connections
141 and invokes distccd when one arrives.<BR>
142 <P>
143 This is slightly less efficient than running a standalone distccd
144 daemon. distccd is not able to regulate the number of concurrent
145 jobs accepted, but there may be an option in your inetd configuration
146 to do so.<BR>
147 <P>
148 For traditional Unix inetd, a line like this can be added to /etc/inetd.conf:<BR>
149 <UL>
150 <P>
151 distcc stream tcp nowait.6000 root /usr/local/bin/distccd distccd
152 --inetd<BR>
153 </UL>
154 <P>
155 inetd imposes a limit on the rate of connections to a service
156 to protect against accidental or intentional overuse. The default
157 in Linux NetKit inetd is 40 per minute, which is far too low
158 for distccd. The .6000 option raises the limit to 6000 per minute.<BR>
159 <H2>
160 <A NAME=TOC_7>
161 TERMINATING DISTCCD</A>
162 </H2>
163 To shut down a standalone server, send a SIGTERM signal to the
164 parent process. The most reliable way to do this from a script
165 is to use the <I> --pid-file</I> option to record its process
166 ID. Shutting down the server in this way should allow any jobs
167 currently in progress to complete.<BR>
168 <H2>
169 <A NAME=TOC_8>
170 OPTIONS</A>
171 </H2>
172 <BR>
173 <DL>
174 <DT>
175 <B>--help</B>
176 </DT>
177 <DD>
178 Display summary usage information.<BR>
179 </DD>
180 <DT>
181 <B>--version</B>
182 </DT>
183 <DD>
184 Shows the daemon version and exits.<BR>
185 </DD>
186 <DT>
187 <B>-j, --jobs JOBS</B>
188 </DT>
189 <DD>
190 Sets a limit on the number of jobs that can be accepted at any
191 time. By default this is set to two greater than the number of
192 CPUs on the machine, to allow for some processes being blocked
193 on network IO. (Daemon mode only.)<BR>
194 </DD>
195 <DT>
196 <B>-N, --nice NICENESS</B>
197 </DT>
198 <DD>
199 Makes the daemon more nice about giving up the CPU to other tasks
200 on the machine. NICENESS is an increment to the current priority
201 of the process. The range of priorities depends on the operating
202 system but is typically 0 to 20. By default the niceness is increased
203 by 5.<BR>
204 </DD>
205 <DT>
206 <B>-p, --port PORT</B>
207 </DT>
208 <DD>
209 Set the TCP port to listen on, rather than the default of 3632.
210 (Daemon mode only.)<BR>
211 </DD>
212 <DT>
213 <B>--listen ADDRESS</B>
214 </DT>
215 <DD>
216 Instructs the distccd daemon to listen on the IP address ADDRESS.
217 This can be useful for access control on dual-homed hosts. (Daemon
218 mode only.)<BR>
219 </DD>
220 <DT>
221 <B>-P, --pid-file FILE</B>
222 </DT>
223 <DD>
224 Save daemon process id to file FILE. (Daemon mode only.)<BR>
225 </DD>
226 <DT>
227 <B>--user USER</B>
228 </DT>
229 <DD>
230 If distccd gets executed as root, change to user USER.<BR>
231 </DD>
232 <DT>
233 <B>-a, --allow IPADDR[/MASK]</B>
234 </DT>
235 <DD>
236 Instructs distccd to accept connections from the IP address IPADDR.
237 A CIDR mask length can be supplied optionally after a trailing
238 slash, e.g. 192.168.0.0/24, in which case addresses that match
239 in the most significant MASK bits will be allowed. If no --allow
240 options are specified, distccd will exit immediately! Unauthorized
241 connections are rejected by closing the TCP connection immediately.
242 A warning is logged on the server but nothing is sent to the client.<BR>
243 </DD>
244 <DT>
245 <B>--job-lifetime SECONDS</B>
246 </DT>
247 <DD>
248 Kills a distccd job if it runs for more than SECONDS seconds.
249 This prevents denial of service from clients that don't properly
250 disconnect and compilers that fail to terminate. By default this
251 is turned off.<BR>
252 </DD>
253 <DT>
254 <B>--no-detach</B>
255 </DT>
256 <DD>
257 Do not detach from the shell that started the daemon.<BR>
258 </DD>
259 <DT>
260 <B>--no-fork</B>
261 </DT>
262 <DD>
263 Don't fork children for each connection, to allow attaching gdb.
264 Don't use this if you don't understand it!<BR>
265 </DD>
266 <DT>
267 <B>--log-file FILE</B>
268 </DT>
269 <DD>
270 Send messages to file FILE instead of syslog. Logging directly
271 to a file is significantly faster than going via syslog and is
272 recommended.<BR>
273 </DD>
274 <DT>
275 <B>--log-level LEVEL</B>
276 </DT>
277 <DD>
278 Set the minimum severity of error that will be included in the
279 log file. Useful if you only want to see error messages rather
280 than an entry for each connection. LEVEL can be any of the standard
281 syslog levels, and in particular <I> critical, error, warning,
282 notice, info,</I> or <I> debug.</I><BR>
283 </DD>
284 <DT>
285 <B>--log-stderr</B>
286 </DT>
287 <DD>
288 Send log messages to stderr, rather than to a file or syslog.
289 This is mainly intended for use in debugging. Do not use in inetd
290 mode.<BR>
291 </DD>
292 <DT>
293 <B>--verbose</B>
294 </DT>
295 <DD>
296 Include debug messages in log. Equivalent to <B> --log-level=debug</B><BR>
297 </DD>
298 <DT>
299 <B>--wizard</B>
300 </DT>
301 <DD>
302 Turn on all options appropriate for starting distccd under gdb:
303 run as a daemon, log verbosely to stderr, and do not detach or
304 fork. For wizards only.<BR>
305 </DD>
306 <DT>
307 <B>--stats</B>
308 </DT>
309 <DD>
310 Turn on the statistics HTTP server. By default it is off. (Daemon
311 mode only.)<BR>
312 </DD>
313 <DT>
314 <B>--stats-port PORT</B>
315 </DT>
316 <DD>
317 Set the TCP port to listen on for HTTP requests, rather than the
318 default of 3633. (Daemon mode only.)<BR>
319 </DD>
320 <DT>
321 <B>--inetd</B>
322 </DT>
323 <DD>
324 Serve a client connected to stdin/stdout. As the name suggests,
325 this option should be used when distccd is run from within a super-server
326 like inetd. distccd assumes inetd mode when stdin is a socket.<BR>
327 </DD>
328 <DT>
329 <B>--daemon</B>
330 </DT>
331 <DD>
332 Bind and listen on a socket, rather than running from inetd.
333 This is used for standalone mode. distccd assumes daemon mode
334 at startup if stdin is a tty, so --daemon should be explicitly
335 specified when starting distccd from a script or in a non-interactive
336 ssh connection.<BR>
337 </DD>
338 <DT>
339 <B>--zeroconf</B>
340 </DT>
341 <DD>
342 Register the availability of this distccd server using Avahi Zeroconf
343 DNS Service Discovery (DNS-SD). This allows distcc clients on
344 the local network to access this distccd server without explicitly
345 listing its host name or IP address in their distcc host list:
346 the distcc clients can just use &quot;+zeroconf&quot; in their
347 distcc host lists. <B> This option is only available if distccd
348 was compiled with</B> <B> Avahi support enabled.</B><BR>
349 </DD>
350 <DT>
351 <B>--auth</B>
352 </DT>
353 <DD>
354 Perform GSS-API based mutual authentication. <B> This option is
355 only available if distccd was compiled with</B> <B> the --with-auth
356 configure option.</B><BR>
357 </DD>
358 <DT>
359 <B>--show-principal</B>
360 </DT>
361 <DD>
362 Displays the name of the distccd security principal extracted
363 from the environment. <B> This option is only available if distccd
364 was compiled with</B> <B> the --with-auth configure option.</B><BR>
365 </DD>
366 <DT>
367 <B>--blacklist=FILE</B>
368 </DT>
369 <DD>
370 Instruct distccd to reject connections from users whose principal
371 names are listed in FILE. <B> This option is only available if
372 distccd was compiled with</B> <B> the --with-auth configure option
373 and if distccd is run with the</B> <B> --auth option.</B><BR>
374 </DD>
375 <DT>
376 <B>--whitelist=FILE</B>
377 </DT>
378 <DD>
379 Instruct distccd to accept connections only from users whose principal
380 names are listed in FILE. <B> This option is only available if
381 distccd was compiled with</B> <B> the --with-auth configure option
382 and if distccd is run with the</B> <B> --auth option.</B><BR>
383 </DD>
384 </DL>
385 <H2>
386 <A NAME=TOC_9>
387 SEARCH PATHS</A>
388 </H2>
389 <BR>
390 <P>
391 distcc can pass either a relative or an absolute name for the
392 compiler to distccd. If distcc is given an explicit absolute
393 compiler filename, that name is used verbatim on both the client
394 and server. If the compiler name is not an absolute path, or if
395 the client is used in masquerade mode, then the server's PATH
396 is searched.<BR>
397 <P>
398 distccd inherits its search path from its parent process. By
399 default distccd tries to remove directories that seem to contain
400 distccd masquerade links, to guard against inadvertent recursion.
401 The <B> DISTCCD_PATH</B> environment variable may be used to set
402 the path.<BR>
403 <P>
404 The search path is logged when --verbose is given. In case of
405 confusion, check the logs.<BR>
406 <P>
407 When distccd is run over ssh, the <I> $HOME/.ssh/environment</I>
408 file may be useful in setting the path. See <B> ssh(1).</B><BR>
409 <H2>
410 <A NAME=TOC_10>
411 DIAGNOSTICS</A>
412 </H2>
413 distccd logs messages to syslog's <I> daemon</I> facility by default,
414 which normally writes to <I> /var/log/daemon</I> or <I> /var/log/messages.</I>
415 Log messages can be sent to a different file using the <B> --log-file
416 option.</B><BR>
417 <H2>
418 <A NAME=TOC_11>
419 ENVIRONMENT VARIABLES</A>
420 </H2>
421 <BR>
422 <DL>
423 <DT>
424 <B>DISTCC_CMDLIST</B>
425 </DT>
426 <DD>
427 If the environment variable DISTCC_CMDLIST is set, load a list
428 of supported commands from the file named by DISTCC_CMDLIST, and
429 refuse to serve any command whose last DISTCC_CMDLIST_MATCHWORDS
430 last words do not match those of a command in that list. See
431 the comments in src/serve.c.<BR>
432 </DD>
433 <DT>
434 <B>DISTCC_CMDLIST_NUMWORDS</B>
435 </DT>
436 <DD>
437 The number of words, from the end of the command, to match. The
438 default is 1.<BR>
439 </DD>
440 <DT>
441 <B>DISTCCD_PATH</B>
442 </DT>
443 <DD>
444 When starting distccd, if this value is set it will be used unaltered
445 for the command-execution PATH. The code that normally tries
446 to remove masquerade directories from the path is skipped.<BR>
447 </DD>
448 <DT>
449 <B>DISTCC_SAVE_TEMPS</B>
450 </DT>
451 <DD>
452 If set to 1, temporary files are not deleted after use.<BR>
453 </DD>
454 </DL>
455 <P>
456 Note that <B> DISTCC_LOG</B> does not affect the log destination
457 for the server.<BR>
458 <DL>
459 <DT>
460 <B>DISTCC_TCP_DEFER_ACCEPT</B>
461 </DT>
462 <DD>
463 On Linux, turn on the TCP_DEFER_ACCEPT socket option. Defaults
464 to on.<BR>
465 </DD>
466 <DT>
467 <B>TMPDIR</B>
468 </DT>
469 <DD>
470 Directory for temporary files such as preprocessor output. By
471 default /tmp/ is used.<BR>
472 </DD>
473 <DT>
474 <B>DISTCCD_PRINCIPAL</B>
475 </DT>
476 <DD>
477 If set, specifies the name of the principal that distccd runs
478 under, and is used to authenticate with the client. <B> This environment
479 variable is only used if distccd was compiled with</B> <B> the
480 --with-auth configure option and if distccd is run with the --auth
481 option.</B><BR>
482 </DD>
483 </DL>
484 <H2>
485 <A NAME=TOC_12>
486 SEE ALSO</A>
487 </H2>
488 <B>distcc</B>(1), <B>pump</B>(1), <B>include_server</B>(1), <B>gcc</B>(1),
489 <B>make</B>(1), and <B>ccache</B>(1) <I> http://code.google.com/p/distcc/</I><BR>
490 <H2>
491 <A NAME=TOC_13>
492 BUGS</A>
493 </H2>
494 IP-based access control is not secure against attackers able to
495 spoof TCP connections, and cannot discriminate different users
496 on a client.<BR>
497 <P>
498 TCP connections are not secure against attackers able to observe
499 or modify network traffic.<BR>
500 <P>
501 Because ccache does not cache compilation from <B> .i</B> files,
502 it is not useful to call it from distccd.<BR>
503 <H2>
504 <A NAME=TOC_14>
505 LICENCE</A>
506 </H2>
507 You are free to use distcc. distcc (including this manual) may
508 be copied, modified or distributed only under the terms of the
509 GNU General Public Licence version 2 or later. distcc comes with
510 absolutely no warrany. A copy of the GPL is included in the file
511 COPYING.<BR>
512 <H2>
513 <A NAME=TOC_15>
514 AUTHOR</A>
515 </H2>
516 distcc was written by Martin Pool &lt;[email protected]&gt;,
517 with the co-operation of many scholars including Wayne Davison,
518 Frerich Raabe, Dimitri Papadopoulos and others noted in the NEWS
519 file. See <B>pump</B>(1) for the authors of pump mode. Please
520 report bugs to &lt;[email protected]&gt;.<BR>
521 </BODY>
522 </HTML>