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


NAME

     dbclean -- Clean Distributed Checksum Clearinghouse Database


SYNOPSIS

     dbclean [-dfFNPSVqu] [-i id] [-a [server-addr][,port]] [-h homedir]
             [-H hash-file-dir] [-D db-file-dir] [-G on] [-R mode]
             [-s hash-size] [-e seconds] [-E spamsecs]
             [-L ltype,facility.level]


DESCRIPTION

     Dbclean creates empty, rebuilds corrupted, and deletes or expires old re-
     ports of checksums from DCC databases.  It should be installed where it
     will be found with the path given the DCC server daemon when the daemon
     needs to expand the hash table.  See dccd(8).  It should also be run by
     the daily cron(8) job, @libexecdir@/cron-dccd.

     The whitelist in @prefix@/whitelist or @prefix@/grey_whitelist are built
     into the DCC server's database.  Changes to the whitelist are not effec-
     tive until dbclean is run.  White or blacklists can also be used by DCC
     clients and work better.

   OPTIONS
     The following options are available.  Most of them should set by changing
     DBCLEAN_LOGDAYS and DBCLEAN_ARGS in the @prefix@/dcc_conf control file.

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

     -F   uses write() instead of mmap() and msync() in some cases to modify
          the DCC database.  This works better on some versions of Solaris
          provided the entire DCC database fits in RAM and provided the file
          system has not been tuned for the large, random accesses of a DCC
          database.  It is the default on Solaris except when the database is
          in a memory mapped file system or the entire database fits in RAM.
          Do not use -F with -f, -H, or -D.

     -f   uses mmap() and msync() to modify the DCC database.  Do not use -f
          with -F, -H, or -D.

     -N   creates a new, empty database.  There must not be an existing data-
          base and the DCC server, dccd(8), must not be running.

     -P   expires old checksums from a database using the -e -and -E values
          from the preceding use of dbclean.  -P cannot be used with -e or -E.
          Using -P differs from not using -e or -E, because in the absence of
          all three, their default values are used.

     -S   says that the DCC server, dccd(8), is not running and so dbclean
          should run stand-alone and not try to tell the DCC server about
          changes to the database.  -i is not needed with -S.

     -V   displays the version of the DCC database cleaner.  Two or more -V
          options show the options with which it was built.

     -q   quiets the announcement to stderr of the final results and debugging
          messages turned on with -d.  Results are still sent to the system
          log.

     -u   should be used when the file system containing the dcc_db and
          dcc_db.hash files is "ultra-fast," such as a solid-state drive.
          This setting postpones writing some data during normal operation un-
          til the system is shutdown.  This reduces wear on the SSD at the
          cost of writing GBytes of data when the system is shutdown.  Writing
          GBytes to a rotating disk at system shutdown unacceptable, but not
          noticeable to a non-rotating disk that operates 10 or 100 times
          faster.

     -i id
          specifies the DCC ID recognized by the local DCC server as its own.
          This ID allows the DCC server to recognize commands from dbclean to
          stop using the database while it is being cleaned.

     -a [server-addr][,port]
          is commonly used to specify a UDP port or IP address of the local
          server other than the default.

     -h homedir
          overrides the default DCC home directory, @prefix@.

     -H hash-file-dir
          puts the dcc_db.hash hash table file in the hash-file-dir directory
          with a symbolic link.  Using -H to put the hash table in a memory,
          "tmpfs", or "swap" file system such as /dev/shm or /tmp signifi-
          cantly speeds up the DCC server, dccd(8), on operating systems such
          as Linux and Solaris that lack the MAP_NOSYNC flag for the mmap(8)
          system call.

          The memory file system must have space for two copies of the
          dcc_db.hash file.  -H is undesirable on FreeBSD and other systems
          with MAP_NOSYNC except when -D is used.  The DCC database file,
          dcc_db, should usually be in file system that is not cleared by op-
          erating system rebooting and not in a memory file system.

          Use or stop using -H by adding it to or removing it from DB-
          CLEAN_ARGS in @prefix@/dcc_conf and manually running or waiting for
          the nightly run of the @libexecdir@/cron-dccd cron job.

          Do not use -H with -F or -f.

     -D db-file-dir
          puts the @prefix@/dcc_db database and the @prefix@/dcc_db.hash hash
          table files in the db-file-dir directory with symbolic links.  Using
          -D to put the files in a memory, "tmpfs", or "swap" file system such
          as /dev/shm or /tmp significantly speeds up the DCC server, dccd(8),
          but causes several GBytes of database transfers before DCC is effec-
          tive whenever the operating system is restarted.  -D should not be
          used except at sites with more than one DCC server installation and
          where at least one of the other local servers is not using -D.  -D
          should only be used on systems that are rarely rebooted, because up
          to one month is required for the database reach equilibrium.

          The memory file system must have space for two copies of the dcc_db
          file.

          Use or stop using -D by adding it to or removing it from DB-
          CLEAN_ARGS in @prefix@/dcc_conf and manually running or waiting for
          the nightly run of the @libexecdir@/cron-dccd cron job.

          Do not use -D with -F or -f.

     -G on
          cleans a greylist database in @prefix@/grey_db and
          @prefix@/grey_db.hash instead of of a DCC server database.

     -R mode
          repairs a database or does a quick cleaning.  Mode must be one of
          the following:
          bad    to repair a broken database.
          quick  for a quick, superficial cleaning during the day.
          hash   to rebuild a hash not sent to disk before the system was re-
                 booted.
          failsafe
                 to work around missing nightly cleaning by the cron(8) job,
                 @libexecdir@/cron-dccd
          del    to finish processing a delete command received by dccd(8).

     -s hash-size
          specifies a size for the hash table in @prefix@/dcc_db.hash.  By de-
          fault the hash table is rebuilt to be approximately 80% full based
          on an estimate of the number of distinct checksums in the database
          file.

     -e seconds
          specifies that reports older than seconds and with totals below 10
          targets should be deleted.  Reports older than seconds of checksums
          that have been reported more recently are summarized in the data-
          base.  The default value is 1DAY or the value of -E, whichever is
          smaller.  The 1 day default is reduced if the system does not appear
          to have enough RAM to hold the database.  The minimum is 1 hour.
          Seconds can also be NEVER or a number of hours, days, or weeks fol-
          lowed by HOURS, H, DAYS, D, WEEKS or W.

          DCC servers that are not very busy and are isolated or do not re-
          ceive "floods" of checksums from busy servers should use longer val-
          ues to increase their chances of recognizing bulk mail.

     -E spamsecs
          changes the expiration of checksums with more than 10 targets from
          the default of 30DAYS or the explicit value of -e, whichever is
          larger.  The default is reduced if the system does not have enough
          RAM to hold the database.  Spamsecs can also be NEVER or a number of
          hours, days, or weeks followed by HOURS, H, DAYS, D, WEEKS or W.

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

     dbclean exits 0 on success, and > 0 if an error occurs.


FILES

     @prefix@      is the DCC home directory containing data and control
                   files.
     dcc_conf      is the DCC control file.
     dcc_db        is the main file containing mail checksums.
     dcc_db.hash   mail checksum database hash table.
     grey_db       is the database of greylist checksums.
     grey_db.hash  is the greylist database hash table.
     dcc_db-new, dcc_db-new.hash, grey_db-new, grey_db-new.hash
                   new database and hash files until they are renamed.
     dcc_db-old, grey_db-old
                   previous database files.
     ids           list of IDs and passwords, as described in dccd(8).
     whitelist     contains the DCC server whitelist in the format described
                   in dcc(8).
     grey_whitelist
                   contains the greylist server whitelist.


SEE ALSO

     cdcc(8), cron(8), dcc(8), dccd(8), dblist(8), dccifd(8), dccm(8),
     dccproc(8).


HISTORY

     Implementation of dbclean was started at Rhyolite Software, in 2000.
     This document describes version RHYOLITE_VERSION.

                                March 22, 2024

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