--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/dccm.8.in	Tue Mar 10 13:49:58 2009 +0100
@@ -0,0 +1,1239 @@
+.\" Copyright (c) 2008 by Rhyolite Software, LLC
+.\"
+.\" This agreement is not applicable to any entity which sells anti-spam
+.\" solutions to others or provides an anti-spam solution as part of a
+.\" security solution sold to other entities, or to a private network
+.\" which employs the DCC or uses data provided by operation of the DCC
+.\" but does not provide corresponding data to other users.
+.\"
+.\" Permission to use, copy, modify, and distribute this software without
+.\" changes for any purpose with or without fee is hereby granted, provided
+.\" that the above copyright notice and this permission notice appear in all
+.\" copies and any distributed versions or copies are either unchanged
+.\" or not called anything similar to "DCC" or "Distributed Checksum
+.\" Clearinghouse".
+.\"
+.\" Parties not eligible to receive a license under this agreement can
+.\" obtain a commercial license to use DCC by contacting Rhyolite Software
+.\" at sales@rhyolite.com.
+.\"
+.\" A commercial license would be for Distributed Checksum and Reputation
+.\" Clearinghouse software.  That software includes additional features.  This
+.\" free license for Distributed ChecksumClearinghouse Software does not in any
+.\" way grant permision to use Distributed Checksum and Reputation Clearinghouse
+.\" software
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND RHYOLITE SOFTWARE, LLC DISCLAIMS ALL
+.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL RHYOLITE SOFTWARE, LLC
+.\" BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+.\" SOFTWARE.
+.\"
+.\" Rhyolite Software DCC 1.3.103-1.168 $Revision$
+.\"
+.Dd February 26, 2009
+.ds volume-ds-DCC Distributed Checksum Clearinghouse
+.Dt dccm 8 DCC
+.Os " "
+.Sh NAME
+.Nm dccm
+.Nd Distributed Checksum Clearinghouse Milter Interface
+.Sh SYNOPSIS
+.Bk -words
+.Nm
+.Op Fl VdbxANQ
+.Op Fl G Ar on | off | noIP | IPmask/xx
+.Op Fl h Ar homedir
+.Op Fl I Ar user
+.br
+.Op Fl p Ar protocol:filename | protocol:port@host
+.Op Fl m Ar map
+.br
+.Op Fl w Ar whiteclnt
+.Op Fl U Ar userdirs
+.Op Fl a Ar IGNORE | REJECT | DISCARD
+.br
+.Oo
+.Fl t Xo
+.Sm off
+.Ar type,
+.Op Ar log-thold,
+.Ar rej-thold
+.Sm on
+.Xc
+.Oc
+.Oo
+.Fl g Xo
+.Sm off
+.Op Ar not-
+.Ar type
+.Sm on
+.Xc
+.Oc
+.Op Fl S Ar header
+.br
+.Op Fl l Ar logdir
+.Op Fl R Ar rundir
+.Op Fl r Ar rejection-msg
+.Op Fl j Ar maxjobs
+.Op Fl B Ar dnsbl-option
+.Op Fl L Ar ltype,facility.level
+.Ek
+.Sh DESCRIPTION
+.Nm
+is a daemon built with the sendmail milter interface intended to connect
+.Xr sendmail 8
+to DCC servers.
+When built with the milter filter machinery and configured to talk to
+.Nm
+in the
+.Pa sendmail.cf
+file,
+sendmail passes all email to
+.Nm
+which in turn reports related checksums to the nearest DCC server.
+.Nm
+then adds an
+.Em X-DCC
+SMTP header line to the message.
+Sendmail is told to reject the message if it is unsolicited bulk mail.
+.Pp
+.Nm Dccm
+sends reports of checksums related to mail received by DCC clients
+and queries about the total number of reports of particular checksums.
+A DCC server receives
+.Em no
+mail, address, headers, or other information,
+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.
+Its only acts as a clearinghouse of counts for checksums computed by clients.
+For complete privacy as far as the DCC is concerned,
+the checksums of purely internal mail or other
+mail that is known to not be unsolicited bulk can be listed in a whitelist
+to not be reported to the DCC server.
+.Pp
+Since the checksums of messages that are whitelisted locally
+by the
+.Fl w Ar whiteclnt
+file are not reported to the DCC server,
+.Nm
+knows nothing about the total recipient counts for their checksums and
+so cannot add
+.Em X-DCC
+header lines to such messages.
+Sendmail does not tell
+.Nm
+about messages that are not received by sendmail via SMTP, including messages
+submitted locally and received via UUCP, and so they also do not receive
+.Em X-DCC
+header lines.
+.Pp
+Enable the daemon and put its parameters in the
+.Pa dcc_conf
+file and start the daemon with the
+.Pa @libexecdir@/start-dccm
+or
+.Pa var/dcc/libexec/rcDCC
+script.
+.Pp
+The list of servers that
+.Nm
+contacts is in the memory mapped file
+.Pa map
+shared by local DCC clients.
+The file is  maintained with
+.Xr cdcc 8 .
+.Ss OPTIONS
+The following options are available:
+.Bl -tag -width 3n
+.It Fl V
+displays the version of
+.Nm .
+.It Fl d
+enables debugging output from the DCC client software.
+Additional
+.Fl d
+options increase the number of messages.
+A single
+.Fl d
+ aborted SMTP transactions including those from some "dictionary attacks."
+.It Fl b
+causes the daemon to not detach itself from the controlling tty
+and put itself into the background.
+.It Fl x
+causes the daemon to try "extra hard" to contact a DCC server.
+Since it is usually more important to deliver mail than to report its
+checksums,
+.Nm
+normally does not delay too long while trying to contact a DCC server.
+It will not try again for several seconds after a failure.
+With
+.Fl x ,
+it will always try to contact the DCC server
+and it will tell the MTA to answer the DATA command with a 4yz
+temporary failure.
+.It Fl A
+adds to existing X-DCC headers in the message
+instead of replacing existing headers
+of the brand of the current server.
+.It Fl N
+neither adds, deletes, nor replaces existing X-DCC headers in the message.
+Each message is logged, rejected, and otherwise handled the same.
+.It Fl Q
+only queries the DCC server about the checksums of messages
+instead of reporting and querying.
+This is useful when
+.Nm
+is used to filter mail that has already been reported to a DCC
+server by another DCC client.
+No single mail message should be reported to a DCC
+server more than once per recipient,
+because each report will increase the apparent "bulkness" of the message.
+.Pp
+It is better to use
+.Em MXDCC
+lines in the global
+.Pa whiteclnt
+file for your MX mail servers that use DCC than
+.Fl Q .
+.It Fl G Ar on | off | noIP | IPmask/xx
+controls
+.Em greylisting .
+At least one working greylist server must be listed in the
+.Pa map
+file in the DCC home directory.
+If more than one is named,
+they must "flood" or change checksums and they must use the
+same
+.Fl G
+parameters.
+See
+.Xr dccd 8 .
+Usually all dccm or dccifd DCC client processes use the same
+.Fl G
+parameters.
+.Pp
+.Ar IPmask/xx
+and
+.Ar noIP
+remove part or all of the IP address from the greylist triple.
+The CIDR block size,
+.Ar xx ,
+must be between 1 and 128.
+96 is added to block sizes smaller than 33 to make them appropriate for
+the IPv6 addresses used by the DCC.
+.Ar IPmask/96
+differs from
+.Ar noIP
+for IPv4 addresses,
+because the former retains the IPv4 to IPv6 mapping prefix.
+.It Fl h Ar homedir
+overrides the default DCC home directory,
+.Pa @prefix@ .
+.It Fl I Ar user
+specifies the UID and GID of the process.
+.It Fl p Ar protocol:filename | protocol:port@host
+specifies the protocol and address by which sendmail will contact
+.Nm dccm .
+The default is a UNIX domain socket in the "run" directory,
+.Pa @dcc_rundir@/dccm .
+(See also
+.Fl R)
+This protocol and address must match the value in
+.Pa sendmail.cf .
+This mechanism can be used to connect
+.Nm
+on one computer to sendmail on another computer
+when a port and host name or IP address are used.
+.It Fl m Ar map
+specifies a name or path of the memory mapped parameter file instead
+of the default
+.Pa map
+file in the DCC home directory.
+It should be created with the
+.Xr cdcc 8
+command.
+.It Fl w Ar whiteclnt
+specifies an optional file containing filtering parameters
+as well as SMTP client IP addresses,
+SMTP envelope values, and header values
+of mail that is spam or is not spam and does not need a
+.Em X-DCC
+header,
+and whose checksums should not be reported to the DCC server.
+.Pp
+If the pathname
+.Ar whiteclnt
+is not absolute, it is relative to the DCC home directory.
+.Pp
+The format of the
+.Nm
+whiteclnt file is the same as the
+.Pa whitelist
+files used by
+.Xr dbclean 8
+and the
+.Pa whiteclnt
+file used by
+.Xr dccproc 8 .
+See
+.Xr dcc 8
+for a description of DCC white and blacklists.
+Because the contents of the
+.Ar whiteclnt
+file are used frequently, a companion file is automatically
+created and maintained.
+It has the same pathname but with an added suffix of
+.Ar .dccw
+and contains a memory mapped hash table of the main file.
+.Pp
+A whitelist entry ("OK") or two or more semi-whitelistings ("OK2")
+for one of the message's checksums prevents all of
+the message's checksums from being reported to the DCC server 
+and the addition of a
+.Em X-DCC
+header line by
+.Nm
+A whitelist entry for a checksum
+also prevents rejecting or discarding the message based on DCC recipient
+counts as specified by
+.Fl a
+and
+.Fl t .
+Otherwise, one or more checksums with blacklisting entries ("MANY") cause
+all of the message's
+checksums to be reported to the server with an addressee count of "MANY".
+.Pp
+If the message has a single recipient, an
+.Ar env_To
+.Ar whiteclnt
+entry of "OK" for the checksum of its recipient address acts like any other
+.Ar whiteclnt
+entry of "OK."
+When the SMTP message has more than one recipient,
+the effects can be complicated.
+When a message has several recipients with some but not all listed in the
+.Ar whiteclnt
+file,
+.Nm
+tries comply with the wishes of the users who want filtering as
+well as those who don't by silently not delivering the message to 
+those who want filtering (i.e. are not whitelisted) and delivering
+the message to don't want filtering.
+.It Fl U Ar userdirs
+enables per-user
+.Pa whiteclnt
+files and log directories.
+Each target of a message can have a directory of log files named
+.Ar usedirs/${dcc_userdir}/log
+where
+.Em ${dcc_userdir}
+is the
+.Pa sendmail.cf
+macro described below.
+If
+.Em ${dcc_userdir}
+is not set,
+.Ar userdirs/${rcpt_mailer}/${rcpt_addr}/log
+is used.
+The most likely value of
+.Ar mailer
+is
+.Ar local .
+Appropriate values for both
+.Ar ${rcpt_mailer}
+and
+.Ar ${rcpt_addr}
+can be seen by examining
+.Em env_To
+lines in
+.Fl l Ar logdir
+files.
+If it is not absolute,
+.Ar userdirs
+is relative to the DCC home directory.
+The directory containing the log files must be named
+.Ar log
+and it must be writable by the
+.Nm
+process.
+Each log directory must exist or logging for the corresponding
+is silently disabled.
+The files created in the log directory are owned by the UID of the
+.Nm
+process,
+but they have
+.Em group
+and
+.Em other
+read and write permissions copied from the corresponding
+.Ar log
+directory.
+To ensure the privacy of mail,
+it may be good to make the directories readable only by
+.Em owner
+and
+.Em group ,
+and to use a
+.Xr cron
+script that changes the owner of each file to match the grandparent
+.Ar addr
+directory.
+.Pp
+There can also be a per -user whitelist file named
+.Ar userdirs/${dcc_userdir}/whiteclnt
+or if
+.Ar ${dcc_userdir}
+is not set,
+.Ar userdirs/${rcpt_mailer}/${rcpt_addr}
+per-user whitelist files.
+Any checksum that is not white- or blacklisted by an individual
+addressee's 
+.Pa whiteclnt
+file  is checked in the main
+.Fl w whiteclnt
+file.
+A missing per-addressee
+.Ar whiteclnt
+file is the same as an empty file.
+Relative paths for files included in per-addressee files
+are resolved in the DCC home directory.
+The
+.Ar whiteclnt
+files and the
+.Ar addr
+directories containing them must be writable by the
+.Nm
+process.
+.Pp
+.Ar Option
+lines in per-user whiteclnt files can be used to modify many aspects of
+.Nm
+filtering,
+as described in the main
+.Xr dcc
+man page.
+For example, an
+.Ar option dcc-off
+line turns off DCC filtering for individual mailboxes.
+.It Fl a Ar IGNORE | REJECT | DISCARD
+specifies the action taken when
+DCC server counts or
+.Fl t
+thresholds say that a message is unsolicited and bulk.
+.Ar IGNORE
+causes the message to be unaffected except for adding the
+.Em X-DCC
+header line to the message.
+This turns off DCC filtering.
+.Pp
+Spam can also be
+.Ar REJECT Ns ed
+or accepted and silently
+.Ar DISCARD Ns ed
+without being delivered to local mailboxes.
+The default is
+.Ar REJECT .
+.Pp
+Mail forwarded via IP addresses marked
+.Em MX
+or
+.Em MXDCC
+in the main
+.Pa whiteclnt
+file is treated
+as if
+.Fl a Ar DISCARD
+were specified.
+This prevents "bouncing" spam.
+.Pp
+Determinations that mail is or is not spam from sendmail via
+.Em ${dcc_isspam}
+or
+.Em ${dcc_notspam}
+macros override
+.Fl a .
+The effects of the
+.Fl w Ar whiteclnt
+are not affected by
+.Fl a .
+.It Fl t Xo
+.Sm off
+.Ar type,
+.Op Ar log-thold,
+.Ar rej-thold
+.Sm on
+.Xc
+sets logging and "spam" thresholds for checksum
+.Ar type .
+The checksum types are
+.Ar IP ,
+.Ar env_From ,
+.Ar From ,
+.Ar Message-ID ,
+.Ar substitute ,
+.Ar Received ,
+.Ar Body ,
+.Ar Fuz1 ,
+.Ar Fuz2 ,
+.Ar rep-total ,
+and
+.Ar rep .
+The first six,
+.Ar IP
+through
+.Ar substitute ,
+have no effect except when a local DCC server configured with
+.Fl K
+is used.
+The
+.Ar substitute
+thresholds apply to the first substitute heading encountered in the mail
+message.
+The string
+.Ar ALL
+sets thresholds for all types, but is unlikely to be useful except for
+setting logging thresholds.
+The string
+.Ar CMN
+specifies the commonly used checksums
+.Ar Body ,
+.Ar Fuz1 ,
+and
+.Ar Fuz2 .
+.Ar Rej-thold
+and
+.Ar log-thold
+must be numbers, the string
+.Ar NEVER ,
+or the string
+.Ar MANY
+indicating millions of targets.
+Counts from the DCC server as large as the threshold for any single type
+are taken as sufficient evidence
+that the message should be logged or rejected.
+.Pp
+.Ar Log-thold
+is the threshold at which messages are logged.
+It can be handy to log messages at a lower threshold to find
+solicited bulk mail sources such as mailing lists.
+If no logging threshold is set,
+only rejected mail and messages with complicated combinations of white
+and blacklisting are logged.
+Messages that reach at least one of their rejection thresholds are
+logged regardless of logging thresholds.
+.Pp
+.Ar Rej-thold
+is the threshold at which messages are considered "bulk,"
+and so should be rejected or discarded if not whitelisted.
+.Pp
+DCC Reputation thresholds in the commercial version
+of the DCC are controlled by thresholds on checksum types
+.Ar rep
+and
+.Ar rep-total .
+Messages from an IP address that the DCC database says has sent
+more than
+.Fl t Ar rep-total,log-thold
+messages are logged.
+A DCC Reputation is computed for messages received
+from IP addresses that
+have sent more than
+.Fl t Ar rep-total,log-thold
+messages.
+The DCC Reputation of an IP address is the percentage of its messages
+that have been detected as bulk
+or having at least 10 recipients.
+The defaults are equivalent to
+.Fl t Ar rep,never
+and
+.Fl t Ar rep-total,never,20 .
+.Pp
+Bad DCC Reputations do not reject mail unless enabled by an
+.Ar option DCC-rep-on
+line in a
+.Pa whiteclnt
+file.
+.Pp
+The checksums of locally whitelisted messages are not checked with
+the DCC server and so only the number of targets of the current copy of
+a whitelisted message are compared against the thresholds.
+.Pp
+The default is
+.Ar ALL,NEVER ,
+so that nothing is discarded, rejected, or logged.
+A common choice is
+.Ar CMN,25,50
+to reject or discard
+mail with common bodies except as overridden by
+the whitelist of the DCC server, the sendmail
+.Em ${dcc_isspam}
+and
+.Em ${dcc_notspam}
+macros, and
+.Fl g ,
+and
+.Fl w .
+.It Fl g Xo
+.Sm off
+.Op Ar not-
+.Ar type
+.Sm on
+.Xc
+indicates that whitelisted,
+.Ar OK
+or
+.Ar OK2 ,
+counts from the DCC server for a type of checksum are to be believed.
+They should be ignored if prefixed with
+.Ar not- .
+.Ar Type
+is one of the same set of strings as for
+.Fl t .
+Only
+.Ar IP ,
+.Ar env_From ,
+and
+.Ar From
+are likely choices.
+By default all three are honored,
+and hence the need for
+.Ar not- .
+.It Fl S Ar hdr
+adds to the list of substitute or locally chosen headers that
+are checked with the
+.Fl w Ar whiteclnt
+file and sent to the DCC server.
+The checksum of the last header of type
+.Ar hdr
+found in the message is checked.
+.Ar Hdr
+can be
+.Em HELO
+to specify the SMTP envelope HELO value.
+.Ar Hdr
+can also be
+.Em mail_host
+to specify the sendmail "resolved" host name from
+the Mail_from value in the SMTP envelope.
+As many as six different substitute headers can be specified, but only
+the checksum of the first of the six will be sent to the DCC server.
+.It Fl l Ar logdir
+specifies a directory in which files containing copies of messages processed by
+.Nm
+are kept.
+They can be copied to per-user directories specified with
+.Fl U .
+Information about other recipients of a message is deleted from
+the per-user copies.
+.Pp
+See the FILES section below concerning the contents of the files.
+See also the
+.Ar option log-subdirectory-{day,hour,minute}
+lines in
+.Pa whiteclnt
+files described in
+.Xr dcc 8 .
+.Pp
+The directory is relative to the DCC home directory if it is not absolute
+.It Fl R Ar rundir
+specifies the "run" directory where the UNIX domain socket and file
+containing the daemon's process ID are stored.
+The default value is @dcc_rundir@ .
+.It Fl r Ar rejection-msg
+specifies the rejection message
+in
+.Fl o
+proxy mode
+for unsolicited bulk mail or for mail temporarily blocked by
+.Em greylisting
+when
+.Fl G
+is specified.
+The first
+.Fl r Ar rejection-msg
+replaces the default bulk mail rejection message,
+.Bk -words
+"5.7.1 550 mail %ID from %CIP rejected by DCC".
+.Ek
+." see rej_def in reply.c
+The second replaces
+.Bk -words
+"4.2.1 452 mail %ID from %CIP temporary greylist embargoed".
+.Ek
+." see grey_def in reply.c
+The third
+.Fl r Ar rejection-msg
+replaces the default SMTP rejection message
+.Bk -words
+"5.7.1 550 %ID bad reputation; see http://commercial-dcc.rhyolite.com/cgi-bin/reps.cgi?tgt=%CIP"
+.Ek
+for mail with bad DCC Reputations.
+If
+.Ar rejection-msg
+is the zero-length string,
+the
+.Fl r
+setting is counted but the corresponding message is not changed.
+.Pp
+.Ar Rejection-msg
+can contain specific information about the mail message.
+The following strings starting with % are replaced with the corresponding
+values:
+.Bl -tag -width "%BRESULT" -offset 4n -compact
+.It %ID
+message ID such as the unique part of log file name or sendmail queue ID
+.It %CIP
+SMTP client IP address
+.It %BTYPE
+type of DNS blacklist hit, such as "SMTP client", "mail_host", or "URL NS"
+.It %BTGT
+IP address or name declared bad by DNS blacklist
+.It %BPROBE
+domain name found in DNS blacklist such as 4.3.2.10.example.com
+.It %BRESULT
+value of the %BPROBE domain name found in DNS blacklist
+.El
+.Pp
+A common alternate for the bulk mail rejection message is
+.Bk -words
+"4.7.1 451 Access denied by DCC"
+.Ek
+to tell the sending mail system to continue trying.
+Use a 4yz response with caution, because it is likely to delay for days
+a delivery failure message for false positives.
+If the rejection message
+does not start with an RFC 1893 status code and RFC 2821 reply code,
+5.7.1 and 550 or 4.2.1 and 452 are used.
+.Pp
+See also
+.Fl B Ar set:rej-msg=rejection-msg
+to set the status message for mail rejected by DNS blacklists.
+.It Fl j Ar maxjobs
+limits the number of simultaneous requests that will be processed.
+The default value is the maximum number that seems to be possible given system
+limits on open files, select() bit masks, and so forth.
+Start
+.Nm
+with
+.Fl d
+and see the starting message in the system log to see the limit.
+.It Fl B Ar dnsbl-option
+enables DNS blacklist checks of the SMTP client IP address, SMTP envelope
+Mail_From sender domain name, and of host names in URLs in the message body.
+Body URL blacklisting has too many false positives to use on
+abuse mailboxes.
+It is less effective than greylisting with
+.Xr dccm 8
+or
+.Xr dccifd 8
+but can be useful in situations where
+greylisting cannot be used.
+.Pp
+.Ar Dnsbl-option
+is either one of the
+.Fl B Ar set:option
+forms or
+.Bd -literal -compact -offset 4n
+.Fl B Xo
+.Sm off
+.Ar domain Oo Ar ,IPaddr
+.Op Ar /xx Op Ar ,bltype Oc
+.Sm on
+.Xc
+.Ed
+.Ar Domain
+is a DNS blacklist domain such as example.com
+that will be searched.
+.Ar IPaddr Ns Op Ar /xxx
+is the string "any"
+an IP address in the DNS blacklist
+that indicates that the mail message
+should be rejected,
+or a CIDR block covering results from the DNS blacklist.
+"127.0.0.2" is assumed if
+.Ar IPaddr
+is absent.
+IPv6 addresses can be specified with the usual colon (:) notation.
+Names can be used instead of numeric addresses.
+The type of DNS blacklist
+is specified by
+.Ar bltype
+as
+.Ar name ,
+.Ar IPv4 ,
+or
+.Ar IPv6 .
+Given an envelope sender domain name or a domain name in a URL of
+spam.domain.org
+and a blacklist of type
+.Ar name ,
+spam.domain.org.example.com will be tried.
+Blacklist types of
+.Ar IPv4
+and
+.Ar IPv6
+require that the domain name in a URL sender address
+be resolved into an IPv4 or IPv6
+address.
+The address is then written as a reversed string of decimal
+octets to check the DNS blacklist, as in 2.0.0.127.example.com,
+.Pp
+More than one blacklist can be specified and blacklists can be grouped.
+All searching within a group is stopped at the first positive result.
+.Pp
+Positive results are ignored after being logged unless an
+.Ar option\ DNSBL-on
+line appears in the global or per-user
+.Pa whiteclnt
+file.
+.Pp
+.Bl -tag -width 3n
+.It Fl B Ar set:no-client
+says that SMTP client IP addresses and reverse DNS domain names should
+not be checked in the following blacklists.
+.br
+.Fl B Ar set:client
+restores the default for the following blacklists.
+.It Fl B Ar set:no-mail_host
+says that SMTP envelope Mail_From sender domain names should
+not be checked in the following blacklists.
+.Fl B Ar set:mail_host
+restores the default.
+.It Fl B Ar set:no-URL
+says that URLs in the message body should not be checked in the
+in the following blacklists.
+.Fl B Ar set:URL
+restores the default.
+.It Fl B Ar set:no-MX
+says MX servers of sender Mail_From domain names and host names in URLs
+should not be checked in the following blacklists.
+.br
+.Fl B Ar set:MX
+restores the default.
+.It Fl B Ar set:no-NS
+says DNS servers of sender Mail_From domain names and host names in URLs
+should not be checked in the following blacklists.
+.Fl B Ar set:NS
+restores the default.
+.It Fl B Ar set:defaults
+is equivalent to all of
+.Fl B Ar set:no-temp-fail
+.Fl B Ar set:client
+.br
+.Fl B Ar set:mail_host
+.Fl B Ar set:URL
+.Fl B Ar set:MX
+and
+.Fl B Ar set:NS
+.It Fl B Ar set:group=X
+adds later DNS blacklists specified with
+.Bd -literal -compact -offset 4n
+.Fl B Xo
+.Sm off
+.Ar domain Oo Ar ,IPaddr
+.Op Ar /xx Op Ar ,bltype Oc
+.Sm on
+.Xc
+.Ed
+to group 1, 2, or 3.
+.It Fl B Ar set:debug=X
+sets the DNS blacklist logging level
+.It Fl B Ar set:msg-secs=S
+limits
+.Nm
+to
+.Ar S
+seconds total for checking all DNS blacklists.
+The default is 25.
+.It Fl B Ar set:URL-secs=S
+limits
+.Nm
+to at most
+.Ar S
+seconds resolving and checking any single URL.
+The default is 11.
+Some spam contains dozens of URLs and that
+some "spamvertised" URLs contain host names that need minutes to
+resolve.
+Busy mail systems cannot afford to spend minutes checking each incoming
+mail message.
+.It Fl B Ar set:rej-msg=rejection-msg
+sets the SMTP rejection message for the following blacklists.
+.Ar Rejection-msg
+must be in the same format as for
+.Fl r .
+If
+.Ar rejection-msg
+is null, the default is restored.
+The default DNS blacklist rejection message is the first message set
+with
+.Fl r .
+.It Fl B Ar set:temp-fail
+causes
+.Nm
+to the MTA to answer the SMTP DATA command with
+.Bd -literal -offset 3n -compact
+452 4.2.1 mail %ID from %CIP temporary delayed for DNSBL
+.Ed
+if any DNS answer required for a DNSBL in the current group times out,
+including resolving names in URLs.
+.It Fl B Ar set:no-temp-fail
+restores the default of assuming a negative answer for DNS responses
+that take too long.
+.It Fl B Ar set:maxjobs=X
+sets maximum number of helper processes to
+.Ar X .
+In order to use typical single-threaded DNS resolver libraries,
+.Nm
+uses fleets of helper processes.
+It is rarely a good idea to change the default,
+which is the same as the maximum number of simultaneous jobs set with
+.Fl j .
+.It Fl B Ar set:progpath=@libexecdir@/dns-helper
+changes the path to the helper program.
+.El
+.It Fl L Ar ltype,facility.level
+specifies how messages should be logged.
+.Ar Ltype
+must be
+.Ar error ,
+.Ar info ,
+or
+.Ar off
+to indicate which of the two types of messages are being controlled or
+to turn off all
+.Xr syslog 3
+messages from
+.Nm .
+.Ar Level
+must be a
+.Xr syslog 3
+level among
+.Ar EMERG ,
+.Ar ALERT ,
+.Ar CRIT , ERR ,
+.Ar WARNING ,
+.Ar NOTICE ,
+.Ar INFO ,
+and
+.Ar DEBUG .
+.Ar Facility
+must be among
+.Ar AUTH ,
+.Ar AUTHPRIV ,
+.Ar CRON ,
+.Ar DAEMON ,
+.Ar FTP ,
+.Ar KERN ,
+.Ar LPR ,
+.Ar MAIL ,
+.Ar NEWS ,
+.Ar USER ,
+.Ar UUCP ,
+and
+.Ar LOCAL0
+through
+.Ar LOCAL7 .
+The default is equivalent to
+.Dl Fl L Ar info,MAIL.NOTICE  Fl L Ar error,MAIL.ERR
+.El
+.Pp
+.Nm
+normally sends counts of mail rejected and so forth the to system log at
+midnight.
+The SIGUSR1 signal sends an immediate report to the system log.
+They will be repeated every 24 hours instead of at midnight.
+.Sh SENDMAIL MACROS
+Sendmail can affect
+.Nm
+with the values of some
+.Pa sendmail.cf
+macros.
+These macro names must be added to the
+Milter.macros option statements in
+.Pa sendmail.cf
+as in the example "Feature" file dcc.m4.
+.Bl -tag -width dcc_mail_host
+.It Em ${dcc_isspam}
+causes a mail message to be reported to the DCC server
+as having been addressed to "MANY" recipients.
+The
+.Em ${dcc_isspam}
+macro is ignored if the
+.Em ${dcc_notspam}
+macro is set to a non-null string
+.Pp
+If the value of the
+.Ar ${dcc_isspam}
+is null,
+.Nm
+uses SMTP rejection messages controlled by
+.Fl a
+and
+.Fl r .
+If the value of the
+.Ar ${dcc_isspam}
+macro starts with "DISCARD",
+the mail message is silently discarded
+as with
+.Fl a Ar DISCARD.
+If value of the macro not null and does not start with "DISCARD",
+it is used as the SMTP error
+message given to the SMTP client trying to send the rejected message.
+The message starts with an optional SMTP error type and number
+followed by text.
+.Pp
+The
+.Fl a
+option does not effect messages
+marked spam with
+.Em ${dcc_isspam} .
+When the
+.Em ${dcc_isspam}
+macro is set, the message is rejected or discarded despite
+local or DCC database whitelist entries.
+The local whitelist does control whether the message's
+checksums will be reported to the DCC server and an
+.Em X-DCC
+SMTP header line will be added.
+.It Em ${dcc_notspam}
+causes a message not be considered unsolicited bulk despite
+evidence to the contrary.
+It also prevents
+.Nm
+from reporting the checksums of the message to the DCC server
+and from adding an
+.Em X-DCC
+header line.
+.Pp
+When the macro is set by the
+.Pa sendmail.cf
+rules,
+.Ar ${dcc_notspam}
+macros overrides DCC threshlds that say the message should be
+rejected as well as the effects of the
+.Em ${dcc_isspam}
+macro.
+.It Em ${dcc_mail_host}
+specifies the name of the SMTP client that is sending the message.
+This macro is usually the same as the
+.Em mail_host
+macro.
+They can differ when a sendmail "smart relay" is involved.
+The
+.Em ${dcc_mail_host}
+macro does not work if
+.Em FEATURE(delay_checks)
+is used.
+.It Em ${dcc_userdir}
+is the per-user whitelist and log directory for a recipient.
+If the macro is not set in sendmail.cf,
+$&{rcpt_mailer}/$&{rcpt_addr}
+is assumed, but with the recipient address converted to lower case.
+Whatever value is used,
+the directory name after the last slash (/) character is converted to
+lower case.
+Any value containing the string "/../" is ignored.
+.Pp
+This macro also does not work if
+.Em FEATURE(delay_checks)
+is used.
+.Pp
+The following two lines in a sendmail mc file have the same effect
+as not defining the ${dcc_userdir} macro, provided
+.Em FEATURE(dcc)
+is also used and
+the sendmail
+.Pa cf/feature
+directory has a symbolic link to the
+.Pa misc/dcc.m4
+file.
+.El
+.Pp
+.Bd -literal -compact
+SLocal_check_rcpt
+R$*	$: $1 $(macro {dcc_userdir} $@ $&{rcpt_mailer}/$&{rcpt_addr} $))
+.Ed
+.Sh FILES
+.Bl -tag -width whiteclnt -compact
+.It Pa @prefix@
+is the DCC home directory in which other files are found.
+.It Pa @libexecdir@/start-dccm
+is a script used to
+.Nm .
+.It Pa dcc/dcc_conf
+contains parameters used by the scripts to start DCC daemons and cron jobs.
+.It Pa logdir
+is an optional directory specified with
+.Fl l
+and containing marked mail.
+Each file in the directory contains one message, at least one of whose
+checksums reached its
+.Fl t
+thresholds or that is interesting for some other reason.
+Each file starts with lines containing the date when the message
+was received, the IP address of the SMTP client, and SMTP envelope
+values.
+Those lines are followed by the body of the SMTP message including its header
+as it was received by sendmail and without any new or changed header lines.
+Only approximately the first 32 KBytes of the body are recorded
+unless modified by
+.Em ./configure --with-max-log-size=xx
+The checksums for the message follow the body.
+They are followed by lines indicating that the
+.Em ${dcc_isspam}
+or
+.Em ${dcc_notspam}
+.Pa sendmail.cf
+macros were set or one of the checksums is white- or blacklisted by the
+.Fl w Ar whiteclnt
+file.
+Each file ends with the
+.Em X-DCC
+header line added to the message and the disposition of
+the message including SMTP status message if appropriate.
+.It Pa map
+is the memory mapped file of information concerning DCC servers
+in the DCC home directory.
+.It Pa whiteclnt
+contains the client whitelist in
+the format described in
+.Xr dcc 8 .
+.It Pa whiteclnt.dccw
+is a memory mapped hash table of the
+.Pa whiteclnt
+file.
+.It Pa dccm.pid
+in the
+.Fl R Ar rundir
+directory contains daemon's process ID.
+The string
+.Dq dccm
+is replaced by the file name containing the daemon to facilitate
+running multiple daemons, probably connected to remote instances of
+sendmail using TCP/IP instead of a UNIX domain socket.
+See also
+.Fl R .
+.It Pa @dcc_rundir@/dccm
+is the default UNIX domain socket used by the sendmail milter interface.
+See also
+.Fl R .
+.It Pa sendmail.cf
+is the
+.Xr sendmail 8
+control file.
+.It Pa misc/dcc.m4
+sendmail mc file that should have a symbolic link in the sendmail
+cf/feature directory so that
+.Em FEATURE(dcc)
+can be used in a sendmail mc file.
+.El
+.Sh EXAMPLES
+.Nm Dccm
+should be started before sendmail with something like the
+script
+.Pa @libexecdir@/start-dccm.
+It looks for common DCC parameters in the
+.Pa dcc_conf
+file in the DCC home directory,
+.Pa @prefix@.
+.Pp
+Those numbers should modified to fit local conditions.
+It might be wise to replace the "100" numbers with much larger
+values or with "MANY" until a few weeks of monitoring the log directory
+show that sources of mailing lists are in the server's whitelist file
+(see
+.Xr dccd 8 )
+or the local
+.Pa whiteclnt
+file.
+.Pp
+It is usually necessary to regularly delete old log files
+with a script like @libexecdir@/cron-dccd.
+.Pp
+On systems unlike modern FreeBSD and other UNIX-like systems which
+include sendmail milter support,
+sendmail must be built with the milter interface, such as by creating a
+.Pa devtools/Site/site.config.m4
+or similar file containing something like the following lines:
+.Bd -literal -offset indent
+APPENDDEF(`conf_sendmail_ENVDEF', `-D_FFR_MILTER=1')
+APPENDDEF(`conf_libmilter_ENVDEF', `-D_FFR_MILTER=1')
+.Ed
+.Pp
+Appropriate lines invoking the milter interface must be added to
+.Pa sendmail.cf.
+That can be done by putting a symbolic link to the
+the misc/dcc.m4 file in the DCC source to the sendmail cf/feature directory
+and adding the line
+.Pp
+.Dl FEATURE(dcc)
+.Pp
+to the local .mc file.
+.Pp
+Note that
+.Nm
+should not be used with the Postfix milter mechanism.
+Instead use
+.Xr dccifd 8
+as a before-queue filter as described in that man page.
+.Sh SEE ALSO
+.Xr cdcc 8 ,
+.Xr dbclean 8 ,
+.Xr dcc 8 ,
+.Xr dccd 8 ,
+.Xr dblist 8 ,
+.Xr dccifd 8 ,
+.Xr dccproc 8 ,
+.Xr dccsight 8 ,
+.Xr sendmail 8 .
+.Sh HISTORY
+Distributed Checksum Clearinghouses are based on an idea of Paul Vixie.
+Implementation of
+.Nm
+was started at Rhyolite Software in 2000.
+This document describes version 1.3.103.
+.Sh BUGS
+.Nm
+uses
+.Fl t
+where
+.Xr dccproc 8
+uses
+.Fl c .
+.Pp
+Systems without
+.Xr setrlimit 2
+and
+.Xr getrlimit 2
+RLIMIT_NOFILE
+can have problems with the default limit on the number of simultaneous
+jobs, the value of
+.Fl j .
+Every job requires four open files.
+These problems are usually seen with errors messages that say something like
+.Dl dccm[24448]: DCC: accept() returned invalid socket
+A fix is to use a smaller value for
+.Fl j
+or to allow
+.Nm
+to open more files.
+Sendmail version 8.13 and later can be told to poll() instead of select
+with SM_CONF_POLL.
+Some older versions of sendmail knew about FFR_USE_POLL.
+One of the following lines in your devtools/Site/site.config.m4
+file can help:
+.Bd -literal -offset indent
+APPENDDEF(`conf_libmilter_ENVDEF', `-DSM_CONF_POLL')
+APPENDDEF(`conf_libmilter_ENVDEF', `-DFFR_USE_POLL')
+.Ed
+.Pp
+On many systems with sendmail 8.11.3 and preceding,
+a bug in the sendmail milter mechanism causes
+.Nm
+to die with a core file when given a signal.