Provided by: distcc_3.4+really3.4-3_amd64 
NAME
distccd - distributed C/C++ compiler server
SYNOPSIS
distccd --daemon [OPTIONS]
DESCRIPTION
distccd is the server for the distcc(1) distributed compiler. It accepts and runs
compilation jobs for network clients.
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.
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.
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 --listen and --allow
options can be used for simple IP-based access control.
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 --user option, or the user called
"distcc", or the user called "nobody".
distccd does not have a configuration file; it's behaviour is controlled only by command-
line options and requests from clients.
STANDALONE SERVER
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.
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
# service distcc start
To start distccd as a standalone service, run a command like this either as root or an
ordinary user:
# distccd --daemon
RUNNING FROM INIT
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.
distccd should be started just as for a standalone server, except that the --no-detach
option should be used so that the super-server can monitor it.
For example, to add distccd as a process to Linux sysvinit, add this line to /etc/inittab
dscc:2345:respawn:/usr/local/bin/distccd --verbose --no-detach --daemon
RUNNING FROM INETD
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.
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.
For traditional Unix inetd, a line like this can be added to /etc/inetd.conf:
distcc stream tcp nowait.6000 root /usr/local/bin/distccd distccd --inetd
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.
TERMINATING DISTCCD
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 --pid-file option to record its
process ID. Shutting down the server in this way should allow any jobs currently in
progress to complete.
OPTIONS
--help Display summary usage information.
--version
Shows the daemon version and exits.
-j, --jobs JOBS
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.)
-N, --nice NICENESS
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.
-p, --port PORT
Set the TCP port to listen on, rather than the default of 3632. (Daemon mode
only.)
--listen ADDRESS
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.)
-P, --pid-file FILE
Save daemon process id to file FILE. (Daemon mode only.)
--user USER
If distccd gets executed as root, change to user USER.
-a, --allow IPADDR[/MASK]
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.
--allow-private
Allow private networks (10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, and
127.0.0.0/8).
--job-lifetime SECONDS
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.
--no-detach
Do not detach from the shell that started the daemon.
--no-fork
Don't fork children for each connection, to allow attaching gdb. Don't use this if
you don't understand it!
--log-file FILE
Send messages to file FILE instead of syslog. Logging directly to a file is
significantly faster than going via syslog and is recommended.
--log-level LEVEL
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 critical, error,
warning, notice, info, or debug.
--log-stderr
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.
--verbose
Include debug messages in log. Equivalent to --log-level=debug
--wizard
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.
--stats
Turn on the statistics HTTP server. By default it is off. (Daemon mode only.)
--stats-port PORT
Set the TCP port to listen on for HTTP requests, rather than the default of 3633.
(Daemon mode only.)
--inetd
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.
--daemon
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.
--enable-tcp-insecure
By default (since Distcc 3.3) distcc will only execute binaries that are
masqueraded to distcc in /usr/lib/distcc. This turns that off, and opens distcc up
to executing arbitrary code. This feature is mainly for distcc's test suite. See
MASQUERADING of distcc(1).
--zeroconf
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. Can optionally use -j parameter to specify the maximum number of jobs that
this server can process concurrently. This option is only available if distccd was
compiled with Avahi support enabled.
--auth Perform GSS-API based mutual authentication. This option is only available if
distccd was compiled with the --with-auth configure option.
--show-principal
Displays the name of the distccd security principal extracted from the environment.
This option is only available if distccd was compiled with the --with-auth
configure option.
--blacklist=FILE
Instruct distccd to reject connections from users whose principal names are listed
in FILE. This option is only available if distccd was compiled with the --with-
auth configure option and if distccd is run with the --auth option.
--whitelist=FILE
Instruct distccd to accept connections only from users whose principal names are
listed in FILE. This option is only available if distccd was compiled with the
--with-auth configure option and if distccd is run with the --auth option.
SEARCH PATHS
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.
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 DISTCCD_PATH environment variable may be used to set the path.
The search path is logged when --verbose is given. In case of confusion, check the logs.
When distccd is run over ssh, the $HOME/.ssh/environment file may be useful in setting the
path. See ssh(1).
DIAGNOSTICS
distccd logs messages to syslog's daemon facility by default, which normally writes to
/var/log/daemon or /var/log/messages. Log messages can be sent to a different file using
the --log-file option.
ENVIRONMENT VARIABLES
DISTCC_CMDLIST
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.
DISTCC_CMDLIST_NUMWORDS
The number of words, from the end of the command, to match. The default is 1.
DISTCCD_PATH
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.
DISTCC_SAVE_TEMPS
If set to 1, temporary files are not deleted after use.
Note that DISTCC_LOG does not affect the log destination for the server.
DISTCC_TCP_DEFER_ACCEPT
On Linux, turn on the TCP_DEFER_ACCEPT socket option. Defaults to on.
TMPDIR Directory for temporary files such as preprocessor output. By default /tmp/ is
used.
DISTCCD_PRINCIPAL
If set, specifies the name of the principal that distccd runs under, and is used to
authenticate with the client. This environment variable is only used if distccd
was compiled with the --with-auth configure option and if distccd is run with the
--auth option.
SEE ALSO
distcc(1), distcc-pump(1), include_server(1), gcc(1), make(1), and ccache(1)
http://code.google.com/p/distcc/
BUGS
IP-based access control is not secure against attackers able to spoof TCP connections, and
cannot discriminate different users on a client.
TCP connections are not secure against attackers able to observe or modify network
traffic.
Because ccache does not cache compilation from .i files, it is not useful to call it from
distccd.
LICENCE
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.
AUTHOR
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 distcc-pump(1) for the authors of pump mode. Please report bugs to
<distcc@lists.samba.org>.
9 June 2008 distccd(1)