1distccd(1)                  General Commands Manual                 distccd(1)
2
3
4

NAME

6       distccd - distributed C/C++ compiler server
7

SYNOPSIS

9       distccd --daemon [OPTIONS]
10

DESCRIPTION

12       distccd  is  the  server  for  the  distcc(1) distributed compiler.  It
13       accepts and runs compilation jobs for network clients.
14
15       distcc can run over either TCP or a connection command such as  ssh(1).
16       TCP  connections are fast but relatively insecure.  SSH connections are
17       secure but slower.
18
19       For SSH connections, distccd must be installed  on  the  volunteer  but
20       should  not  run  as a daemon -- it will be started over SSH as needed.
21       SSH connections have several advantages: neither the client nor  server
22       listens  on  any new ports; compilations run with the privileges of the
23       user that requested them; unauthorized users cannot access the  server;
24       and source and output is protected in transit.
25
26       For  TCP  connections,  distccd can run either from an inetd-style pro‐
27       gram, or as  a  standalone  server.   Standalone  mode  is  recommended
28       because  it  is  slightly more efficient and allows distccd to regulate
29       the number of incoming jobs.  The --listen and --allow options  can  be
30       used for simple IP-based access control.
31
32       distcc  may  be  started  either  by root or any other user.  If run by
33       root, it gives away privileges and changes to the user specified by the
34       --user  option,  or  the  user  called  "distcc",  or  the  user called
35       "nobody".
36
37       distccd does not have a configuration  file;  it's  behaviour  is  con‐
38       trolled only by command-line options and requests from clients.
39

STANDALONE SERVER

41       The  recommended  method for running distccd is as a standalone server.
42       distccd will listen for network connections and fork several child pro‐
43       cesses to serve them.
44
45       If  you  installed  distcc  using a packaged version you may be able to
46       start the server using the standard mechanism for your  operating  sys‐
47       tem, such as
48
49              # service distcc start
50
51       To  start  distccd  as  a  standalone  service, run a command like this
52       either as root or an ordinary user:
53
54              # distccd --daemon
55

RUNNING FROM INIT

57       distccd may be run as a standalone daemon under the control of  another
58       program  like  init(8) or daemontools.  The super-server starts distccd
59       when the system boots, and whenever it exits.
60
61       distccd should be started just as for a standalone server, except  that
62       the --no-detach option should be used so that the super-server can mon‐
63       itor it.
64
65       For example, to add distccd as a process to Linux  sysvinit,  add  this
66       line to /etc/inittab
67
68              dscc:2345:respawn:/usr/local/bin/distccd  --verbose  --no-detach
69              --daemon
70

RUNNING FROM INETD

72       distccd may be started from a network super-server  such  as  inetd  or
73       xinetd.  In this case inetd listens for network connections and invokes
74       distccd when one arrives.
75
76       This is slightly less efficient than running a standalone distccd  dae‐
77       mon.   distccd  is  not  able to regulate the number of concurrent jobs
78       accepted, but there may be an option in your inetd configuration to  do
79       so.
80
81       For  traditional  Unix  inetd,  a  line  like  this  can  be  added  to
82       /etc/inetd.conf:
83
84              distcc  stream  tcp  nowait.6000   root   /usr/local/bin/distccd
85              distccd --inetd
86
87       inetd  imposes  a limit on the rate of connections to a service to pro‐
88       tect against accidental or intentional overuse.  The default  in  Linux
89       NetKit  inetd is 40 per minute, which is far  too low for distccd.  The
90       .6000 option raises the limit to 6000 per minute.
91

TERMINATING DISTCCD

93       To shut down a standalone server, send a SIGTERM signal to  the  parent
94       process.   The most reliable way to do this from a script is to use the
95       --pid-file option to record its process ID.  Shutting down  the  server
96       in this way should allow any jobs currently in progress to complete.
97

OPTIONS

99       --help Display summary usage information.
100
101       --version
102              Shows the daemon version and exits.
103
104       -j, --jobs JOBS
105              Sets  a  limit on the number of jobs that can be accepted at any
106              time.  By default this is set to two greater than the number  of
107              CPUs  on  the machine, to allow for some processes being blocked
108              on network IO.  (Daemon mode only.)
109
110       -N, --nice NICENESS
111              Makes the daemon more nice about giving  up  the  CPU  to  other
112              tasks  on  the machine.  NICENESS is an increment to the current
113              priority of the process.  The range of priorities depends on the
114              operating system but is typically 0 to 20.  By default the nice‐
115              ness is increased by 5.
116
117       -p, --port PORT
118              Set the TCP port to listen on, rather than the default of  3632.
119              (Daemon mode only.)
120
121       --listen ADDRESS
122              Instructs  the  distccd  daemon  to  listen  on  the  IP address
123              ADDRESS.  This can be useful for access  control  on  dual-homed
124              hosts.  (Daemon mode only.)
125
126       -P, --pid-file FILE
127              Save daemon process id to file FILE.  (Daemon mode only.)
128
129       --user USER
130              If distccd gets executed as root, change to user USER.
131
132       -a, --allow IPADDR[/MASK]
133              Instructs  distccd  to  accept  connections  from the IP address
134              IPADDR.  A CIDR mask length can be supplied optionally  after  a
135              trailing  slash,  e.g.  192.168.0.0/24,  in which case addresses
136              that match in the most significant MASK bits  will  be  allowed.
137              If  no  --allow options are specified, distccd will exit immedi‐
138              ately!  Unauthorized connections are rejected by closing the TCP
139              connection  immediately.   A warning is logged on the server but
140              nothing is sent to the client.
141
142       --allow-private
143              Allow    private    networks    (10.0.0.0/8,     192.168.0.0/16,
144              172.16.0.0/12, and 127.0.0.0/8).
145
146       --job-lifetime SECONDS
147              Kills  a  distccd  job if it runs for more than SECONDS seconds.
148              This prevents denial of service from clients that don't properly
149              disconnect and compilers that fail to terminate. By default this
150              is turned off.
151
152       --no-detach
153              Do not detach from the shell that started the daemon.
154
155       --no-fork
156              Don't fork children for each connection, to allow attaching gdb.
157              Don't use this if you don't understand it!
158
159       --log-file FILE
160              Send  messages to file FILE instead of syslog.  Logging directly
161              to a file is significantly faster than going via syslog  and  is
162              recommended.
163
164       --log-level LEVEL
165              Set  the  minimum severity of error that will be included in the
166              log file.  Useful if you only want to see error messages  rather
167              than  an  entry  for  each  connection.  LEVEL can be any of the
168              standard syslog levels, and in particular critical, error, warn‐
169              ing, notice, info, or debug.
170
171       --log-stderr
172              Send  log  messages  to stderr, rather than to a file or syslog.
173              This is mainly intended for use in debugging.   Do  not  use  in
174              inetd mode.
175
176       --verbose
177              Include debug messages in log.  Equivalent to --log-level=debug
178
179       --wizard
180              Turn  on all options appropriate for starting distccd under gdb:
181              run as a daemon, log verbosely to stderr, and do not  detach  or
182              fork.  For wizards only.
183
184       --stats
185              Turn on the statistics HTTP server. By default it is off.  (Dae‐
186              mon mode only.)
187
188       --stats-port PORT
189              Set the TCP port to listen on for HTTP requests, rather than the
190              default of 3633.  (Daemon mode only.)
191
192       --inetd
193              Serve a client connected to stdin/stdout.  As the name suggests,
194              this option should be used when distccd is  run  from  within  a
195              super-server  like inetd.  distccd assumes inetd mode when stdin
196              is a socket.
197
198       --daemon
199              Bind and listen on a socket, rather  than  running  from  inetd.
200              This  is  used for standalone mode.  distccd assumes daemon mode
201              at startup if stdin is a tty, so --daemon should  be  explicitly
202              specified when starting distccd from a script or in a non-inter‐
203              active ssh connection.
204
205       --enable-tcp-insecure
206              By default (since Distcc 3.3) distcc will only execute  binaries
207              that  are  masqueraded  to distcc in /usr/lib/distcc. This turns
208              that off, and opens distcc up to executing arbitrary code.  This
209              feature  is  mainly for distcc's test suite. See MASQUERADING of
210              distcc(1).
211
212       --zeroconf
213              Register the availability of this  distccd  server  using  Avahi
214              Zeroconf  DNS  Service  Discovery  (DNS-SD).  This allows distcc
215              clients on the local network to access this distccd server with‐
216              out  explicitly  listing  its  host  name or IP address in their
217              distcc host list: the distcc clients can just use "+zeroconf" in
218              their  distcc  host  lists.   Can optionally use -j parameter to
219              specify the maximum number of jobs that this server can  process
220              concurrently.  This option is only available if distccd was com‐
221              piled with Avahi support enabled.
222
223       --auth Perform GSS-API based mutual  authentication.   This  option  is
224              only available if distccd was compiled with the --with-auth con‐
225              figure option.
226
227       --show-principal
228              Displays the name of the distccd  security  principal  extracted
229              from  the environment.  This option is only available if distccd
230              was compiled with the --with-auth configure option.
231
232       --blacklist=FILE
233              Instruct distccd to reject connections from users whose  princi‐
234              pal  names are listed in FILE.  This option is only available if
235              distccd was compiled with the --with-auth configure  option  and
236              if distccd is run with the --auth option.
237
238       --whitelist=FILE
239              Instruct  distccd  to  accept  connections only from users whose
240              principal names are listed in FILE.  This option is only  avail‐
241              able  if  distccd  was  compiled  with the --with-auth configure
242              option and if distccd is run with the --auth option.
243

SEARCH PATHS

245       distcc can pass either a relative or an absolute name for the  compiler
246       to distccd.  If distcc is given an explicit absolute compiler filename,
247       that name is used verbatim on both the client and server.  If the  com‐
248       piler  name  is  not an absolute path, or if the client is used in mas‐
249       querade mode, then the server's PATH is searched.
250
251       distccd inherits its search path from its parent process.   By  default
252       distccd  tries  to remove directories that seem to contain distccd mas‐
253       querade  links,  to   guard   against   inadvertent   recursion.    The
254       DISTCCD_PATH environment variable may be used to set the path.
255
256       The  search  path is logged when --verbose is given.  In case of confu‐
257       sion, check the logs.
258
259       When distccd is run over ssh, the $HOME/.ssh/environment  file  may  be
260       useful in setting the path.  See ssh(1).
261

DIAGNOSTICS

263       distccd  logs  messages  to  syslog's daemon facility by default, which
264       normally writes to /var/log/daemon or /var/log/messages.  Log  messages
265       can be sent to a different file using the --log-file option.
266

ENVIRONMENT VARIABLES

268       DISTCC_CMDLIST
269              If  the  environment variable DISTCC_CMDLIST is set, load a list
270              of supported commands from the file named by DISTCC_CMDLIST, and
271              refuse to serve any command whose last DISTCC_CMDLIST_MATCHWORDS
272              last words do not match those of a command in  that  list.   See
273              the comments in src/serve.c.
274
275       DISTCC_CMDLIST_NUMWORDS
276              The  number of words, from the end of the command, to match. The
277              default is 1.
278
279       DISTCCD_PATH
280              When starting distccd, if this value is  set  it  will  be  used
281              unaltered  for  the  command-execution PATH.  The code that nor‐
282              mally tries to remove masquerade directories from  the  path  is
283              skipped.
284
285       DISTCC_SAVE_TEMPS
286              If set to 1, temporary files are not deleted after use.
287
288       Note  that  DISTCC_LOG  does  not  affect  the  log destination for the
289       server.
290
291       DISTCC_TCP_DEFER_ACCEPT
292              On Linux, turn on the TCP_DEFER_ACCEPT socket option.   Defaults
293              to on.
294
295       TMPDIR Directory  for  temporary files such as preprocessor output.  By
296              default /tmp/ is used.
297
298       DISTCCD_PRINCIPAL
299              If set, specifies the name of the principal  that  distccd  runs
300              under,  and is used to authenticate with the client.  This envi‐
301              ronment variable is only used if distccd was compiled  with  the
302              --with-auth  configure  option  and  if  distccd is run with the
303              --auth option.
304

SEE ALSO

306       distcc(1), pump(1), include_server(1), gcc(1), make(1), and   ccache(1)
307       http://code.google.com/p/distcc/
308

BUGS

310       IP-based  access  control is not secure against attackers able to spoof
311       TCP connections, and cannot discriminate different users on a client.
312
313       TCP connections are not secure against attackers  able  to  observe  or
314       modify network traffic.
315
316       Because ccache does not cache compilation from .i files, it is not use‐
317       ful to call it from distccd.
318

LICENCE

320       You are free to use distcc.  distcc  (including  this  manual)  may  be
321       copied, modified or distributed only under the terms of the GNU General
322       Public Licence version 2 or later.  distcc  comes  with  absolutely  no
323       warrany.  A copy of the GPL is included in the file COPYING.
324

AUTHOR

326       distcc  was  written  by Martin Pool <mbp@sourcefrog.net>, with the co-
327       operation of many scholars including Wayne Davison, Frerich Raabe, Dim‐
328       itri  Papadopoulos  and others noted in the NEWS file.  See pump(1) for
329       the   authors    of    pump    mode.     Please    report    bugs    to
330       <distcc@lists.samba.org>.
331
332
333
334                                  9 June 2008                       distccd(1)
Impressum