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