dccd(8)            DCC -- Distributed Checksum Clearinghouse           dccd(8)


NAME

     dccd - Distributed Checksum Clearinghouse Daemon


SYNOPSIS

     dccd [-VbQ] -i server-ID [-n brand] [-h homedir]
          [-a [server-addr][,server-port]] [-I host-ID] [-q qsize]
          [-G [embargo][,wait][,white]] [-t [type],threshold] [-K [no-]type]
          [-T tracemode] [-u anon-delay[,inflate]] [-C dbclean]
          [-L ltype,facility.level]
          [-R [RL_SUB],[RL_FREE],[RL_ALL_FREE],[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 or close cluster of DCC servers is identified by a numer-
     ic server-ID. Each DCC client is identified by a client-ID, either ex-
     plicitly listed in the ids file or the special anonymous client-ID.  Many
     computers are expected to share a single client-ID. A server-ID is less
     than 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 asso-
     ciated 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 comput-
     ers.  See the ids file.

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

     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 flod file, and send them reports containing check-
     sums 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 flod file entry changes their incoming flooded re-
     ports counts to "many."

     Dccd automatically checks its flod and ids files periodically.  Cdcc(8)
     has the server commands new ids and flood check to tell dccd to check
     those two files immediately.  Both files are also checked for changes in
     response to the SIGHUP signal.

   OPTIONS
     The following options are available:

     -V   displays the version of the DCC server daemon.

     -b   causes the server to not detach itself from the controlling tty or
          put itself into the background.

     -Q   causes the server to treat reports of checksums as queries except
          from DCC clients marked trusted in the 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, which is often /var/lib/dcc.

     -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 is to listen on all local IP addresses.
          It can be useful to list some or all of the IP addresses of multi-
          homed hosts to deal with local or remote 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 IN_ADDRANY 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.  Note that this means that -a -127.0.0.1 breaks
          flooding, often with "Invalid argument" messages.  See also the flod
          file.

     -I host-ID
          changes the server's globally unique identity from the default value
          consisting of the first 16 characters of the host name.  Host-ID is
          a string of up to 16 characters to be used instead of the first 16
          characters of the system's hostname.

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

     -t [type],threshold
          sets the threshold below which checksum reports are not sent or
          flooded to peer DCC servers.  Checksums whose total counts are less
          than to the number threshold are not sent.  If threshold is the
          string "many," a value of millions is understood.  If type is ab-
          sent, the threshold must be at least 10 and sets the thresholds for
          the body checksums.

          This threshold has no direct effect on which checksums are marked
          "bulk" by DCC clients.  Instead, it allows cooperating DCC servers
          to share only the checksums of bulk mail and significantly reduces
          inter-server communications.  The thresholds should be larger than
          the number of addressees of typical private email but not much larg-
          er, because reports of checksums that total less than their thresh-
          olds can be flooded as many extra times as there are other thresh-
          olds.  By default, the thresholds for the body checksums, Body,
          Fuz1, and Fuz2 are 20.  The thresholds for the other checksums are
          so high by default that by themselves they can never cause reports
          to be flooded.

          Reports containing any checksums marked "OK or "OK2" are not sent to
          other servers.  This reduces the bandwidth needed for the inter-
          server flooding, the sizes of DCC database files, and helps protect
          the privacy of email of clients of a DCC server.

     -G [embargo][,wait][,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 wait 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 remains famil-
          iar for white seconds.  The triple is forgotten if it is ever asso-
          ciated 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 de-
          fault is -G 270seconds,7days,63days. The embargo should be longer
          than open proxies can linger on your SMTP servers retransmitting and
          long enough to let DCC servers total target counts reported for em-
          bargoed messages.  The wait time should be as long as legitimate
          mail servers persist in retransmitting to recognize embargoed mes-
          sages 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.

          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
          grey_flod file.

          Clients of greylist servers cannot be anonymous and must have
          client-IDs and passwords assigned in the ids file.

          White- and blacklists are honored by the DCC clients.  White-listed
          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.

     -K [no-]type
          marks checksums of type (not) be "kept" or counted in the database
          unless they appear in the whitelist.  The default is equivalent to
          -K no-all -K Body -K Fuz1 -K Fuz2 to count only the body checksums.

     -T tracemode
          causes the server to trace or record some operations.  tracemode
          must be one of the following:
            ALL    all tracing
            ADMN   administrative requests from the control program.  See cd-
                   cc(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
            FLOOD  messages about inter-server flooding
            IDS    unknown server-IDs in flooded reports
            BL     requests from clients with IP addresses in the blacklist
                   file.
          The default is ANON CLNT.

     -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 anonymous clients..  The de-
          lay is multiplied by 1 plus the number of recent anonymous requests
          from an IP address 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,none, 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
          libexec/dbclean in the DCC home directory.

     -L ltype,facility.level
          specifies how messages should be logged.  Ltype must be error or
          info to indicate which of the two types of messages are being con-
          trolled.  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_FREE],[RL_ALL_FREE],[RL_BUGS]
          sets the four categories of 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.  Its default value is set by the compile-time
          value of DCCD_RL_SUB, which is 150 by default.


          RL_FREE limits the number of DCC transactions per second from anony-
          mous DCC clients.  Its default value is set by the compile-time val-
          ue of DCCD_RL_FREE, which is 20 by default.  This limit applies to
          each IP address independently.  It is better to use -u than to
          change this value to exclude anonymous clients.

          RL_ALL_FREE limits the number of DCC transactions per second from
          all anonymous DCC clients.  Its default value is set by the compile-
          time value of DCCD_RL_ALL_FREE, which is 150 by default 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.  Its default value is set by the compile-time
          value of DCCD_RL_BUGS, which is 2 by default.


FILES

     /var/lib/dcc is the DCC home directory containing data and control files.
     dcc_db    is the database of mail checksums.
     dcc_db.hash is the mail checksum database hash table.
     grey_db   is the database of greylist checksums.
     grey_db.hash is the greylist database hash table.
     flod      contains lines controlling DCC flooding of the form:
                 host[,port][;src] rem-ID [passwd-ID [o-opts [i-opts]]]
               where absent optional values are signaled with "-" and
                host is the IP address or name of a DCC server.
                port is the name or number of the UDP port used by the server.
                src is the IP address or host name from which the outgoing
                    connection should come.
                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-opts and o-opts are comma-separated lists of
                     off turns off flooding to the remote or local system.
                     traps indicates that the remote sending or local receiv-
                         ing system has only "spam traps."
                     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 not sent to remote servers and
                         refused in incoming floods.
                     del says delete requests are accepted by the remote or
                         local server.
                     no-log-del turns off logging of incoming delete requests
                         to delete checksums.
                     passive is used to tell a server outside a firewall to
                         expect a peer inside and using the SOCKS protocol to
                         create both of the pair of input and output TCP con-
                         nections used for flooding.  The peer inside the
                         firewall should use SOCKS 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.
                     ID1->ID2 converts server-ID ID1 in flooded reports to
                         server-ID ID2. Either ID1 or ID2 may be the string
                         `self' to specify the server's own ID.  ID1 can be
                         the string `all' to specify all server-IDs or a pair
                         of server-IDs separated by a dash to specify an in-
                         clusive range.  ID2 can be the string `ok' to send or
                         receive reports without translation or the string
                         `reject' to not send outgoing or refuse incoming re-
                         ports.  Only the first matching conversion is ap-
                         plied.  For example, when `self->ok,all->reject' is
                         applied to a locally generated report, the first con-
                         version is applied and the second is ignored.
                     leaf=path-len does not send reports with paths longer
                         than path-len server-IDs.
                     vers specifies the version of the DCC flooding protocol
                         used by the remote DCC server with a string such as
                         `version2'.

     grey_flod is the equivalent of flod used by dccd when it is a greylist
               server.

     flod.map is an automatically generated file in which dccd records its
               progress sending or flooding reports to DCC peers.

     grey_flod.map is the equivalent of flod.map 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.  It contains
               blank lines, comments starting with "#" and lines of the form:
                     id[,rpt-ok] passwd1 [passwd2]
               where
               id is a DCC client-ID or server-ID.
               Rpt-ok if present overrides the -Q argument by saying that this
                   particular client is trusted to report only checksums for
                   unsolicited bulk mail.
               passwd1 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.
               passwd2 is the optional next password that those clients will
                   use.  A DCC server accepts either password if both are pre-
                   sent 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.

     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 DCC clients that are ignored.  Each line in the file
               should be blank, a comment starting with '#', an IP address, or
               a block of IP addresses in the xxx.xxx.xxx.xxx/yy form.
               Changes to the file are automatically noticed and acted upon
               within a few minutes.  Addresses can be followed with comments
               starting with '#'.  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 misc/start-dccd.  It uses values in the file dcc_conf in the DCC
     home directory to start the server.

     The following is useful for cleanly stopping the daemon:


           cdcc 'id 100; stop'

     Again, the ID of the local server must be used instead of "100."

     Unless old reports are removed from the database, it grows too large.
     dbclean(8) should be run daily with script like /var/lib/dcc/libexec/cron-dc-
     cd.


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
     Rhyolite Software starting in 2000.  This document describes version
     1.2.16.


                               November 19, 2003                             7

Man(1) output converted with man2html modified for the DCC $Date 2001/04/29 03:22:18 $