
             Distributed Checksum Clearinghouse (DCC) Installation


    1. Fetch the source The DCC is available in three successively larger
       packages:

        dcc-dccproc.tar.Z
                is the smallest tarball. It contains the DCC procmail and
                non-sendmail interfaces, dccproc and dccifd. This
                package also contains utilities such as cdcc and all
                of the manual pages and documentation.

        dcc-dccm.tar.Z
                adds the sendmail DCC interface, dccm, to mark or
                filter mail with sendmail.

        dcc-dccd.tar.Z
                adds the DCC server, dccd.


    2. Read the documentation
       The DCC and other man pages describe the features, operating
       modes, required data files, and other characteristics of the DCC.
       Also see the DCC FAQ or list of frequently answered questions.

    3. Build sendmail If the DCC-sendmail interface, dccm, is not
       used, then skip to the next step.
       Sendmail must have the Mail Filter API or Milter enabled. Some
       systems such a FreeBSD 4.6 and newer are shipped with Milter
       enabled and the library installed by default. If your system comes
       with the Milter interface turn on, then skip to the next step.
       Otherwise, the Milter interface must be explicitly enabled by
       adding lines like those in misc/site.config.m4 to your
       sendmail/devtools/Site/site.config.m4 file or equivalent. Then
       build sendmail as described in the INSTALL file distributed with
       sendmail. You must build libmilter separately by something like
            cd libmilter
            sh ./Build
       After sendmail has been rebuilt if necessary it will need to be
       restarted. That should be done at the end of the next step.

    4. Configure, build, and install the DCC programs
       See the installation considerations in the DCC man page.
       Most DCC files are in a "home directory" such as /var/dcc. DCC
       programs such as cdcc and dccproc are run by end users and should
       be installed in a directory such as /usr/local/bin. They must also
       be set-UID to the UID that can change the DCC data files. DCC
       programs that do not need to be run by end users are installed by
       default in the libexec subdirectory of the DCC home directory. See
       the table of configure script and makefile parameters. Omit
       any parameters you don't need change and usually use:
        ./configure
        make install
       End users installing only dccproc can install it in their
       private "~/bin" directories and use private directories for their
       DCC home directories. In this case, the DCC programs that would
       otherwise need to be set-UID need not be.
       To build dccproc for an individual user, use something like
        ./configure --disable-sys-inst  --disable-server --disable-
dccm --disable-dccifd
                --homedir=$HOME/dccdir  --bindir=$HOME/bin
        make install
       The sendmail interface, dccm, must be built with the sendmail
       source and object tree. By default, the makefiles look for a
       native sendmail libraries (e.g. on FreeBSD 4.6), an installed
       "package" (e.g. on FreeBSD), or a directory named sendmail
       parallel to the DCC source and object tree. Those who regularly
       build new versions of sendmail may find it convenient to make a
       symbolic link there to their current sendmail. Otherwise configure
       the dccm makefile with
        ./configure --with-sendmail=/some/where/sendmail
        make install
       If dccm does not build because it cannot find libmilter, check
       that libmilter was compiled with sendmail in the previous
       step.
       To connect the sendmail Milter interface to dccm, copy or
       "sym-link" misc/dcc.m4 and misc/dccdnsbl.m4 to your
       sendmail/cf/feature directory and add FEATURE(dcc) lines to your
       sendmail.mc configuration file. Then rebuild and reinstall your
       sendmail.cf file, and restart sendmail.

    5. Create client configuration files All DCC configuration files are
       in the DCC home directory, usually /var/dcc. See the dcc,
       dccm, dccifd, and dccproc man pages for the files each
       needs. Example files are in homedir.
          + Unless run anonymously, DCC clients need client-ID numbers
            and passwords assigned by the operators of the chosen DCC
            servers in the /var/dcc/map file. The homedir/ids file
            can be a start.
          + Even if run anonymously, the /var/dcc/map file must contain
            the IP addresses of DCC servers. The installation process
            generates a serviceable /var/dcc/map file from the included
            homedir/map.txt.
          + Sources of legitimate bulk mail should be recorded in white
            lists. Example client, server, and common white
            lists are among the other sample configuration files. The
            format of DCC white lists is described in the DCC man
            page.
          + Put suitable values in the DCC configuration file,
            dcc_conf for dccm or dccifd. The default client values
            are usually good for a start and often only DCCM_REJECT_AT
            needs to be changed when it is time to reject spam.
          + Start dccm or dccifd before sendmail or the other MTA with
            the sample rc script /var/dcc/libexec/rcDCC.
          + Install a cron job like /var/dcc/libexec//cron-dccd to
            prune dccm, dccifd, and dccproc log files.

    6. Create server files and start server Skip this and the next
       step if only remote DCC servers will be used.
       It is best to use remote servers until the DCC client, dccm or
       dccproc, is stable. Then
          + Put suitable values for dccd in the configuration file,
            dcc_conf, in the home directory. Only SRVR_ID and BRAND
            are commonly changed. Every DCC server in a network of
            servers requires a unique server-ID. Negotiate a unique
            server-ID with whomever is keeping track of them in the
            network you'll join.
          + Choose a secret password for your server-ID in your
            /var/dcc/ids file. This password can be used to control
            your server remotely.
          + Start the server with the system by installing
            /var/dcc/libexec/rcDCC or an equivalent. If it is used
            unchanged, rcDCC is best installed with a symbolic link to
            automate installing updates.
          + A script like /var/dcc/libexec/cron-dccd should be used
            to run dbclean about once a day. An entry like
            misc/crontab can be put into the crontab file for the
            user that runs dccd on some systems. If you have more than
            one DCC server, stagger the times at which the cron job is
            run so that not all of your servers are simultaneously busy
            cleaning databases.
          + Install a shutdown script such as /var/dcc/libexec/rcDCC
            to shut down the DCC server as the operating system stops. If
            the DCC server fails to close the database cleanly, the
            database must be cleaned by the server with it starts. That
            can take time.

    7. Configure flooding Skip to the next step if only remote DCC
       servers will be used.
       The DCC works better as more mailboxes participate, and "flooding"
       or exchanging checksums with other servers is the most effective
       way to get more participants. Flooding requires that every server
       participating in a network of DCC servers have a unique server-ID
       and know about all of the other server-IDs. That means that if
       your server might join a network of DCC servers, you should
       contact people involved in the network to obtain server-IDs for
       your servers. For now, server-IDs known to the public network of
       DCC server can be obtained by contacting Vernon Schryver.
       After you have an official server-ID,
          + Obtain the passwd-ID and its password and add them to
            your /var/dcc/ids file.
          + Add a line for each flooding peer to the /var/dcc/flod
            file.
          + Wait a few minutes for dccd to notice the change to the file
            and start flooding. The cdcc stats, cdcc "id X; flood
            list" and /var/dcc/libexec/dblist -Hv commands can be
            used to monitor the floods of reports of checksums of bulk
            mail.

    8. Configure greylisting Skip to the next step if greylisting
       will not be used.
       Because greylisting uses a modified DCC server to maintain a
       database of checksums of familiar mail senders, their addressees,
       and the IP addresses of their SMTP clients, the complete
       dcc-dccd.tar.Z tarball must be used.
       Larger sites can use more than one greylist server, with the
       greylist servers flooding data just like DCC servers.
       To configure greylisting:

         1. Assign greylist client- and server-IDs
            Client-IDs and matching passwords must be used by clients of
            greylist servers such as dccm and dccifd. The client-IDs must
            be in the /var/dcc/map file on the client system. Greylist
            client- and server-IDs must be in the /var/dcc/ids file
            on the greylist server. When a system hosts both DCC and
            greylist servers, it is convenient for clients to use the
            same client-ID and password for both. It is also convenient
            for a greylist server and a DCC server on a system to share a
            common server-ID and password.
            The vast majority of installations, which do not have local
            DCC servers, can use the greylist server-ID generated by the
            makefiles in the /var/dcc/ids file.

         2. Add the greylist server to /var/dcc/map
            If the cdcc "info" command does not show the correct
            greylist server, add it with something like
        cdcc "add localhost greylist 32768 secret"
            The DCC makefile files add a greylist server at localhost or

            127.0.0.1 to /var/dcc/map file

         3. Set /var/dcc/dcc_conf In most installations, enable a local
            greylist server by setting GREY_ENABLE=on in
            /var/dcc/dcc_conf.
            If necessary override the greylist embargo, wait, and
            white values in GREY_DCCD_ARGS in /var/dcc/dcc_conf.
            Otherwise, simply set GREY_CLIENT_ARGS=on

         4. Set /var/dcc/grey_flod
            Sites with more than one greylist server should arrange to
            flood data among them by adding lines to
            /var/dcc/grey_flod files in the same format as
            /var/dcc/flod files. Flooding among greylist servers uses
            port 6276 by default, and so that port may need to be opened
            in firewalls.

    9. Start dccm or dccifd If the DCC-sendmail interface, dccm, is not
       used, skip to the next step.
       The DCC sendmail milter interface dccm should be started
       before sendmail. That commonly requires changing an /etc/rc script
       or configuration file. The distributed file
       /var/dcc/libexec/start-dccm is a shell script that can be used
       to start dccm as the user "dcc." It requires local configuration
       parameters in the dcc_conf file in the DCC home directory. The
       rc script /var/dcc/libexec/rcDCC for starting dccd can be used
       with some versions of FreeBSD, Linux, and Solaris.
       The general MTA interface dccifd usually must be started
       before the MTA that uses it.

   10. Configure uses of dccproc If dccproc is used with procmail, add
       rules to procmailrc files as described in the dccproc man
       page.

   11. Adjust rejection thresholds
       It is best to only mark mail with X-DCC SMTP headers before
       changing procmail or dccm to reject mail. Configure dccm with
       DCCM_LOG_AT in dcc_conf to log bulk mail with somewhat lower
       counts than

Installation Parameters

   There are several installation configuration parameters that can set
   to suit individual preferences and systems.

   --disable-server   configure   do not build server
   --disable-dccifd   configure   do not build program interface
   --disable-dccm   configure   do not build sendmail interface
   --with-sendmail=DIR   configure ../sendmail or /usr/ports/mail/...
   directory containing sendmail milter header files
   --with-cgibin=DIR   configure --homedir/cgi-bin directory for DCC
   white list CGI scripts
   --with-rundir=DIR   configure /var/run/dcc "run" directory for PIDs
   and sockets
     CFLAGS both1   compiler options such as -g or -O2
     DCC_CFLAGS configure^2 depends on target compiler options
     PTHREAD_CFLAGS configure^2 depends on target compiler options for
   compiling with pthreads
     LDFLAGS both1   linker options
     DCC_LDFLAGS configure^2 depends on target linker options
     PTHREAD_LDFLAGS configure^2 depends on target linker options for
   compiling with pthreads
     LIBS configure^2   additional libraries to be configured in
   makefiles.
     PTHREAD_LIBS configure^2 depends on target libraries for pthreads
     CC both cc C compiler such as "gcc" or "/opt/SUNWspro/SC6.1/bin/cc"
     INSTALL make^1 ./autoconf/install-sh installation script
     DCCD_MAX_FLOODS make^1 32 maximum DCC server flooding peers
   --with-db-memory=MB   configure 64 minimum server database buffer size
   MB between 8 and 3072 MByte
   --with-max-db-mem=MB   configure 3072 maximum server database buffer
   size
   --with-max-log-size=KB   configure 32 maximum dccifd and dccm log file
   size in KBytes; 0=no limit
   --with-bad-locks   configure without work around broken fcntl()
   locking
   --without-IPv6   configure IPV6 on if supported turn off IPv6 support
   --with-socks[=lib]   configure   location of SOCKS client library
   --with-DCC-MD5   configure   use MD5 code in DCC source instead of any
   local library
   --with-kludge=FILE   configure   include header FILE, best with an
   absolute path

   Note^1
          These values are not built into the Makefiles by the configure
          script but their current values in the environment are used by
          the script and the Makefiles.

   Note^2
          These values are copied by the configure script from the
          environment into the generated Makefiles.

   Note^3
          When --disable-sys-inst is specified, the current UID and
          GID become the defaults, the man pages are not installed, and
          dccproc, cdcc, and dccsight are not installed SUID.
          It is usually also necessary to set --bindir to a private
          directory such as $HOME/bin.

Compatibility

   The DCC is thought to work on several systems including:

   BSDI BSD/OS
          The DCC works starting with version 3.0 of BSD/OS.

   FreeBSD
          The works starting with at least version 4.0 of FreeBSD.

   NetBSD
          The DCC should work starting with at least 1.4.2 without
          threads and so with dccd, dccproc, and all of DCC except the
          part that uses threads, dccm. Dccm is available if you point
          PTHREAD_LIBS, PTHREAD_CFLAGS, and PTHREAD_LDFLAGS to the
          optional threads package.

   OpenBSD
          The DCC works starting with at least 2.9 despite lame the lame
          mmap() implementation.

   Linux
          The DCC works starting with at least RedHat 5.2.

   AIX
          The DCC on 4.1.PPC has been tried but not well tested. Rumor
          has it that the 4.1.PPC pthreads code does not work with the
          sendmail milter library and dccm, but the rest of the DCC does
          work.

   Solaris
          The DCC compiles on several versions of Solaris with gcc or
          native compilers by setting the environment variable CC
          appropriately. You must use gmake or alias make to gmake.

          If your system has enough RAM to hold most of the database,
          adding -F to DBCLEAN_ARGS in dcc_conf can make the
          daily use of dbclean twice as fast and much less of a load
          on the system.

          While building the sendmail milter library, consider using
          _FFR_USE_POLL to avoid problems with large file descriptors and
          select().

   HP-UX
          The DCC compiles and works on versions of HP-UX starting with

          11.00. It requires gmake.
          Dccproc should work on 10.20, since it does not use pthreads.
          At least some versions have no known method for dccd to
          determine the size of physical memory, and so you must use

        ./configure --with-db-memory
        make install

   IRIX
          The DCC compiles on IRIX 6.5. It requires gmake.

   OSF1
          The DCC compiles on OSF1 V5.0 with gmake.

   OpenUNIX
          The DCC compiles on OpenUNIX 8.0.1.

   Mac OS/X
          The DCC compiles on at least some versions of Apple's OS/X.

   Windows
          The DCC client dccproc compiles and works on at least some
          versions of Windows 98 and Windows XP with Borland's free SDK
          and with Microsoft's SDK. See the main Makefile for
          Windows.

   Those system names include trademarks. Please don't abuse them.

Troubleshooting

   Much of the DCC list of frequently asked questions concerns
   troubleshooting DCC installations. Many of the messages in the archive
   of the DCC mailing list are also troubleshooting questions and
   answers.

Spam Traps

   Dccm and sendmail can be configured to report the checksums of
   unsolicited bulk mail so that other DCC clients can reject later
   copies of the same unsolicited bulk mail sent from other sources. Such
   mechanisms are commonly called spam traps.

   The sendmail "feature file" misc/dccdnsbl.m4 used as
   FEATURE(dccdnsbl) causes mail from blacklisted sources to be reported
   as extremely bulky to the DCC server as well as rejected. For example,
   the following would both reject and report mail from RSS entries:
  FEATURE(dccdnsbl, `relays.mail-abuse.org',
   `"Mail from " $`'&{client_addr} " reject to DCC - see http://www.mail-abuse.
org/rss/"')

   Entries in a sendmail access_db can also be rejected or discarded
   while they are reported to the DCC server by dccm. The script
   misc/hackmc modifies the output of sendmail .mc files to tell
   dccm about some undesirable mail. The script accepts one or more .mc
   files and generates the corresponding slightly modified .cf files. If
   the access_db entry starts with the string "DCC:", the message is
   reported by dccm to the DCC server as extremely bulky. Otherwise the
   message is rejected as usual. The remainder of the the access_db entry
   after "DCC:" consists of the optional string "DISCARD" followed by an
   optional SMTP status message. If the string "DISCARD" is present, the
   message is discarded instead of rejected. This is important to keep
   senders of unsolicited bulk mail from discovering and removing "spam
   trap" addresses from their lists.

   For example, a line like the following in an access_db can discard all
   mail from example.com while reporting it to the DCC server as
   extremely bulky. Note the quotes (").
    example.com     DCC: "DISCARD spam"

   It is also possible to route mail from a spam trap address to dccproc
   as described in the dccproc man page

SOCKS

   The DCC client and server programs can be built to use the SOCKS
   protocol. The --with-socks configure parameter configures the DCC
   client library and the DCC server to use common SOCKS network library
   functions. If the SOCKS library is in a standard place, something like
   --with-socks=socks should be sufficient. Setting the environment
   variable DCC_LDFLAGS to something like -L/usr/local/lib is
   sometimes helpful. Otherwise, using --with-socks without
   specifying the library name and setting LIBS to the full pathname
   of the library might work.

   DCC client programs including dccproc and dccm that use the DCC client
   library must be told to use the SOCKS5 protocol with the SOCKS on
   operation of cdcc. SOCKS5 is required instead of SOCKS4 because
   DCC clients communicate with DCC servers using UDP.

   DCC servers can use SOCKS4 or SOCKS5 when exchanging floods of reports
   of checksums. Links between individual pairs of peers are configured
   with the passive and SOCKS flags in the flod file described in the
   dccd man page. In both cases, the SOCKS library code must be
   configured, often in the files /etc/socks.conf and /etc/socksd.conf.

   When the DCC software is built with SOCKS, IPv6 name resolution is
   turned off.

   The DCC server and client programs have been tested with the
   DANTE library and server. The DANTE SOCKS implementation is also
   one of the FreeBSD "ports" or packages.

   Note that if a connection fails repeatedly, Dante will disable the
   rule that failed and will eventually try the underlying connect()
   call. This fails in almost every SOCKS environment because there is no
   available route for an ordinary connect(). Dante by default won't
   re-enable the failing rule. To fix this, change BADROUTE_EXPIRE from
   the default of 0*60 to 5 in include/config.h in the Dante source and
   recompile.

   The NEC SOCKS implementation should be similar.

  Version

   This document describes DCC version 1.2.74.

