    dccd(8)                 FreeBSD System Manager's Manual                dccd(8)

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

         Dccd receives reports of checksums related to mail received by DCC
         clients and queries about the total number of reports of particular
         checksums.  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 infor-
         mation that corresponds to the checksums it receives.  It only acts as a
         clearinghouse of total counts of checksums computed by clients.

         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 associ-
         ated with DCC server-IDs should be protected, because DCC servers listen
         to commands authenticated with server-IDs and their associated passwords.
         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.

         A /var/dcc/whitelist of known good (or bad) sources of email prevents le-
         gitimate 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 contain-
         ing checksums with total counts exceeding thresholds.  Changes in the
         flod file are noticed automatically within minutes.

         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 peri-
         odically.  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 set by changing
         the /var/dcc/dcc_conf control file.

         -d   enables debugging output.  Additional -d options increase the number
              of messages.

         -V   displays the version of the DCC server daemon.  Two or more -V op-
              tions 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.

         -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 ap-
              pears in the SMTP X-DCC headers generated by the DCC.

         -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 asser-
              tions 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 an 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 ad-
              dresses 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 sup-
              ported, separate UDP sockets are bound to each configured network
              interface so that each DCC clients receives replies from the IP ad-
              dresses 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 in-
              terfaces, 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 used the IP address of a single -a option, but only if there
              is 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 enve-
              lope sender, and SMTP envelope recipient.  If the SMTP client per-
              sists 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 remem-
              bered 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 retransmit-
              ting.  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 em-
              bargo, even if the body of the message differs.

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

              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.

              The target counts of embargoed messages are reported to the DCC net-
              work to improve the detection of bulk mail.

         -W [rate][,chg][,dbsize]
              controls quick database cleaning.  If the database is larger than
              dbsize in MBytes, the database has not recently been cleaned and is
              not about to be cleaned, and dccd is receiving fewer than rate re-
              quests per second, or if telling DCC clients that the database is
              about to be cleaned reduces the requests/second by chg, then dccd
              starts dbclean(8) for a quick database cleaning.  The cleaning is
              abandoned if it takes too long.

              The defaults are equivalent to -W 1.0,40.0,RSS where RSS is the max-
              imum dccd resident set size displayed in the system log when the
              database is opened.  A rate of -W 0.0 disables quick cleanings.

         -K [no-]type
              marks checksums of type (not) be kept or counted in the database
              (unless they appear in the /var/dcc/whitelist file).  Explicit set-
              tings add to or remove from the initial contents of the list, which
              is equivalent to -K Body -K Fuz1 -K Fuz2.

         -T [no-]tracemode
              causes the server to trace or record some operations.  tracemode
              must be one of the following:
                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 concerning the report-ID cache that is used
                        to detect 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.

         -u anon-delay[,inflate]
              changes the number of milliseconds anonymous or unauthenticated
              clients must wait for answers to their queries and reports.  The
              purpose of this delay is to discourage large anonymous clients.  The
              anon-delay is 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 only for checksum queries and reports but also cdcc(8) stats re-
              quests.  A missing value for inflate turns off inflation.

              The default value is 50, except when -G is used in which 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 becomes too full.  The default value is
              /usr/local/libexec/dcc/dbclean.  The value can include arguments as in -C
              '/usr/local/libexec/dcc/dbclean -F'.

              Dbclean should not be run by dccd except in emergencies such as
              database corruption or hash table overflow.  Dbclean(8) should be
              run daily with the /usr/local/libexec/dcc/cron-dccd cron script

         -L ltype,facility.level
              specifies how messages should be logged.  Ltype must be error, info,
              or off to indicate which of the two types of messages are being con-
              trolled or to turn off all syslog(3) messages from dccd.  Level must
              be a syslog(3) level among 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 ad-
              dress independently.

              RL_ANON limits the number of DCC transactions per second from anony-
              mous DCC clients.  This limit applies to each IP address indepen-
              dently.  It is better to use -u than to change this value to exclude
              anonymous clients.

              RL_ALL_ANON limits the number of DCC transactions per second from
              all anonymous DCC clients.  This limit applies to all anonymous
              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 as well as for each DCC
              client by IP address.

              The default is equivalent to -R 400,50,2000,0.1

## FILES

         <SPAN="FILE-/var/dcc">/var/dcc  is the DCC home directory containing data and control files.
         <SPAN="FILE-dcc_conf">dcc_conf  is the DCC control file.
         <SPAN="FILE-dcc_db">dcc_db    is the database of mail checksums.
         <SPAN="FILE-dcc_db.hash">dcc_db.hash is the mail checksum database hash table.
         <SPAN="FILE-grey_db">grey_db   is the database of greylist checksums.
         <SPAN="FILE-grey_db.hash">grey_db.hash is the greylist database hash table.
         <SPAN="FILE-flod">flod      contains lines controlling DCC flooding of the form:
                   host[,rport][;src[,lport]] rem-ID [passwd-ID [o-opt [i-opt]]]
                   where absent optional values are signaled with "-" and
                    host is the IP address or name of a DCC server and rport is
                        the name or number of the TCP port used by the remote
                        server.
                    src and lport are 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.  In-
                        coming flooding connections must arrive at an address and
                        port specified with -a.
                    rem-id is the server-ID of the remote DCC server.
                    passwd-ID is 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 re-
                        quired 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 are 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 ac-
                             cepted 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 is 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 is 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 proto-
                             col.
                         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 transla-
                             tion.  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 gener-
                             ated 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 re-
                             ports 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.
         <SPAN="FILE-grey_flod">grey_flod is the equivalent of the /var/dcc/flod file used by dccd when
                   it is a greylist server.
         <SPAN="FILE-flod.map">flod.map  is an automatically generated file in which dccd records its
                   progress sending or flooding reports to DCC peers.
         <SPAN="FILE-grey_flod.map">grey_flod.map is the equivalent of the /var/dcc/flod.map file used by
                   dccd when it is a greylist server.
         <SPAN="FILE-ids">ids       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]

                   where
                    id  is 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 di-
                        vided by the inflate value.  See -u.
                    pass1 is the password currently used by clients with identi-
                        fier id.  It is a 1 to 32 character string that does not
                        contain blank, tab, newline or carriage return characters.
                    pass2 is 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 not used except to
                   tell dccd that server-IDs in the flooded reports are valid.
                   The string unknown is equivalent to the null string.
         <SPAN="FILE-whitelist">whitelist contains the DCC server whitelist.  It is not used directly but
                   is loaded into the database when dbclean(8) is run.
         <SPAN="FILE-grey_whitelist">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.
         <SPAN="FILE-blacklist">blacklist if present, 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 automati-
                   cally 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.
         <SPAN="FILE-dccd_clients">dccd_clients contains client IP addresses and activity counts.
         <SPAN="FILE-grey_clients">grey_clients contains greylist client IP addresses and activity counts.

## EXAMPLES

         dccd is usually started with other system daemons with something like the
         <SPAN="FILE-script">script /usr/local/libexec/dcc/rcDCC.  That scripts uses values in
         <SPAN="FILE-/var/dcc/dcc_conf">/var/dcc/dcc_conf to start the server.  With the argument stop,
         /usr/local/libexec/dcc/rcDCC can be used to stop the daemon.

         <SPAN="FILE-The">The database grows too large unless old reports are removed.  dbclean(8)
         <SPAN="FILE-should">should be run daily with the /usr/local/libexec/dcc/cron-dccd cron(8) script

## SEE ALSO

         cdcc(8), dcc(8), dbclean(8), dblist(8), dccifd(8), dccm(8), dccproc(8).
         dccsight(8),

## HISTORY

         dccd is based on an idea from Paul Vixie.  It was designed and written at
         <SPAN="FILE-Rhyolite">Rhyolite Software, starting in 2000.  This document describes version
         <SPAN="FILE-RHYOLITE_VERSION.">RHYOLITE_VERSION.

                                    March 22, 2024