1distccd(1) General Commands Manual distccd(1)
2
6 distccd - distributed C/C++ compiler server
7
9 distccd --daemon [OPTIONS]
10
12 distccd is the server for the distcc(1) distributed compiler. It
13 accepts and runs compilation jobs for network clients.
14 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 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 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 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 distccd does not have a configuration file; it's behaviour is con‐
38 trolled only by command-line options and requests from clients.
39
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 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 # service distcc start
50 To start distccd as a standalone service, run a command like this
52 either as root or an ordinary user:
53 # distccd --daemon
55
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 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 For example, to add distccd as a process to Linux sysvinit, add this
66 line to /etc/inittab
67 dscc:2345:respawn:/usr/local/bin/distccd --verbose --no-detach
69 --daemon
70
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 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 For traditional Unix inetd, a line like this can be added to
82 /etc/inetd.conf:
83 distcc stream tcp nowait.6000 root /usr/local/bin/distccd
85 distccd --inetd
86 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
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
99 --help Display summary usage information.
100 --version
102 Shows the daemon version and exits.
103 -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 -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 -p, --port PORT
118 Set the TCP port to listen on, rather than the default of 3632.
119 (Daemon mode only.)
120 --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 -P, --pid-file FILE
127 Save daemon process id to file FILE. (Daemon mode only.)
128 --user USER
130 If distccd gets executed as root, change to user USER.
131 -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 --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 --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 --no-detach
153 Do not detach from the shell that started the daemon.
154 --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 --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 --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 --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 --verbose
177 Include debug messages in log. Equivalent to --log-level=debug
178 --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 --stats
185 Turn on the statistics HTTP server. By default it is off. (Dae‐
186 mon mode only.)
187 --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 --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 --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 --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 --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 --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 --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 --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 --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
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 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 The search path is logged when --verbose is given. In case of confu‐
257 sion, check the logs.
258 When distccd is run over ssh, the $HOME/.ssh/environment file may be
260 useful in setting the path. See ssh(1).
261
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
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 DISTCC_CMDLIST_NUMWORDS
276 The number of words, from the end of the command, to match. The
277 default is 1.
278 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 DISTCC_SAVE_TEMPS
286 If set to 1, temporary files are not deleted after use.
287 Note that DISTCC_LOG does not affect the log destination for the
289 server.
290 DISTCC_TCP_DEFER_ACCEPT
292 On Linux, turn on the TCP_DEFER_ACCEPT socket option. Defaults
293 to on.
294 TMPDIR Directory for temporary files such as preprocessor output. By
296 default /tmp/ is used.
297 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
306 distcc(1), pump(1), include_server(1), gcc(1), make(1), and ccache(1)
307 http://code.google.com/p/distcc/
308
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 TCP connections are not secure against attackers able to observe or
314 modify network traffic.
315 Because ccache does not cache compilation from .i files, it is not use‐
317 ful to call it from distccd.
318
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
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 9 June 2008 distccd(1)