distccd(1)

💖 distccd(1) — General Commands Manual 💖

okay so bestie, welcome to the distccd page, the compiler server that carries the whole distributed-compile friend group on its back. grab a snack, this one's a whole journey ✨

---

✨ NAME ✨

distccd — the distributed C/C++ compiler server, aka the server-side main character 🎀

---

🌸 SYNOPSIS 🌸

distccd --daemon [OPTIONS]

---

🦋 DESCRIPTION 🦋

distccd is the server for the distcc(1) distributed compiler. It's the one that accepts and runs compilation jobs for network clients. literally the workhorse. 💅

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. pick your fighter, no cap.

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. and honestly? SSH connections have several advantages, bestie:

• 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
• 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". it's giving humble. it's giving "I don't need the power actually" 👑

distccd does not have a configuration file; it's behaviour is controlled only by command-line options and requests from clients. no config file, we die like real ones 🫶

---

🌈 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. so many little babies. so organized. 💖

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. it's giving helicopter parent but make it sysadmin energy 🌸

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. don't ghost your super-server, that's rude.

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. very "we'll call you, don't call us" of them 💅

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. so like. check your settings, bestie.

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. glow up. 🔥

---

💀 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. graceful exit, we love to see it 🫶

---

✨ OPTIONS ✨

• --help — Display summary usage information. the "what am I even doing here" button 🥺
• --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.) bestie the default is a vibe, not a guarantee 💅
• -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. be polite. share the CPU. 🎀
• -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! like, immediately 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. silent treatment, but make it security.
• --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 timer, no limits, no thoughts head empty 🙈
• --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! for real, this is not a "eh, I'll figure it out" option 💀
• --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. 🧙‍♀️ you either have the robe or you don't
• --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. say it with your chest, bestie 💅
• --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). like, dangerous dangerous. do not casually enable this one, I'm begging 🫶
• --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. the logs are your bestie, they would never lie to you 💖

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 🌸

Okay bestie, here's where distccd gets its whole vibe from the environment. Read these carefully, they lowkey change everything 💅

• DISTCC_CMDLIST — if this one's set, distccd loads a list of supported commands from the file it names, and then it will refuse to serve any command whose last DISTCC_CMDLIST_MATCHWORDS last words don't match the words of a command in that list. (Yes, the original page says DISTCC_CMDLIST_MATCHWORDS right there while the variable below is called DISTCC_CMDLIST_NUMWORDS — that's just how the page is written, don't come for me 🙈.) For the full lore, go read the comments in src/serve.c.
• DISTCC_CMDLIST_NUMWORDS — how many words, counted from the end of the command, you're matching. Default is 1.
• DISTCCD_PATH — when distccd starts up, if this is set it gets used unaltered as the command-execution PATH. Like, the code that would normally try to strip masquerade directories out of the path? Yeah, it gets skipped entirely. No cap.
• DISTCC_SAVE_TEMPS — set it to 1 and temporary files are not deleted after use. Keep your lil leftovers, queen 🎀
• DISTCC_TCP_DEFER_ACCEPT — on Linux, turns on the TCP_DEFER_ACCEPT socket option. Defaults to on.

Heads up bestie: DISTCC_LOG does not affect the log destination for the server. Just so we're clear ✨

• TMPDIR — the directory for temporary files like preprocessor output. By default it's /tmp/. Periodt.
• DISTCCD_PRINCIPAL — if set, this names the principal that distccd runs under, and it's used to authenticate with the client. Only used if distccd was compiled with the --with-auth configure option and distccd is run with the --auth option. Both, or it does nothing, iykyk.

---

🦋 SEE ALSO 🦋

Go give these icons a read, fr fr:

• distcc(1)
• pump(1)
• include_server(1)
• gcc(1)
• make(1)
• ccache(1)
• http://code.google.com/p/distcc/

---

💀 BUGS 💀

Okay, real talk, the scary parts. Not me being dramatic, this is genuinely in the page:

• IP-based access control is not secure against attackers who can spoof TCP connections — and it can't tell different users on a client apart. At all.
• TCP connections are not secure against attackers who can observe or modify network traffic. Like, if they can watch or mess with it, you're cooked 😭
• Because ccache does not cache compilation from .i files, calling it from distccd is not useful. Save yourself the trouble bestie.

---

👑 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. (That's spelled warrany in the source, and I'm keeping it exactly, character for character — iconic typo behavior, we stan 🫶.) 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 pump(1) for the authors of pump mode. Please report bugs to <distcc@lists.samba.org>. 🐛

---

And that's the whole page, bestie — this lil masterpiece is dated 9 June 2008 and it's the distccd(1) manual page, brought to you by the distcc crew. Go compile something gorgeous 💅🌈⭐