Manual Pages for UNIX Darwin command on man distccd

distccd(1) distccd(1)

NAME

distccd - distributed C/C++ compiler server

SYNOPSIS

ddiissttccccdd --ddaaeemmoonn [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 pro-

gram, 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 --lliisstteenn and --aallllooww 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

--uusseerr option, or the user called "distcc", or the user called

"nobody".

distccd does not have a configuration file; it's behaviour is con-

trolled only by command-line options and requests from clients.

SSTTAANNDDAALLOONNEE SSEERRVVEERR

The recommended method for running distccd is as a standalone server.

distccd will listen for network connections and fork several child pro-

cesses 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 sys-

tem, 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

RRUUNNNNIINNGG FFRROOMM IINNIITT

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 --nnoo-ddeettaacchh option should be used so that the super-server can mon-

itor 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

RRUUNNNNIINNGG FFRROOMM IINNEETTDD

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 dae-

mon. 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 pro-

tect 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. TTEERRMMIINNAATTIINNGG DDIISSTTCCCCDD 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. OOPPTTIIOONNSS

--hheellpp Display summary usage information.

--vveerrssiioonn

Shows the daemon version and exits.

-jj,, --jjoobbss JJOOBBSS

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.)

-NN,, --nniiccee NNIICCEENNEESSSS

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 nice-

ness is increased by 5.

-pp,, --ppoorrtt PPOORRTT

Set the TCP port to listen on, rather than the default of 3632. (Daemon mode only.)

--lliisstteenn AADDDDRREESSSS

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.)

-PP,, --ppiidd-ffiillee FFIILLEE

Save daemon process id to file FILE. (Daemon mode only.)

--uusseerr UUSSEERR

If distccd gets executed as root, change to user USER.

-aa,, --aallllooww IIPPAADDDDRR[[//MMAASSKK]]

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, all clients are allowed.

Unauthorized connections are rejected by closing the TCP connec-

tion immediately. A warning is logged on the server but nothing is sent ot the client.

--nnoo-ddeettaacchh

Do not detach from the shell that started the daemon.

--nnoo-ffoorrkk

Don't fork children for each connection, to allow attaching gdb. Don't use this if you don't understand it!

--lloogg-ffiillee FFIILLEE

Send messages to file FILE instead of syslog. Logging directly to a file is significantly faster than going via syslog and is recommended.

--lloogg-lleevveell LLEEVVEELL

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, warn-

ing, notice, info, or debug.

--lloogg-ssttddeerrrr

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.

--vveerrbboossee

Include debug messages in log. Equivalent to --lloogg-lleevveell==ddeebbuugg

--wwiizzaarrdd

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.

--iinneettdd

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.

--ddaaeemmoonn

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-inter-

active ssh connection.

--mmaaxx-ccaacchhee-aaggee HHOOUURRSS

Specifies the maximum time to keep a cached pch file. The value is computed based on the last file access, and is constrained to be at most 72 hours (the default).

--mmaaxx-ccaacchhee-ssiizzee MMBB

Specifies the maximum total disk use in Mb allowed for the pch cache. A value of zero (the default) allows the cache to grow without an explicit upper size limit.

--mmiinn-ddiisskk-ffrreeee MMBB

Specifies the minimum disk free space in Mb to preserve on the filesystem containing the pch cache. The default is 2048, and

the minimum is 512. --pprriioorriittyy PPRRIIOORRIITTYY Specifies an integer

priority for the build machine. Machines with higher priorities will be ordered towards the beginning of the DISTCCHOSTS list by Xcode. This setting is not used by distcc. SSEEAARRCCHH PPAATTHHSS 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 com-

piler name is not an absolute path, or if the client is used in mas-

querade 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 mas-

querade links, to guard against inadvertent recursion. The DDIISSTTCCCCDDPPAATTHH environment variable may be used to set the path.

The search path is logged when -verbose is given. In case of confu-

sion, check the logs.

When distccd is run over ssh, the $HOME/.ssh/environment file may be

useful in setting the path. See sssshh((11)).. 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 --lloogg-ffiillee ooppttiioonn..

ENVIRONMENT VARIABLES DDIISSTTCCCCDDPPAATTHH

When starting distccd, if this value is set it will be used

unaltered for the command-execution PATH. The code that nor-

mally tries to remove masquerade directories from the path is skipped. DDIISSTTCCCCSSAAVVEETTEEMMPPSS If set to 1, temporary files are not deleted after use. Note that DDIISSTTCCCCLLOOGG does not affect the log destination for the server. DDIISSTTCCCCTTCCPPDDEEFFEERRAACCCCEEPPTT On Linux, turn on the TCPDEFERACCEPT socket option. Defaults to on. TTMMPPDDIIRR Directory for temporary files such as preprocessor output. By default /tmp/ is used. PPCCHH CCAACCHHIINNGG

The Mac OS X version of distccd includes support for precompiled header

(pch) files. distccd caches these files in TMPDIR, and provides options

for managing the cache based on file access times and disk use. The pch files are downloaded from the client machines as needed and stored on a per user, per client machine basis. To minimize build times the pch cache should be sufficiently large. If there is insufficient space

then pch files may be repeatedly downloaded during a build. distccd

will emit a warning if it detects that the cache constraints require discarding recently downloaded pch files (possibly due to a full disk.)

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 ..ii files, it is not use-

ful to call it from distccd.

LLIICCEENNCCEE 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 , with the co-

operation of many scholars including Wayne Davison, Frerich Raabe, Dim-

itri Papadopoulos and others noted in the NEWS file. Please report bugs to .