dccd(8)

📦 version 2.3.169, in alpine 3.24

🦋 dccd(8) — System Manager's Manual 🦋

💖 NAME 💖

dccd — Distributed Checksum Clearinghouse Daemon

✨ SYNOPSIS ✨

dccd [-dVbfFQ] -i server-ID [-n brand] [-h homedir] -I [host-ID][,user]
     [-a [server-addr][,server-port]] [-q qsize]
     [-G [on,][weak-body,][weak-IP,][embargo][,window][,white]]
     [-W [rate][,chg][,dbsize]] [-K [no-]type] [-T [no-]tracemode]
     [-u anon-delay[,inflate]] [-C dbclean] [-L ltype,facility.level]
     [-R [RL_SUB],[RL_ANON],[RL_ALL_ANON],[RL_BUGS]]

🌸 DESCRIPTION 🌸

okay so bestie, the whole vibe of dccd is that it receives reports of checksums related to mail received by DCC clients, plus queries about the total number of reports of particular checksums. And the iconic privacy detail is: a DCC server never receives mail, address, headers, or other information from clients, but only cryptographically secure checksums of such information. A DCC server cannot determine the text or other information that corresponds to the checksums it receives. It only acts as a clearinghouse of total counts of checksums computed by clients. periodt 💅

Each DCC server is identified by a numeric server-ID. Each DCC client is identified by a client-ID, either explicitly listed in the /var/dcc/ids file or the special anonymous client-ID. Many computers are expected to share a single client-ID. A server-ID is between 100 and 32768 while a client-ID is between 32768 and 16777215. DCC server-IDs need be known only to DCC servers and the people running them. The passwords associated with DCC server-IDs should be protected, because DCC servers listen to commands authenticated with server-IDs and their associated passwords. Protect those passwords, no cap. Each client that does not use the anonymous ID must know the client-ID and password used by each of its servers. A single client computer can use different passwords with different server computers. See the /var/dcc/ids file. iykyk 🔥

A /var/dcc/whitelist of known good (or bad) sources of email prevents legitimate mailing lists from being seen as unsolicited bulk email by DCC clients. The whitelist used by a DCC server is built into the database when old entries are removed by dbclean(8). Each DCC client has its own, local whitelist, and in general, whitelists work better in DCC clients than servers.

A dccd /var/dcc/whitelist file containing IP addresses that should be in client whiteclnt files is useful. When -T WLIST tracing is enabled (as it is by default), dccd complains to the system log when an authenticated client reports mail from IP addresses listed as OK, MX, or MXDCC. It is often useful to have a /var/dcc/whitecommon file containing whitelisted IP addresses. 🎀

The effectiveness of a Distributed Checksum Clearinghouse increases as the number of subscribers increases. Flooding reports of checksums among DCC servers increases the effective number of subscribers to each server. Each dccd daemon tries to maintain TCP/IP connections to the other servers listed in the /var/dcc/flod file, and send them reports containing checksums with total counts exceeding thresholds. Changes in the flod file are noticed automatically within minutes. the way that just quietly updates? obsessed. ⭐

Controls on report flooding are specified in the flod file. Each line specifies a hostname and port number to which reports should be flooded, a server-ID to identify and authenticate the output stream, a server-ID to identify and authenticate an input stream from the same server, and flags with each ID. The ability to delete reports of checksums is handy, but could be abused. If del is not present among the in-opts options for the incoming ID, incoming delete requests are logged and then ignored. Floods from DCC "brands" that count only mail to spam traps and whose servers use the -Q option to count extremely bulk mail should be marked with traps. They can be seen as counting millions of targets, so the traps flag on their /var/dcc/flod file entry changes their incoming flooded reports counts to many. 💀

dccd automatically checks its /var/dcc/flod and /var/dcc/ids files periodically. Cdcc(8) has the commands new ids and flood check to tell dccd to check those two files immediately. Both files are also checked for changes after the SIGHUP signal. 🫶

💅 OPTIONS 💅

The following options are available. Most of them should be set by changing the /var/dcc/dcc_conf control file.

  • -d — enables debugging output. Additional -d options increase the number of messages. lowkey chatty, highkey useful. 😭
  • -V — displays the version of the DCC server daemon. Two or more -V options show the options with which it was built. ✨
  • -b — causes the server to not detach itself from the controlling tty or put itself into the background. it's giving "stay right here with me" energy.
  • -F — uses write() instead of mmap() and msync() in some cases to modify the DCC database. It is the default on Solaris except when the database is in a memory mapped file system. See -f.
  • -f — uses mmap() and msync() to modify the DCC database. See -F.
  • -Q — causes the server to treat reports of checksums as queries except from DCC clients marked trusted in the /var/dcc/ids file with rpt-ok. See -u to turn off access by anonymous or unauthenticated clients. 👑
  • -i server-ID — specifies the ID of this DCC server. Each server identifies itself as responsible for checksums that it forwards to other servers.
  • -n brand — is an arbitrary string of letters and numbers that identifies the organization running the DCC server. The brand is required, and appears in the SMTP X-DCC headers generated by the DCC. required means required, bestie. 🎀
  • -h homedir — overrides the default DCC home directory, /var/dcc.
  • -I [host-ID][,user] — sets the UID and GID of the process or the server's name for assertions of its -i server-ID flooded to peers. The default name is the first 16 characters of the host name. If present, user must be a valid user name. 🦋
  • -a [server-addr][,server-port] — adds a hostname or IP address to the list of local IP addresses that the server answers. Multiple -a options can be used to specify a subset of the available network interfaces or to use more than one port number. The default without any -a options is to listen on all local IP addresses. It can be useful to list some of the IP addresses of multi-homed hosts to deal with firewalls. By default server-port is 6277 for DCC servers and 6276 for greylist servers. It is the UDP port at which DCC requests are received and the TCP port for incoming floods of reports.

If server-addr is absent and if the getifaddrs(8) function is supported, separate UDP sockets are bound to each configured network interface so that each DCC clients receives replies from the IP addresses to which corresponding request are sent. If dccd is started before all network interfaces are turned on or there are interfaces that are turned on and off or change their addresses such as PPP interfaces, then the special string @ should be used to tell dccd to bind to an INADDR_ANY UDP socket.

Outgoing TCP connections to flood checksum reports to other DCC servers use the IP address of a single -a option, but only if there is a single option that is not localhost. See also the /var/dcc/flod file. 🌈

  • -q qsize — specifies the maximum size of the queue of requests from anonymous or unauthenticated clients. The default value is the maximum DCC RTT in seconds times 200 or 1000.
  • -G [on,][weak-body,][weak-IP,][embargo][,window][,white] — changes dccd to a greylist server for dccm(8) or dccifd(8). Greylisting consists of temporarily rejecting or embargoing mail from unfamiliar combinations of SMTP client IP address, SMTP envelope sender, and SMTP envelope recipient. If the SMTP client persists for embargo seconds and so is probably not an open proxy, worm-infected personal computer, or other transient source of spam, the triple of (IP address,sender,recipient) is added to a database similar to the usual DCC database. If the SMTP client does not try again after embargo seconds and before window seconds after the first attempt, the triple is forgotten. If the SMTP client persists past the embargo, the triple is added to the database and becomes familiar and the message is accepted. Familiar triples are remembered for white seconds after the last accepted mail message. The triple is forgotten if it is ever associated with unsolicited bulk email.

All three durations can be a number of minutes, hours, days, or weeks followed by MINUTES, M, HOURS, H, DAYS, D, WEEKS or W. The default is -G 270seconds,7days,63days. The first duration or the embargo should be longer than open proxies can linger retransmitting. The second window time should be as long as legitimate mail servers persist in retransmitting to recognize embargoed messages whose retransmissions were not received because of network or other problems. The white time should be long enough to recognize and not embargo messages from regular senders.

Usually the DCC greylist system requires that an almost identical copy of the message be retransmitted during the embargo. If weak-body is present, any message with the same triple of sender IP address, sender mail address, and target mail address ends the embargo, even if the body of the message differs.

If weak-IP is present, all mail from an SMTP client at an IP address is accepted after any message from the same IP address has been accepted.

Unlike DCC checksums, the contents of greylist databases are private and do not benefit from broad sharing. However, large installations can use more — two or more — greylist servers flooding triples among themselves. Flooding among greylist servers is controlled by the /var/dcc/grey_flod file.

All greylist cooperating or flooding greylist servers must use the same -G values.

Clients of greylist servers cannot be anonymous and must have client-IDs and passwords assigned in the /var/dcc/ids file. This implies that cdcc commands directed to greylist servers must specify the server-ID.

White- and blacklists are honored by the DCC clients. whitelisted messages are embargoed or checked with a greylist server. The greylist triples of blacklisted messages, messages whose DCC counts make them spam, and other messages known to be spam are sent to a greylist server to be removed from the greylist database and cause an embargo on the next messages with those triples.

Messages whose checksums match greylist server whitelists are not embargoed and the checksums of their triples are not added to the greylist database. 💜

…and heads up, bestie — the target counts of embargoed messages get reported to the DCC network, all so bulk mail detection gets better at its job. 💅

  • -W [rate][,chg][,dbsize] — the quick database cleaning knob ✨ Here's the whole vibe: dccd kicks off dbclean(8) for a quick clean only if all of this lines up — the database is bigger than dbsize in MBytes, the database hasn't been cleaned recently and isn't about to be, and dccd is pulling fewer than rate requests per second, or telling DCC clients that the database is about to be cleaned drops the requests/second by chg. And the cleaning gets abandoned if it takes too long, no cap. 🫶
    • The defaults are equivalent to -W 1.0,40.0,RSS, where RSS is the max dccd resident set size shown in the system log right when the database gets opened.
    • A rate of -W 0.0 disables quick cleanings entirely. Poof, gone. 💀
  • -K [no-]type — marks checksums of type to be kept or counted in the database (or not kept/counted, when you slap a no- on it) — unless they show up in the /var/dcc/whitelist file, which overrides all of that. Explicit settings add to or remove from the initial contents of that list, and the starting set is equivalent to -K Body -K Fuz1 -K Fuz2. 🎀
  • -T [no-]tracemode — makes the server trace or record some operations. tracemode must be one of these, no improvising:
    • ADMN — administrative requests from the control program, cdcc(8)
    • ANON — errors by anonymous clients
    • CLNT — errors by authenticated clients
    • RLIM — rate-limited messages
    • QUERY — all queries and reports
    • RIDC — some messages about the report-ID cache, the one used to spot duplicate reports from clients
    • FLOOD1 — messages about inter-server flooding connections
    • FLOOD2 — messages about flooded reports
    • BL — requests from clients in the /var/dcc/blacklist file
    • DB — odd database events, including long chains of duplicate checksums 👀
    • WLIST — reports of whitelisted checksums from authenticated (not anonymous) DCC clients
    • The default is ANON CLNT WLIST — except for a greylist server, which uses ANON CLNT WLIST IDS instead. Slay. ✨
  • -u anon-delay[,inflate] — changes how many milliseconds anonymous or unauthenticated clients have to wait for answers to their queries and reports. The whole point of this delay? Discouraging big anonymous clients, periodt. 🚫 The anon-delay gets multiplied by 1 plus the number of recent anonymous requests from IPv4 addresses in a /24 block or IPv6 addresses in a /56 block, divided by the inflate value.
    • The string FOREVER turns off all anonymous or unauthenticated access — not just checksum queries and reports, but cdcc(8) stats requests too. Full lockout, iconic behaviour.
    • If you leave out a value for inflate, inflation is off.
    • Default is 50 — except when -G is used, and in that case FOREVER is assumed and required. 😭
  • -C dbclean — changes the default name or path of the program used to rebuild the hash table when it gets too full. Default is /usr/libexec/dbclean. The value can totally include arguments, like -C '/usr/libexec/dbclean -F'. 💖
Ngl, dbclean should not be run by dccd except in emergencies — think database corruption or hash table overflow. Dbclean(8) should be run daily with the /usr/libexec/cron-dccd cron script instead. 🚨
  • -L ltype,facility.level — specifies how messages get logged. ltype must be error, info, or off — those pick which of the two types of messages you're controlling, or turn off all syslog(3) messages from dccd completely. level must be a syslog(3) level, one of EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG. facility must be among AUTH, AUTHPRIV, CRON, DAEMON, FTP, KERN, LPR, MAIL, NEWS, USER, UUCP, and LOCAL0 through LOCAL7. 🌈
    • The default is equivalent to:
-L info,MAIL.NOTICE -L error,MAIL.ERR
  • -R [RL_SUB],[RL_ANON],[RL_ALL_ANON],[RL_BUGS] — sets one or more of the four rate-limits. 🕐
    • RL_SUB limits the number of DCC transactions per second from subscribers, or DCC clients with known client-IDs and passwords. This limit applies to each IP address independently.
    • RL_ANON limits the number of DCC transactions per second from anonymous DCC clients. Also applies to each IP address independently. Fr fr, it's better to use -u than to change this value just to exclude anonymous clients. 🫶
    • RL_ALL_ANON limits the number of DCC transactions per second from all anonymous DCC clients — as a group, regardless of their IP addresses.
    • RL_BUGS limits the number of complaints or error messages per second for all anonymous DCC clients as a group, plus for each DCC client by IP address.
    • The default is equivalent to -R 400,50,2000,0.1. 👑

🗂️ FILES 💖

okay bestie, here's the whole file cast of dccd — every single one is doing a job, and we are not skipping any of them ✨

  • /var/dcc — the DCC home directory containing data and control files. it's giving main character's apartment.
  • dcc_conf — the DCC control file.
  • dcc_db — the database of mail checksums.
  • dcc_db.hash — the mail checksum database hash table.
  • grey_db — the database of greylist checksums.
  • grey_db.hash — the greylist database hash table.
  • flod — contains lines controlling DCC flooding. we're unpacking this below, don't worry.
  • grey_flod — the equivalent of the /var/dcc/flod file used by dccd when it is a greylist server.
  • flod.map — an automatically generated file in which dccd records its progress sending or flooding reports to DCC peers.
  • grey_flod.map — the equivalent of the /var/dcc/flod.map file used by dccd when it is a greylist server.
  • ids — contains the IDs and passwords known by the DCC server. An ids file that can be read by others cannot be used. periodt, security bestie.
  • whitelist — contains the DCC server whitelist. It is not used directly but is loaded into the database when dbclean(8) is run.
  • grey_whitelist — contains the greylist server whitelist. It is not used directly but is loaded into the database when dbclean(8) is run with -G.
  • blacklist — if present, contains a list of IP addresses and blocks of IP addresses of DCC clients and flooding peers that are ignored. more below.
  • dccd_clients — contains client IP addresses and activity counts.
  • grey_clients — contains greylist client IP addresses and activity counts.

🌊 flod details (and its greylist twin)

The flod file contains lines controlling DCC flooding, and the line format is:

host[,rport][;src[,lport]] rem-ID [passwd-ID [o-opt [i-opt]]]

Absent optional values are signaled with -, and here's the whole breakdown:

  • host — the IP address or name of a DCC server.
  • rport — the name or number of the TCP port used by the remote server.
  • src and lport — the source IP address or host name and TCP port from which the outgoing flooding connection should come. The string * specifies any source IP address. Incoming flooding connections must arrive at an address and port specified with -a.
  • rem-id — the server-ID of the remote DCC server.
  • passwd-ID — a server-ID that is not assigned to a server, but whose first password is used to sign checksum reports sent to the remote system. Either of its passwords are required with incoming reports. If it is absent or -, outgoing floods are signed with the first password of the local server in the ids file and incoming floods must be signed with either password of the remote server-ID.
  • i-opt and o-opt — comma separated lists of:
    • off — turns off flooding to the remote or local system.
    • no-del — says checksum delete requests are refused by the remote or local server and so turns off sending or accepting delete requests, respectively. By default, delete requests are sent to remote servers and accepted in incoming floods if and only if the peers are exchanging DCC reputations.
    • del — says delete requests are accepted by the remote or local server.
    • no-log-del — turns off logging of incoming requests to delete checksums.
    • passive — used to tell a server outside a firewall to expect a peer inside to create both of the pair of input and output TCP connections used for flooding. The peer inside the firewall should use SOCKS or NAT on its flod file entry for this system.
    • SOCKS — used to tell a server inside a firewall that it should create both of the TCP connections used for flooding and that SOCKS protocol should be used. The peer outside the firewall should use passive on its flod file entry for this system.
    • NAT — differs from SOCKS only by not using the SOCKS protocol.
    • IDS->result — converts server-IDs in flooded reports. IDS may be the string self to specify the server's own ID. IDS can instead be the string all to specify all server-IDs or a pair of server-IDs separated by a dash to specify an inclusive range. result can be the string self to translate to the server's own ID. ok sends or receives reports without translation. The string reject to not send outgoing or refuse incoming reports. Only the first matching conversion is applied. For example, when self->ok,all->reject is applied to a locally generated report, the first conversion is made and the second is ignored.
    • leaf=path-len — does not send reports with paths longer than path-len server-IDs. A path-len of 0 blocks reports from this server.
    • IPv4 — requires only IPv4 addresses to connect to this flooding peer.
    • IPv6 — requires only IPv6 addresses to connect to this flooding peer.
    • vers — specifies the version of the DCC flooding protocol used by the remote DCC server with a string such as version2.
    • trace1 — sends information about a single peer like the cdcc(8) command trace FLOOD1 on does for all peers.
    • trace2 — sends information about individual flooded reports like the cdcc(8) command trace FLOOD2 on does for all peers.

🆔 ids details

The ids file contains the IDs and passwords known by the DCC server. An ids file that can be read by others cannot be used. It contains blank lines, comments starting with #, and lines of the form:

id[,rpt-ok][,no-reps][,trace][,delay=ms[*inflate]] pass1
[pass2]

Here's what all that means:

  • id — a DCC client-ID or server-ID.
  • trace — logs activity from clients and flooding peers using the ID.
  • rpt-ok — overrides -Q by saying that this client is trusted to report only checksums for unsolicited bulk mail.
  • no-reps — disables DCC Reputation reports from and responses to clients using this ID.
  • delay=ms[*inflate] — delays answers to systems using the client id. The delay in milliseconds is multiplied by 1 plus the number of recent requests from an IP address using id divided by the inflate value. See -u.
  • pass1 — the password currently used by clients with identifier id. It is a 1 to 32 character string that does not contain blank, tab, newline or carriage return characters.
  • pass2 — the optional next password that those clients will use. A DCC server accepts either password if both are present in the file.

Both passwords can be absent if the entry is not used except to tell dccd that server-IDs in the flooded reports are valid. The string unknown is equivalent to the null string.

🚫 blacklist details

If present, blacklist contains a list of IP addresses and blocks of IP addresses of DCC clients and flooding peers that are ignored. Each line in the file should be blank, a comment starting with #, or an IP address or block of IP addresses in the form:

[trace,][ok,][bad,][no-anon][flood-ok] address

Addresses are single IPv4 or IPv6 addresses, CIDR blocks in the usual form, or a pair of addresses separated by a hyphen (-) specifying an inclusive range. The last line in the file that cover an address applies. Changes to the file are automatically noticed within a few minutes. An IP address is assigned all of the flags from all of lines that apply to it.

Addresses or blocks of addresses can be preceded with ok to "punch holes" in blacklisted blocks or specify tracing without blacklisting. trace logs activity. no-anon blacklists clients only when they use the anonymous client-ID. flood-ok says that DCC flood peering is allowed. bad is assumed when only an address is present. This mechanism is intended for no more than a few dozen blocks of addresses.

🧪 EXAMPLES ✨

dccd is usually started with other system daemons with something like the script /usr/libexec/rcDCC. That script uses values in /var/dcc/dcc_conf to start the server. With the argument stop, /usr/libexec/rcDCC can be used to stop the daemon.

The database grows too large unless old reports are removed. dbclean(8) should be run daily with the /usr/libexec/cron-dccd cron(8) script.

👀 SEE ALSO 🫶

📜 HISTORY 💜

dccd is based on an idea from Paul Vixie. It was designed and written at Rhyolite Software, starting in 2000. This document describes version RHYOLITE_VERSION.

xoxo, your dccd(8) bestie 💖 — this page is serving version RHYOLITE_VERSION, dated March 22, 2024. periodt. 🎀

📦 where this page comes from