Mercurial > notdcc

comparison dccm.8.in @ 0:c7f6b056b673

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First import of vendor version
author Peter Gervai <grin@grin.hu>
date Tue, 10 Mar 2009 13:49:58 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:c7f6b056b673
1 .\" Copyright (c) 2008 by Rhyolite Software, LLC
2 .\"
3 .\" This agreement is not applicable to any entity which sells anti-spam
4 .\" solutions to others or provides an anti-spam solution as part of a
5 .\" security solution sold to other entities, or to a private network
6 .\" which employs the DCC or uses data provided by operation of the DCC
7 .\" but does not provide corresponding data to other users.
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software without
10 .\" changes for any purpose with or without fee is hereby granted, provided
11 .\" that the above copyright notice and this permission notice appear in all
12 .\" copies and any distributed versions or copies are either unchanged
13 .\" or not called anything similar to "DCC" or "Distributed Checksum
14 .\" Clearinghouse".
15 .\"
16 .\" Parties not eligible to receive a license under this agreement can
17 .\" obtain a commercial license to use DCC by contacting Rhyolite Software
18 .\" at sales@rhyolite.com.
19 .\"
20 .\" A commercial license would be for Distributed Checksum and Reputation
21 .\" Clearinghouse software. That software includes additional features. This
22 .\" free license for Distributed ChecksumClearinghouse Software does not in any
23 .\" way grant permision to use Distributed Checksum and Reputation Clearinghouse
24 .\" software
25 .\"
26 .\" THE SOFTWARE IS PROVIDED "AS IS" AND RHYOLITE SOFTWARE, LLC DISCLAIMS ALL
27 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
28 .\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL RHYOLITE SOFTWARE, LLC
29 .\" BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
30 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
31 .\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
32 .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
33 .\" SOFTWARE.
34 .\"
35 .\" Rhyolite Software DCC 1.3.103-1.168 $Revision$
36 .\"
37 .Dd February 26, 2009
38 .ds volume-ds-DCC Distributed Checksum Clearinghouse
39 .Dt dccm 8 DCC
40 .Os " "
41 .Sh NAME
42 .Nm dccm
43 .Nd Distributed Checksum Clearinghouse Milter Interface
44 .Sh SYNOPSIS
45 .Bk -words
46 .Nm
47 .Op Fl VdbxANQ
48 .Op Fl G Ar on | off | noIP | IPmask/xx
49 .Op Fl h Ar homedir
50 .Op Fl I Ar user
51 .br
52 .Op Fl p Ar protocol:filename | protocol:port@host
53 .Op Fl m Ar map
54 .br
55 .Op Fl w Ar whiteclnt
56 .Op Fl U Ar userdirs
57 .Op Fl a Ar IGNORE | REJECT | DISCARD
58 .br
59 .Oo
60 .Fl t Xo
61 .Sm off
62 .Ar type,
63 .Op Ar log-thold,
64 .Ar rej-thold
65 .Sm on
66 .Xc
67 .Oc
68 .Oo
69 .Fl g Xo
70 .Sm off
71 .Op Ar not-
72 .Ar type
73 .Sm on
74 .Xc
75 .Oc
76 .Op Fl S Ar header
77 .br
78 .Op Fl l Ar logdir
79 .Op Fl R Ar rundir
80 .Op Fl r Ar rejection-msg
81 .Op Fl j Ar maxjobs
82 .Op Fl B Ar dnsbl-option
83 .Op Fl L Ar ltype,facility.level
84 .Ek
85 .Sh DESCRIPTION
86 .Nm
87 is a daemon built with the sendmail milter interface intended to connect
88 .Xr sendmail 8
89 to DCC servers.
90 When built with the milter filter machinery and configured to talk to
91 .Nm
92 in the
93 .Pa sendmail.cf
94 file,
95 sendmail passes all email to
96 .Nm
97 which in turn reports related checksums to the nearest DCC server.
98 .Nm
99 then adds an
100 .Em X-DCC
101 SMTP header line to the message.
102 Sendmail is told to reject the message if it is unsolicited bulk mail.
103 .Pp
104 .Nm Dccm
105 sends reports of checksums related to mail received by DCC clients
106 and queries about the total number of reports of particular checksums.
107 A DCC server receives
108 .Em no
109 mail, address, headers, or other information,
110 but only cryptographically secure checksums of such information.
111 A DCC server cannot determine the text or other information that corresponds
112 to the checksums it receives.
113 Its only acts as a clearinghouse of counts for checksums computed by clients.
114 For complete privacy as far as the DCC is concerned,
115 the checksums of purely internal mail or other
116 mail that is known to not be unsolicited bulk can be listed in a whitelist
117 to not be reported to the DCC server.
118 .Pp
119 Since the checksums of messages that are whitelisted locally
120 by the
121 .Fl w Ar whiteclnt
122 file are not reported to the DCC server,
123 .Nm
124 knows nothing about the total recipient counts for their checksums and
125 so cannot add
126 .Em X-DCC
127 header lines to such messages.
128 Sendmail does not tell
129 .Nm
130 about messages that are not received by sendmail via SMTP, including messages
131 submitted locally and received via UUCP, and so they also do not receive
132 .Em X-DCC
133 header lines.
134 .Pp
135 Enable the daemon and put its parameters in the
136 .Pa dcc_conf
137 file and start the daemon with the
138 .Pa @libexecdir@/start-dccm
139 or
140 .Pa var/dcc/libexec/rcDCC
141 script.
142 .Pp
143 The list of servers that
144 .Nm
145 contacts is in the memory mapped file
146 .Pa map
147 shared by local DCC clients.
148 The file is maintained with
149 .Xr cdcc 8 .
150 .Ss OPTIONS
151 The following options are available:
152 .Bl -tag -width 3n
153 .It Fl V
154 displays the version of
155 .Nm .
156 .It Fl d
157 enables debugging output from the DCC client software.
158 Additional
159 .Fl d
160 options increase the number of messages.
161 A single
162 .Fl d
163 aborted SMTP transactions including those from some "dictionary attacks."
164 .It Fl b
165 causes the daemon to not detach itself from the controlling tty
166 and put itself into the background.
167 .It Fl x
168 causes the daemon to try "extra hard" to contact a DCC server.
169 Since it is usually more important to deliver mail than to report its
170 checksums,
171 .Nm
172 normally does not delay too long while trying to contact a DCC server.
173 It will not try again for several seconds after a failure.
174 With
175 .Fl x ,
176 it will always try to contact the DCC server
177 and it will tell the MTA to answer the DATA command with a 4yz
178 temporary failure.
179 .It Fl A
180 adds to existing X-DCC headers in the message
181 instead of replacing existing headers
182 of the brand of the current server.
183 .It Fl N
184 neither adds, deletes, nor replaces existing X-DCC headers in the message.
185 Each message is logged, rejected, and otherwise handled the same.
186 .It Fl Q
187 only queries the DCC server about the checksums of messages
188 instead of reporting and querying.
189 This is useful when
190 .Nm
191 is used to filter mail that has already been reported to a DCC
192 server by another DCC client.
193 No single mail message should be reported to a DCC
194 server more than once per recipient,
195 because each report will increase the apparent "bulkness" of the message.
196 .Pp
197 It is better to use
198 .Em MXDCC
199 lines in the global
200 .Pa whiteclnt
201 file for your MX mail servers that use DCC than
202 .Fl Q .
203 .It Fl G Ar on | off | noIP | IPmask/xx
204 controls
205 .Em greylisting .
206 At least one working greylist server must be listed in the
207 .Pa map
208 file in the DCC home directory.
209 If more than one is named,
210 they must "flood" or change checksums and they must use the
211 same
212 .Fl G
213 parameters.
214 See
215 .Xr dccd 8 .
216 Usually all dccm or dccifd DCC client processes use the same
217 .Fl G
218 parameters.
219 .Pp
220 .Ar IPmask/xx
221 and
222 .Ar noIP
223 remove part or all of the IP address from the greylist triple.
224 The CIDR block size,
225 .Ar xx ,
226 must be between 1 and 128.
227 96 is added to block sizes smaller than 33 to make them appropriate for
228 the IPv6 addresses used by the DCC.
229 .Ar IPmask/96
230 differs from
231 .Ar noIP
232 for IPv4 addresses,
233 because the former retains the IPv4 to IPv6 mapping prefix.
234 .It Fl h Ar homedir
235 overrides the default DCC home directory,
236 .Pa @prefix@ .
237 .It Fl I Ar user
238 specifies the UID and GID of the process.
239 .It Fl p Ar protocol:filename | protocol:port@host
240 specifies the protocol and address by which sendmail will contact
241 .Nm dccm .
242 The default is a UNIX domain socket in the "run" directory,
243 .Pa @dcc_rundir@/dccm .
244 (See also
245 .Fl R)
246 This protocol and address must match the value in
247 .Pa sendmail.cf .
248 This mechanism can be used to connect
249 .Nm
250 on one computer to sendmail on another computer
251 when a port and host name or IP address are used.
252 .It Fl m Ar map
253 specifies a name or path of the memory mapped parameter file instead
254 of the default
255 .Pa map
256 file in the DCC home directory.
257 It should be created with the
258 .Xr cdcc 8
259 command.
260 .It Fl w Ar whiteclnt
261 specifies an optional file containing filtering parameters
262 as well as SMTP client IP addresses,
263 SMTP envelope values, and header values
264 of mail that is spam or is not spam and does not need a
265 .Em X-DCC
266 header,
267 and whose checksums should not be reported to the DCC server.
268 .Pp
269 If the pathname
270 .Ar whiteclnt
271 is not absolute, it is relative to the DCC home directory.
272 .Pp
273 The format of the
274 .Nm
275 whiteclnt file is the same as the
276 .Pa whitelist
277 files used by
278 .Xr dbclean 8
279 and the
280 .Pa whiteclnt
281 file used by
282 .Xr dccproc 8 .
283 See
284 .Xr dcc 8
285 for a description of DCC white and blacklists.
286 Because the contents of the
287 .Ar whiteclnt
288 file are used frequently, a companion file is automatically
289 created and maintained.
290 It has the same pathname but with an added suffix of
291 .Ar .dccw
292 and contains a memory mapped hash table of the main file.
293 .Pp
294 A whitelist entry ("OK") or two or more semi-whitelistings ("OK2")
295 for one of the message's checksums prevents all of
296 the message's checksums from being reported to the DCC server
297 and the addition of a
298 .Em X-DCC
299 header line by
300 .Nm
301 A whitelist entry for a checksum
302 also prevents rejecting or discarding the message based on DCC recipient
303 counts as specified by
304 .Fl a
305 and
306 .Fl t .
307 Otherwise, one or more checksums with blacklisting entries ("MANY") cause
308 all of the message's
309 checksums to be reported to the server with an addressee count of "MANY".
310 .Pp
311 If the message has a single recipient, an
312 .Ar env_To
313 .Ar whiteclnt
314 entry of "OK" for the checksum of its recipient address acts like any other
315 .Ar whiteclnt
316 entry of "OK."
317 When the SMTP message has more than one recipient,
318 the effects can be complicated.
319 When a message has several recipients with some but not all listed in the
320 .Ar whiteclnt
321 file,
322 .Nm
323 tries comply with the wishes of the users who want filtering as
324 well as those who don't by silently not delivering the message to
325 those who want filtering (i.e. are not whitelisted) and delivering
326 the message to don't want filtering.
327 .It Fl U Ar userdirs
328 enables per-user
329 .Pa whiteclnt
330 files and log directories.
331 Each target of a message can have a directory of log files named
332 .Ar usedirs/${dcc_userdir}/log
333 where
334 .Em ${dcc_userdir}
335 is the
336 .Pa sendmail.cf
337 macro described below.
338 If
339 .Em ${dcc_userdir}
340 is not set,
341 .Ar userdirs/${rcpt_mailer}/${rcpt_addr}/log
342 is used.
343 The most likely value of
344 .Ar mailer
345 is
346 .Ar local .
347 Appropriate values for both
348 .Ar ${rcpt_mailer}
349 and
350 .Ar ${rcpt_addr}
351 can be seen by examining
352 .Em env_To
353 lines in
354 .Fl l Ar logdir
355 files.
356 If it is not absolute,
357 .Ar userdirs
358 is relative to the DCC home directory.
359 The directory containing the log files must be named
360 .Ar log
361 and it must be writable by the
362 .Nm
363 process.
364 Each log directory must exist or logging for the corresponding
365 is silently disabled.
366 The files created in the log directory are owned by the UID of the
367 .Nm
368 process,
369 but they have
370 .Em group
371 and
372 .Em other
373 read and write permissions copied from the corresponding
374 .Ar log
375 directory.
376 To ensure the privacy of mail,
377 it may be good to make the directories readable only by
378 .Em owner
379 and
380 .Em group ,
381 and to use a
382 .Xr cron
383 script that changes the owner of each file to match the grandparent
384 .Ar addr
385 directory.
386 .Pp
387 There can also be a per -user whitelist file named
388 .Ar userdirs/${dcc_userdir}/whiteclnt
389 or if
390 .Ar ${dcc_userdir}
391 is not set,
392 .Ar userdirs/${rcpt_mailer}/${rcpt_addr}
393 per-user whitelist files.
394 Any checksum that is not white- or blacklisted by an individual
395 addressee's
396 .Pa whiteclnt
397 file is checked in the main
398 .Fl w whiteclnt
399 file.
400 A missing per-addressee
401 .Ar whiteclnt
402 file is the same as an empty file.
403 Relative paths for files included in per-addressee files
404 are resolved in the DCC home directory.
405 The
406 .Ar whiteclnt
407 files and the
408 .Ar addr
409 directories containing them must be writable by the
410 .Nm
411 process.
412 .Pp
413 .Ar Option
414 lines in per-user whiteclnt files can be used to modify many aspects of
415 .Nm
416 filtering,
417 as described in the main
418 .Xr dcc
419 man page.
420 For example, an
421 .Ar option dcc-off
422 line turns off DCC filtering for individual mailboxes.
423 .It Fl a Ar IGNORE | REJECT | DISCARD
424 specifies the action taken when
425 DCC server counts or
426 .Fl t
427 thresholds say that a message is unsolicited and bulk.
428 .Ar IGNORE
429 causes the message to be unaffected except for adding the
430 .Em X-DCC
431 header line to the message.
432 This turns off DCC filtering.
433 .Pp
434 Spam can also be
435 .Ar REJECT Ns ed
436 or accepted and silently
437 .Ar DISCARD Ns ed
438 without being delivered to local mailboxes.
439 The default is
440 .Ar REJECT .
441 .Pp
442 Mail forwarded via IP addresses marked
443 .Em MX
444 or
445 .Em MXDCC
446 in the main
447 .Pa whiteclnt
448 file is treated
449 as if
450 .Fl a Ar DISCARD
451 were specified.
452 This prevents "bouncing" spam.
453 .Pp
454 Determinations that mail is or is not spam from sendmail via
455 .Em ${dcc_isspam}
456 or
457 .Em ${dcc_notspam}
458 macros override
459 .Fl a .
460 The effects of the
461 .Fl w Ar whiteclnt
462 are not affected by
463 .Fl a .
464 .It Fl t Xo
465 .Sm off
466 .Ar type,
467 .Op Ar log-thold,
468 .Ar rej-thold
469 .Sm on
470 .Xc
471 sets logging and "spam" thresholds for checksum
472 .Ar type .
473 The checksum types are
474 .Ar IP ,
475 .Ar env_From ,
476 .Ar From ,
477 .Ar Message-ID ,
478 .Ar substitute ,
479 .Ar Received ,
480 .Ar Body ,
481 .Ar Fuz1 ,
482 .Ar Fuz2 ,
483 .Ar rep-total ,
484 and
485 .Ar rep .
486 The first six,
487 .Ar IP
488 through
489 .Ar substitute ,
490 have no effect except when a local DCC server configured with
491 .Fl K
492 is used.
493 The
494 .Ar substitute
495 thresholds apply to the first substitute heading encountered in the mail
496 message.
497 The string
498 .Ar ALL
499 sets thresholds for all types, but is unlikely to be useful except for
500 setting logging thresholds.
501 The string
502 .Ar CMN
503 specifies the commonly used checksums
504 .Ar Body ,
505 .Ar Fuz1 ,
506 and
507 .Ar Fuz2 .
508 .Ar Rej-thold
509 and
510 .Ar log-thold
511 must be numbers, the string
512 .Ar NEVER ,
513 or the string
514 .Ar MANY
515 indicating millions of targets.
516 Counts from the DCC server as large as the threshold for any single type
517 are taken as sufficient evidence
518 that the message should be logged or rejected.
519 .Pp
520 .Ar Log-thold
521 is the threshold at which messages are logged.
522 It can be handy to log messages at a lower threshold to find
523 solicited bulk mail sources such as mailing lists.
524 If no logging threshold is set,
525 only rejected mail and messages with complicated combinations of white
526 and blacklisting are logged.
527 Messages that reach at least one of their rejection thresholds are
528 logged regardless of logging thresholds.
529 .Pp
530 .Ar Rej-thold
531 is the threshold at which messages are considered "bulk,"
532 and so should be rejected or discarded if not whitelisted.
533 .Pp
534 DCC Reputation thresholds in the commercial version
535 of the DCC are controlled by thresholds on checksum types
536 .Ar rep
537 and
538 .Ar rep-total .
539 Messages from an IP address that the DCC database says has sent
540 more than
541 .Fl t Ar rep-total,log-thold
542 messages are logged.
543 A DCC Reputation is computed for messages received
544 from IP addresses that
545 have sent more than
546 .Fl t Ar rep-total,log-thold
547 messages.
548 The DCC Reputation of an IP address is the percentage of its messages
549 that have been detected as bulk
550 or having at least 10 recipients.
551 The defaults are equivalent to
552 .Fl t Ar rep,never
553 and
554 .Fl t Ar rep-total,never,20 .
555 .Pp
556 Bad DCC Reputations do not reject mail unless enabled by an
557 .Ar option DCC-rep-on
558 line in a
559 .Pa whiteclnt
560 file.
561 .Pp
562 The checksums of locally whitelisted messages are not checked with
563 the DCC server and so only the number of targets of the current copy of
564 a whitelisted message are compared against the thresholds.
565 .Pp
566 The default is
567 .Ar ALL,NEVER ,
568 so that nothing is discarded, rejected, or logged.
569 A common choice is
570 .Ar CMN,25,50
571 to reject or discard
572 mail with common bodies except as overridden by
573 the whitelist of the DCC server, the sendmail
574 .Em ${dcc_isspam}
575 and
576 .Em ${dcc_notspam}
577 macros, and
578 .Fl g ,
579 and
580 .Fl w .
581 .It Fl g Xo
582 .Sm off
583 .Op Ar not-
584 .Ar type
585 .Sm on
586 .Xc
587 indicates that whitelisted,
588 .Ar OK
589 or
590 .Ar OK2 ,
591 counts from the DCC server for a type of checksum are to be believed.
592 They should be ignored if prefixed with
593 .Ar not- .
594 .Ar Type
595 is one of the same set of strings as for
596 .Fl t .
597 Only
598 .Ar IP ,
599 .Ar env_From ,
600 and
601 .Ar From
602 are likely choices.
603 By default all three are honored,
604 and hence the need for
605 .Ar not- .
606 .It Fl S Ar hdr
607 adds to the list of substitute or locally chosen headers that
608 are checked with the
609 .Fl w Ar whiteclnt
610 file and sent to the DCC server.
611 The checksum of the last header of type
612 .Ar hdr
613 found in the message is checked.
614 .Ar Hdr
615 can be
616 .Em HELO
617 to specify the SMTP envelope HELO value.
618 .Ar Hdr
619 can also be
620 .Em mail_host
621 to specify the sendmail "resolved" host name from
622 the Mail_from value in the SMTP envelope.
623 As many as six different substitute headers can be specified, but only
624 the checksum of the first of the six will be sent to the DCC server.
625 .It Fl l Ar logdir
626 specifies a directory in which files containing copies of messages processed by
627 .Nm
628 are kept.
629 They can be copied to per-user directories specified with
630 .Fl U .
631 Information about other recipients of a message is deleted from
632 the per-user copies.
633 .Pp
634 See the FILES section below concerning the contents of the files.
635 See also the
636 .Ar option log-subdirectory-{day,hour,minute}
637 lines in
638 .Pa whiteclnt
639 files described in
640 .Xr dcc 8 .
641 .Pp
642 The directory is relative to the DCC home directory if it is not absolute
643 .It Fl R Ar rundir
644 specifies the "run" directory where the UNIX domain socket and file
645 containing the daemon's process ID are stored.
646 The default value is @dcc_rundir@ .
647 .It Fl r Ar rejection-msg
648 specifies the rejection message
649 in
650 .Fl o
651 proxy mode
652 for unsolicited bulk mail or for mail temporarily blocked by
653 .Em greylisting
654 when
655 .Fl G
656 is specified.
657 The first
658 .Fl r Ar rejection-msg
659 replaces the default bulk mail rejection message,
660 .Bk -words
661 "5.7.1 550 mail %ID from %CIP rejected by DCC".
662 .Ek
663 ." see rej_def in reply.c
664 The second replaces
665 .Bk -words
666 "4.2.1 452 mail %ID from %CIP temporary greylist embargoed".
667 .Ek
668 ." see grey_def in reply.c
669 The third
670 .Fl r Ar rejection-msg
671 replaces the default SMTP rejection message
672 .Bk -words
673 "5.7.1 550 %ID bad reputation; see http://commercial-dcc.rhyolite.com/cgi-bin/reps.cgi?tgt=%CIP"
674 .Ek
675 for mail with bad DCC Reputations.
676 If
677 .Ar rejection-msg
678 is the zero-length string,
679 the
680 .Fl r
681 setting is counted but the corresponding message is not changed.
682 .Pp
683 .Ar Rejection-msg
684 can contain specific information about the mail message.
685 The following strings starting with % are replaced with the corresponding
686 values:
687 .Bl -tag -width "%BRESULT" -offset 4n -compact
688 .It %ID
689 message ID such as the unique part of log file name or sendmail queue ID
690 .It %CIP
691 SMTP client IP address
692 .It %BTYPE
693 type of DNS blacklist hit, such as "SMTP client", "mail_host", or "URL NS"
694 .It %BTGT
695 IP address or name declared bad by DNS blacklist
696 .It %BPROBE
697 domain name found in DNS blacklist such as 4.3.2.10.example.com
698 .It %BRESULT
699 value of the %BPROBE domain name found in DNS blacklist
700 .El
701 .Pp
702 A common alternate for the bulk mail rejection message is
703 .Bk -words
704 "4.7.1 451 Access denied by DCC"
705 .Ek
706 to tell the sending mail system to continue trying.
707 Use a 4yz response with caution, because it is likely to delay for days
708 a delivery failure message for false positives.
709 If the rejection message
710 does not start with an RFC 1893 status code and RFC 2821 reply code,
711 5.7.1 and 550 or 4.2.1 and 452 are used.
712 .Pp
713 See also
714 .Fl B Ar set:rej-msg=rejection-msg
715 to set the status message for mail rejected by DNS blacklists.
716 .It Fl j Ar maxjobs
717 limits the number of simultaneous requests that will be processed.
718 The default value is the maximum number that seems to be possible given system
719 limits on open files, select() bit masks, and so forth.
720 Start
721 .Nm
722 with
723 .Fl d
724 and see the starting message in the system log to see the limit.
725 .It Fl B Ar dnsbl-option
726 enables DNS blacklist checks of the SMTP client IP address, SMTP envelope
727 Mail_From sender domain name, and of host names in URLs in the message body.
728 Body URL blacklisting has too many false positives to use on
729 abuse mailboxes.
730 It is less effective than greylisting with
731 .Xr dccm 8
732 or
733 .Xr dccifd 8
734 but can be useful in situations where
735 greylisting cannot be used.
736 .Pp
737 .Ar Dnsbl-option
738 is either one of the
739 .Fl B Ar set:option
740 forms or
741 .Bd -literal -compact -offset 4n
742 .Fl B Xo
743 .Sm off
744 .Ar domain Oo Ar ,IPaddr
745 .Op Ar /xx Op Ar ,bltype Oc
746 .Sm on
747 .Xc
748 .Ed
749 .Ar Domain
750 is a DNS blacklist domain such as example.com
751 that will be searched.
752 .Ar IPaddr Ns Op Ar /xxx
753 is the string "any"
754 an IP address in the DNS blacklist
755 that indicates that the mail message
756 should be rejected,
757 or a CIDR block covering results from the DNS blacklist.
758 "127.0.0.2" is assumed if
759 .Ar IPaddr
760 is absent.
761 IPv6 addresses can be specified with the usual colon (:) notation.
762 Names can be used instead of numeric addresses.
763 The type of DNS blacklist
764 is specified by
765 .Ar bltype
766 as
767 .Ar name ,
768 .Ar IPv4 ,
769 or
770 .Ar IPv6 .
771 Given an envelope sender domain name or a domain name in a URL of
772 spam.domain.org
773 and a blacklist of type
774 .Ar name ,
775 spam.domain.org.example.com will be tried.
776 Blacklist types of
777 .Ar IPv4
778 and
779 .Ar IPv6
780 require that the domain name in a URL sender address
781 be resolved into an IPv4 or IPv6
782 address.
783 The address is then written as a reversed string of decimal
784 octets to check the DNS blacklist, as in 2.0.0.127.example.com,
785 .Pp
786 More than one blacklist can be specified and blacklists can be grouped.
787 All searching within a group is stopped at the first positive result.
788 .Pp
789 Positive results are ignored after being logged unless an
790 .Ar option\ DNSBL-on
791 line appears in the global or per-user
792 .Pa whiteclnt
793 file.
794 .Pp
795 .Bl -tag -width 3n
796 .It Fl B Ar set:no-client
797 says that SMTP client IP addresses and reverse DNS domain names should
798 not be checked in the following blacklists.
799 .br
800 .Fl B Ar set:client
801 restores the default for the following blacklists.
802 .It Fl B Ar set:no-mail_host
803 says that SMTP envelope Mail_From sender domain names should
804 not be checked in the following blacklists.
805 .Fl B Ar set:mail_host
806 restores the default.
807 .It Fl B Ar set:no-URL
808 says that URLs in the message body should not be checked in the
809 in the following blacklists.
810 .Fl B Ar set:URL
811 restores the default.
812 .It Fl B Ar set:no-MX
813 says MX servers of sender Mail_From domain names and host names in URLs
814 should not be checked in the following blacklists.
815 .br
816 .Fl B Ar set:MX
817 restores the default.
818 .It Fl B Ar set:no-NS
819 says DNS servers of sender Mail_From domain names and host names in URLs
820 should not be checked in the following blacklists.
821 .Fl B Ar set:NS
822 restores the default.
823 .It Fl B Ar set:defaults
824 is equivalent to all of
825 .Fl B Ar set:no-temp-fail
826 .Fl B Ar set:client
827 .br
828 .Fl B Ar set:mail_host
829 .Fl B Ar set:URL
830 .Fl B Ar set:MX
831 and
832 .Fl B Ar set:NS
833 .It Fl B Ar set:group=X
834 adds later DNS blacklists specified with
835 .Bd -literal -compact -offset 4n
836 .Fl B Xo
837 .Sm off
838 .Ar domain Oo Ar ,IPaddr
839 .Op Ar /xx Op Ar ,bltype Oc
840 .Sm on
841 .Xc
842 .Ed
843 to group 1, 2, or 3.
844 .It Fl B Ar set:debug=X
845 sets the DNS blacklist logging level
846 .It Fl B Ar set:msg-secs=S
847 limits
848 .Nm
849 to
850 .Ar S
851 seconds total for checking all DNS blacklists.
852 The default is 25.
853 .It Fl B Ar set:URL-secs=S
854 limits
855 .Nm
856 to at most
857 .Ar S
858 seconds resolving and checking any single URL.
859 The default is 11.
860 Some spam contains dozens of URLs and that
861 some "spamvertised" URLs contain host names that need minutes to
862 resolve.
863 Busy mail systems cannot afford to spend minutes checking each incoming
864 mail message.
865 .It Fl B Ar set:rej-msg=rejection-msg
866 sets the SMTP rejection message for the following blacklists.
867 .Ar Rejection-msg
868 must be in the same format as for
869 .Fl r .
870 If
871 .Ar rejection-msg
872 is null, the default is restored.
873 The default DNS blacklist rejection message is the first message set
874 with
875 .Fl r .
876 .It Fl B Ar set:temp-fail
877 causes
878 .Nm
879 to the MTA to answer the SMTP DATA command with
880 .Bd -literal -offset 3n -compact
881 452 4.2.1 mail %ID from %CIP temporary delayed for DNSBL
882 .Ed
883 if any DNS answer required for a DNSBL in the current group times out,
884 including resolving names in URLs.
885 .It Fl B Ar set:no-temp-fail
886 restores the default of assuming a negative answer for DNS responses
887 that take too long.
888 .It Fl B Ar set:maxjobs=X
889 sets maximum number of helper processes to
890 .Ar X .
891 In order to use typical single-threaded DNS resolver libraries,
892 .Nm
893 uses fleets of helper processes.
894 It is rarely a good idea to change the default,
895 which is the same as the maximum number of simultaneous jobs set with
896 .Fl j .
897 .It Fl B Ar set:progpath=@libexecdir@/dns-helper
898 changes the path to the helper program.
899 .El
900 .It Fl L Ar ltype,facility.level
901 specifies how messages should be logged.
902 .Ar Ltype
903 must be
904 .Ar error ,
905 .Ar info ,
906 or
907 .Ar off
908 to indicate which of the two types of messages are being controlled or
909 to turn off all
910 .Xr syslog 3
911 messages from
912 .Nm .
913 .Ar Level
914 must be a
915 .Xr syslog 3
916 level among
917 .Ar EMERG ,
918 .Ar ALERT ,
919 .Ar CRIT , ERR ,
920 .Ar WARNING ,
921 .Ar NOTICE ,
922 .Ar INFO ,
923 and
924 .Ar DEBUG .
925 .Ar Facility
926 must be among
927 .Ar AUTH ,
928 .Ar AUTHPRIV ,
929 .Ar CRON ,
930 .Ar DAEMON ,
931 .Ar FTP ,
932 .Ar KERN ,
933 .Ar LPR ,
934 .Ar MAIL ,
935 .Ar NEWS ,
936 .Ar USER ,
937 .Ar UUCP ,
938 and
939 .Ar LOCAL0
940 through
941 .Ar LOCAL7 .
942 The default is equivalent to
943 .Dl Fl L Ar info,MAIL.NOTICE Fl L Ar error,MAIL.ERR
944 .El
945 .Pp
946 .Nm
947 normally sends counts of mail rejected and so forth the to system log at
948 midnight.
949 The SIGUSR1 signal sends an immediate report to the system log.
950 They will be repeated every 24 hours instead of at midnight.
951 .Sh SENDMAIL MACROS
952 Sendmail can affect
953 .Nm
954 with the values of some
955 .Pa sendmail.cf
956 macros.
957 These macro names must be added to the
958 Milter.macros option statements in
959 .Pa sendmail.cf
960 as in the example "Feature" file dcc.m4.
961 .Bl -tag -width dcc_mail_host
962 .It Em ${dcc_isspam}
963 causes a mail message to be reported to the DCC server
964 as having been addressed to "MANY" recipients.
965 The
966 .Em ${dcc_isspam}
967 macro is ignored if the
968 .Em ${dcc_notspam}
969 macro is set to a non-null string
970 .Pp
971 If the value of the
972 .Ar ${dcc_isspam}
973 is null,
974 .Nm
975 uses SMTP rejection messages controlled by
976 .Fl a
977 and
978 .Fl r .
979 If the value of the
980 .Ar ${dcc_isspam}
981 macro starts with "DISCARD",
982 the mail message is silently discarded
983 as with
984 .Fl a Ar DISCARD.
985 If value of the macro not null and does not start with "DISCARD",
986 it is used as the SMTP error
987 message given to the SMTP client trying to send the rejected message.
988 The message starts with an optional SMTP error type and number
989 followed by text.
990 .Pp
991 The
992 .Fl a
993 option does not effect messages
994 marked spam with
995 .Em ${dcc_isspam} .
996 When the
997 .Em ${dcc_isspam}
998 macro is set, the message is rejected or discarded despite
999 local or DCC database whitelist entries.
1000 The local whitelist does control whether the message's
1001 checksums will be reported to the DCC server and an
1002 .Em X-DCC
1003 SMTP header line will be added.
1004 .It Em ${dcc_notspam}
1005 causes a message not be considered unsolicited bulk despite
1006 evidence to the contrary.
1007 It also prevents
1008 .Nm
1009 from reporting the checksums of the message to the DCC server
1010 and from adding an
1011 .Em X-DCC
1012 header line.
1013 .Pp
1014 When the macro is set by the
1015 .Pa sendmail.cf
1016 rules,
1017 .Ar ${dcc_notspam}
1018 macros overrides DCC threshlds that say the message should be
1019 rejected as well as the effects of the
1020 .Em ${dcc_isspam}
1021 macro.
1022 .It Em ${dcc_mail_host}
1023 specifies the name of the SMTP client that is sending the message.
1024 This macro is usually the same as the
1025 .Em mail_host
1026 macro.
1027 They can differ when a sendmail "smart relay" is involved.
1028 The
1029 .Em ${dcc_mail_host}
1030 macro does not work if
1031 .Em FEATURE(delay_checks)
1032 is used.
1033 .It Em ${dcc_userdir}
1034 is the per-user whitelist and log directory for a recipient.
1035 If the macro is not set in sendmail.cf,
1036 $&{rcpt_mailer}/$&{rcpt_addr}
1037 is assumed, but with the recipient address converted to lower case.
1038 Whatever value is used,
1039 the directory name after the last slash (/) character is converted to
1040 lower case.
1041 Any value containing the string "/../" is ignored.
1042 .Pp
1043 This macro also does not work if
1044 .Em FEATURE(delay_checks)
1045 is used.
1046 .Pp
1047 The following two lines in a sendmail mc file have the same effect
1048 as not defining the ${dcc_userdir} macro, provided
1049 .Em FEATURE(dcc)
1050 is also used and
1051 the sendmail
1052 .Pa cf/feature
1053 directory has a symbolic link to the
1054 .Pa misc/dcc.m4
1055 file.
1056 .El
1057 .Pp
1058 .Bd -literal -compact
1059 SLocal_check_rcpt
1060 R$* $: $1 $(macro {dcc_userdir} $@ $&{rcpt_mailer}/$&{rcpt_addr} $))
1061 .Ed
1062 .Sh FILES
1063 .Bl -tag -width whiteclnt -compact
1064 .It Pa @prefix@
1065 is the DCC home directory in which other files are found.
1066 .It Pa @libexecdir@/start-dccm
1067 is a script used to
1068 .Nm .
1069 .It Pa dcc/dcc_conf
1070 contains parameters used by the scripts to start DCC daemons and cron jobs.
1071 .It Pa logdir
1072 is an optional directory specified with
1073 .Fl l
1074 and containing marked mail.
1075 Each file in the directory contains one message, at least one of whose
1076 checksums reached its
1077 .Fl t
1078 thresholds or that is interesting for some other reason.
1079 Each file starts with lines containing the date when the message
1080 was received, the IP address of the SMTP client, and SMTP envelope
1081 values.
1082 Those lines are followed by the body of the SMTP message including its header
1083 as it was received by sendmail and without any new or changed header lines.
1084 Only approximately the first 32 KBytes of the body are recorded
1085 unless modified by
1086 .Em ./configure --with-max-log-size=xx
1087 The checksums for the message follow the body.
1088 They are followed by lines indicating that the
1089 .Em ${dcc_isspam}
1090 or
1091 .Em ${dcc_notspam}
1092 .Pa sendmail.cf
1093 macros were set or one of the checksums is white- or blacklisted by the
1094 .Fl w Ar whiteclnt
1095 file.
1096 Each file ends with the
1097 .Em X-DCC
1098 header line added to the message and the disposition of
1099 the message including SMTP status message if appropriate.
1100 .It Pa map
1101 is the memory mapped file of information concerning DCC servers
1102 in the DCC home directory.
1103 .It Pa whiteclnt
1104 contains the client whitelist in
1105 the format described in
1106 .Xr dcc 8 .
1107 .It Pa whiteclnt.dccw
1108 is a memory mapped hash table of the
1109 .Pa whiteclnt
1110 file.
1111 .It Pa dccm.pid
1112 in the
1113 .Fl R Ar rundir
1114 directory contains daemon's process ID.
1115 The string
1116 .Dq dccm
1117 is replaced by the file name containing the daemon to facilitate
1118 running multiple daemons, probably connected to remote instances of
1119 sendmail using TCP/IP instead of a UNIX domain socket.
1120 See also
1121 .Fl R .
1122 .It Pa @dcc_rundir@/dccm
1123 is the default UNIX domain socket used by the sendmail milter interface.
1124 See also
1125 .Fl R .
1126 .It Pa sendmail.cf
1127 is the
1128 .Xr sendmail 8
1129 control file.
1130 .It Pa misc/dcc.m4
1131 sendmail mc file that should have a symbolic link in the sendmail
1132 cf/feature directory so that
1133 .Em FEATURE(dcc)
1134 can be used in a sendmail mc file.
1135 .El
1136 .Sh EXAMPLES
1137 .Nm Dccm
1138 should be started before sendmail with something like the
1139 script
1140 .Pa @libexecdir@/start-dccm.
1141 It looks for common DCC parameters in the
1142 .Pa dcc_conf
1143 file in the DCC home directory,
1144 .Pa @prefix@.
1145 .Pp
1146 Those numbers should modified to fit local conditions.
1147 It might be wise to replace the "100" numbers with much larger
1148 values or with "MANY" until a few weeks of monitoring the log directory
1149 show that sources of mailing lists are in the server's whitelist file
1150 (see
1151 .Xr dccd 8 )
1152 or the local
1153 .Pa whiteclnt
1154 file.
1155 .Pp
1156 It is usually necessary to regularly delete old log files
1157 with a script like @libexecdir@/cron-dccd.
1158 .Pp
1159 On systems unlike modern FreeBSD and other UNIX-like systems which
1160 include sendmail milter support,
1161 sendmail must be built with the milter interface, such as by creating a
1162 .Pa devtools/Site/site.config.m4
1163 or similar file containing something like the following lines:
1164 .Bd -literal -offset indent
1165 APPENDDEF(`conf_sendmail_ENVDEF', `-D_FFR_MILTER=1')
1166 APPENDDEF(`conf_libmilter_ENVDEF', `-D_FFR_MILTER=1')
1167 .Ed
1168 .Pp
1169 Appropriate lines invoking the milter interface must be added to
1170 .Pa sendmail.cf.
1171 That can be done by putting a symbolic link to the
1172 the misc/dcc.m4 file in the DCC source to the sendmail cf/feature directory
1173 and adding the line
1174 .Pp
1175 .Dl FEATURE(dcc)
1176 .Pp
1177 to the local .mc file.
1178 .Pp
1179 Note that
1180 .Nm
1181 should not be used with the Postfix milter mechanism.
1182 Instead use
1183 .Xr dccifd 8
1184 as a before-queue filter as described in that man page.
1185 .Sh SEE ALSO
1186 .Xr cdcc 8 ,
1187 .Xr dbclean 8 ,
1188 .Xr dcc 8 ,
1189 .Xr dccd 8 ,
1190 .Xr dblist 8 ,
1191 .Xr dccifd 8 ,
1192 .Xr dccproc 8 ,
1193 .Xr dccsight 8 ,
1194 .Xr sendmail 8 .
1195 .Sh HISTORY
1196 Distributed Checksum Clearinghouses are based on an idea of Paul Vixie.
1197 Implementation of
1198 .Nm
1199 was started at Rhyolite Software in 2000.
1200 This document describes version 1.3.103.
1201 .Sh BUGS
1202 .Nm
1203 uses
1204 .Fl t
1205 where
1206 .Xr dccproc 8
1207 uses
1208 .Fl c .
1209 .Pp
1210 Systems without
1211 .Xr setrlimit 2
1212 and
1213 .Xr getrlimit 2
1214 RLIMIT_NOFILE
1215 can have problems with the default limit on the number of simultaneous
1216 jobs, the value of
1217 .Fl j .
1218 Every job requires four open files.
1219 These problems are usually seen with errors messages that say something like
1220 .Dl dccm[24448]: DCC: accept() returned invalid socket
1221 A fix is to use a smaller value for
1222 .Fl j
1223 or to allow
1224 .Nm
1225 to open more files.
1226 Sendmail version 8.13 and later can be told to poll() instead of select
1227 with SM_CONF_POLL.
1228 Some older versions of sendmail knew about FFR_USE_POLL.
1229 One of the following lines in your devtools/Site/site.config.m4
1230 file can help:
1231 .Bd -literal -offset indent
1232 APPENDDEF(`conf_libmilter_ENVDEF', `-DSM_CONF_POLL')
1233 APPENDDEF(`conf_libmilter_ENVDEF', `-DFFR_USE_POLL')
1234 .Ed
1235 .Pp
1236 On many systems with sendmail 8.11.3 and preceding,
1237 a bug in the sendmail milter mechanism causes
1238 .Nm
1239 to die with a core file when given a signal.