Mercurial > notdcc

comparison dccifd.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.102 $Revision$
36 .\"
37 .Dd February 26, 2009
38 .ds volume-ds-DCC Distributed Checksum Clearinghouse
39 .Dt dccifd 8 DCC
40 .Os " "
41 .Sh NAME
42 .Nm dccifd
43 .Nd Distributed Checksum Clearinghouse Interface Daemon
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 .Op Fl p Ar /sock | host,port,rhost/bits
52 .Op Fl o Ar /sock | host,port
53 .br
54 .Op Fl D Ar local-domain
55 .Op Fl m Ar map
56 .Op Fl w Ar whiteclnt
57 .Op Fl U Ar userdirs
58 .br
59 .Op Fl a Ar IGNORE | REJECT | DISCARD
60 .Oo
61 .Fl t Xo
62 .Sm off
63 .Ar type,
64 .Op Ar log-thold,
65 .Ar rej-thold
66 .Sm on
67 .Xc
68 .Oc
69 .br
70 .Oo
71 .Fl g Xo
72 .Sm off
73 .Op Ar not-
74 .Ar type
75 .Sm on
76 .Xc
77 .Oc
78 .Op Fl S Ar header
79 .Op Fl l Ar logdir
80 .Op Fl R Ar rundir
81 .Op Fl r Ar rejection-msg
82 .Op Fl T Ar tmpdir
83 .Op Fl j Ar maxjobs
84 .br
85 .Op Fl B Ar dnsbl-option
86 .Op Fl L Ar ltype,facility.level
87 .Ek
88 .Sh DESCRIPTION
89 .Pp
90 .Nm
91 is a daemon intended to connect spam filters such as SpamAssasin
92 and mail transfer agents (MTAs) other than sendmail to DCC servers.
93 The MTA or filter
94 .Nm
95 which in turn reports related checksums to the nearest DCC server
96 and adds an
97 .Em X-DCC
98 SMTP header line to the message.
99 The MTA is told to reject the message if it is unsolicited bulk.
100 .Pp
101 .Nm Dccifd
102 is similar to the DCC sendmail milter interface,
103 .Xr dccm 8
104 and the DCC Procmail interface,
105 .Xr dccproc 8 .
106 .Nm Dccifd
107 is more efficient than
108 .Xr dccproc 8
109 but not restricted to use with sendmail like
110 .Xr dccm 8 .
111 All three send reports of checksums related to mail received by DCC clients
112 and queries about the total number of reports of particular checksums.
113 .Pp
114 MTA programs use a simple ASCII protocol a subset of SMTP to send
115 a mail message including its SMTP envelope to the daemon.
116 .Nm Dccifd
117 responds with an indication of whether the message is unsolicited bulk
118 and an optional copy of the message with an
119 .Em X-DCC
120 header added.
121 The ASCII protocol is described below and in the
122 .Pa include/dccif.h
123 file in the DCC source.
124 There is a sample C interface routine in the
125 .Pa dcclib/dccif.c
126 file in the DCC source and the
127 .Pa dcclib.a
128 library generated from the source.
129 A
130 .Em Perl
131 version of the interface routine is in
132 .Pa dccifd/dccif.pl .
133 Test or demonstration programs in the style of
134 .Xr dccproc 8
135 that use those interface routines are in
136 .Pa dccifd/dccif-test .
137 .Pp
138 A subset of ESMTP can be used instead of the ASCII protocol
139 to connect
140 .Nm
141 to postfix as a "Before-Queue Content Filter."
142 See the
143 .Fl o
144 flag.
145 .Pp
146 Since the checksums of messages that are whitelisted locally
147 by the
148 .Fl w Ar whiteclnt
149 file are not reported to the DCC server,
150 .Nm
151 knows nothing about the total recipient counts for their checksums and
152 so cannot add
153 .Em X-DCC
154 header lines to such messages.
155 .Pp
156 Enable the daemon and put its parameters in the
157 .Pa dcc_conf
158 file and start the daemon with the
159 .Pa start-dccifd
160 script.
161 .Pp
162 The list of servers that
163 .Nm
164 contacts is in the memory mapped file
165 .Pa map
166 shared by local DCC clients.
167 The file is maintained with
168 .Xr cdcc 8 .
169 .Ss OPTIONS
170 The following options are available:
171 .Bl -tag -width 3n
172 .It Fl V
173 displays the version of
174 .Nm .
175 .It Fl d
176 enables debugging output from the DCC client software.
177 Additional
178 .Fl d
179 options increase the number of messages.
180 A single
181 .Fl d
182 aborted SMTP transactions including those from some "dictionary attacks."
183 .It Fl b
184 causes the daemon to not detach itself from the controlling tty
185 and put itself into the background.
186 .It Fl x
187 causes the daemon to try "extra hard" to contact a DCC server.
188 Since it is usually more important to deliver mail than to report its
189 checksums,
190 .Nm
191 normally does not delay too long while trying to contact a DCC server.
192 It will not try again for several seconds after a failure.
193 With
194 .Fl x ,
195 it will always try to contact the DCC server
196 and it will tell the MTA to answer the DATA command with a 4yz
197 temporary failure.
198 .It Fl A
199 adds to existing X-DCC headers in the message
200 instead of replacing existing headers
201 of the brand of the current server.
202 .It Fl N
203 neither adds, deletes, nor replaces existing X-DCC headers in the message.
204 Each message is logged, rejected, and otherwise handled the same.
205 .It Fl Q
206 only queries the DCC server about the checksums of messages
207 instead of reporting and querying.
208 This is useful when
209 .Nm
210 is used to filter mail that has already been reported to a DCC
211 server by another DCC client.
212 No single mail message should be reported to a DCC
213 server more than once per recipient,
214 because each report will increase the apparent "bulkness" of the message.
215 .Pp
216 It is better to use
217 .Em MXDCC
218 lines in the global
219 .Pa whiteclnt
220 file for your MX mail servers that use DCC than
221 .Fl Q .
222 .It Fl G Ar on | off | noIP | IPmask/xx
223 controls
224 .Em greylisting .
225 At least one working greylist server must be listed in the
226 .Pa map
227 file in the DCC home directory.
228 If more than one is named,
229 they must "flood" or change checksums and they must use the
230 same
231 .Fl G
232 parameters.
233 See
234 .Xr dccd 8 .
235 Usually all dccm or dccifd DCC client processes use the same
236 .Fl G
237 parameters.
238 .Pp
239 .Ar IPmask/xx
240 and
241 .Ar noIP
242 remove part or all of the IP address from the greylist triple.
243 The CIDR block size,
244 .Ar xx ,
245 must be between 1 and 128.
246 96 is added to block sizes smaller than 33 to make them appropriate for
247 the IPv6 addresses used by the DCC.
248 .Ar IPmask/96
249 differs from
250 .Ar noIP
251 for IPv4 addresses,
252 because the former retains the IPv4 to IPv6 mapping prefix.
253 .It Fl h Ar homedir
254 overrides the default DCC home directory,
255 .Pa @prefix@ .
256 .It Fl I Ar user
257 specifies the UID and GID of the process.
258 .It Fl p Ar /sock/name | host,port,rhost/bits
259 overrides the default address at which programs contact
260 .Nm dccifd .
261 The default is a UNIX domain socket named dccifd in the DCC home directory.
262 .Pp
263 The second form specifies a local host name or IP address,
264 a local TCP port number,
265 and the host names or IP addresses of computers that can use
266 .Nm dccifd .
267 127.0.0.1 or
268 .Em localhost
269 are common choices for
270 .Ar host .
271 The string
272 .Ar @
273 specifies IN_ADDRANY or all local IP addresses.
274 127.0.0.0/8 is a common choice for
275 .Ar rhost/bits .
276 .It Fl o Ar /sock | host,port
277 enables SMTP proxy mode instead of the ASCII protocol
278 and specifies the output connection when
279 .Nm
280 acts as an SMTP proxy.
281 It is the address of the SMTP server
282 for which
283 .Nm
284 acts as SMTP client.
285 When
286 .Ar /sock
287 is
288 .Pa /dev/null ,
289 .Nm
290 acts as if there were downstream SMTP server that always answers "250\ ok".
291 The string
292 .Ar @
293 specifies the same IP address as the incoming TCP connection.
294 .Pp
295 The input to
296 .Nm
297 in SMTP proxy mode is specified with
298 .Fl -p .
299 For example,
300 .Fl p Ar 127.0.0.1,10025,127.0.0.1/32 Fl o Ar 127.0.0.1,10026
301 could be used to connect
302 .Nm
303 with Postfix as described in the documentation in version 2.2.1 Postfix
304 documentation.
305 .Pp
306 See below concerning the subset of ESMTP used in this mode.
307 .It Fl m Ar map
308 specifies a name or path of the memory mapped parameter file instead
309 of the default
310 .Pa map
311 file in the DCC home directory.
312 It should be created with the
313 .Xr cdcc 8
314 command.
315 .It Fl w Ar whiteclnt
316 specifies an optional file containing filtering parameters
317 as well as SMTP client IP addresses,
318 SMTP envelope values, and header values
319 of mail that is spam or is not spam and does not need a
320 .Em X-DCC
321 header,
322 and whose checksums should not be reported to the DCC server.
323 .Pp
324 If the pathname
325 .Ar whiteclnt
326 is not absolute, it is relative to the DCC home directory.
327 .Pp
328 The format of the
329 .Nm
330 whiteclnt file is the same as the
331 .Pa whitelist
332 files used by
333 .Xr dbclean 8
334 and the
335 .Pa whiteclnt
336 file used by
337 .Xr dccproc 8 .
338 See
339 .Xr dcc 8
340 for a description of DCC white and blacklists.
341 Because the contents of the
342 .Ar whiteclnt
343 file are used frequently, a companion file is automatically
344 created and maintained.
345 It has the same pathname but with an added suffix of
346 .Ar .dccw
347 and contains a memory mapped hash table of the main file.
348 .Pp
349 A whitelist entry ("OK") or two or more semi-whitelistings ("OK2")
350 for one of the message's checksums prevents all of
351 the message's checksums from being reported to the DCC server
352 and the addition of a
353 .Em X-DCC
354 header line by
355 .Nm
356 A whitelist entry for a checksum
357 also prevents rejecting or discarding the message based on DCC recipient
358 counts as specified by
359 .Fl a
360 and
361 .Fl t .
362 Otherwise, one or more checksums with blacklisting entries ("MANY") cause
363 all of the message's
364 checksums to be reported to the server with an addressee count of "MANY".
365 .Pp
366 If the message has a single recipient, an
367 .Ar env_To
368 .Ar whiteclnt
369 entry of "OK" for the checksum of its recipient address acts like any other
370 .Ar whiteclnt
371 entry of "OK."
372 When the SMTP message has more than one recipient,
373 the effects can be complicated.
374 When a message has several recipients with some but not all listed in the
375 .Ar whiteclnt
376 file,
377 .Nm
378 tries comply with the wishes of the users who want filtering as
379 well as those who don't by silently not delivering the message to
380 those who want filtering (i.e. are not whitelisted) and delivering
381 the message to don't want filtering.
382 .It Fl U Ar userdirs
383 enables per-user
384 .Pa whiteclnt
385 files and log directories.
386 Each target of a message can have a directory of log files named
387 .Ar userdirs/addr/log
388 where
389 .Ar addr
390 is the local user or mailbox name computed by the MTA.
391 The name of each user's log directory must be
392 .Ar log .
393 If it is not absolute,
394 .Ar userdirs
395 is relative to the DCC home directory.
396 The directory containing the log files must be named
397 .Ar log
398 and it must be writable by the
399 .Nm
400 process.
401 Each log directory must exist or logging for the corresponding
402 is silently disabled.
403 The files created in the log directory are owned by the UID of the
404 .Nm
405 process,
406 but they have
407 .Em group
408 and
409 .Em other
410 read and write permissions copied from the corresponding
411 .Ar log
412 directory.
413 To ensure the privacy of mail,
414 it may be good to make the directories readable only by
415 .Em owner
416 and
417 .Em group ,
418 and to use a
419 .Xr cron
420 script that changes the owner of each file to match the grandparent
421 .Ar addr
422 directory.
423 .Pp
424 There can also be a per -user whitelist file named
425 .Ar userdirs/addr/whiteclnt
426 for each address
427 .Ar addr.
428 Any checksum that is not white- or blacklisted by an individual
429 addressee's
430 .Pa whiteclnt
431 file is checked in the main
432 .Fl w whiteclnt
433 file.
434 A missing per-addressee
435 .Ar whiteclnt
436 file is the same as an empty file.
437 Relative paths for files included in per-addressee files
438 are resolved in the DCC home directory.
439 The
440 .Ar whiteclnt
441 files and the
442 .Ar addr
443 directories containing them must be writable by the
444 .Nm
445 process.
446 .Pp
447 .Ar Option
448 lines in per-user whiteclnt files can be used to modify many aspects of
449 .Nm
450 filtering,
451 as described in the main
452 .Xr dcc
453 man page.
454 For example, an
455 .Ar option dcc-off
456 line turns off DCC filtering for individual mailboxes.
457 .It Fl a Ar IGNORE | REJECT | DISCARD
458 specifies the action taken when
459 .Nm
460 is in proxy mode with
461 .Fl o
462 and
463 DCC server counts or
464 .Fl t
465 thresholds say that a message is unsolicited and bulk.
466 .Ar IGNORE
467 causes the message to be unaffected except for adding the
468 .Em X-DCC
469 header line to the message.
470 This turns off DCC filtering.
471 .Pp
472 Spam can also be
473 .Ar REJECT Ns ed
474 or (when in proxy mode with
475 .Fl o )
476 accepted and silently
477 .Ar DISCARD Ns ed
478 without being delivered to local mailboxes.
479 The default is
480 .Ar REJECT .
481 .Pp
482 Mail forwarded via IP addresses marked
483 .Em MX
484 or
485 .Em MXDCC
486 in the main
487 .Pa whiteclnt
488 file is treated
489 as if
490 .Fl a Ar DISCARD
491 were specified.
492 This prevents "bouncing" spam.
493 .Pp
494 The effects of the
495 .Fl w Ar whiteclnt
496 are not affected by
497 .Fl a .
498 .It Fl t Xo
499 .Sm off
500 .Ar type,
501 .Op Ar log-thold,
502 .Ar rej-thold
503 .Sm on
504 .Xc
505 sets logging and "spam" thresholds for checksum
506 .Ar type .
507 The checksum types are
508 .Ar IP ,
509 .Ar env_From ,
510 .Ar From ,
511 .Ar Message-ID ,
512 .Ar substitute ,
513 .Ar Received ,
514 .Ar Body ,
515 .Ar Fuz1 ,
516 .Ar Fuz2 ,
517 .Ar rep-total ,
518 and
519 .Ar rep .
520 The first six,
521 .Ar IP
522 through
523 .Ar substitute ,
524 have no effect except when a local DCC server configured with
525 .Fl K
526 is used.
527 The
528 .Ar substitute
529 thresholds apply to the first substitute heading encountered in the mail
530 message.
531 The string
532 .Ar ALL
533 sets thresholds for all types, but is unlikely to be useful except for
534 setting logging thresholds.
535 The string
536 .Ar CMN
537 specifies the commonly used checksums
538 .Ar Body ,
539 .Ar Fuz1 ,
540 and
541 .Ar Fuz2 .
542 .Ar Rej-thold
543 and
544 .Ar log-thold
545 must be numbers, the string
546 .Ar NEVER ,
547 or the string
548 .Ar MANY
549 indicating millions of targets.
550 Counts from the DCC server as large as the threshold for any single type
551 are taken as sufficient evidence
552 that the message should be logged or rejected.
553 .Pp
554 .Ar Log-thold
555 is the threshold at which messages are logged.
556 It can be handy to log messages at a lower threshold to find
557 solicited bulk mail sources such as mailing lists.
558 If no logging threshold is set,
559 only rejected mail and messages with complicated combinations of white
560 and blacklisting are logged.
561 Messages that reach at least one of their rejection thresholds are
562 logged regardless of logging thresholds.
563 .Pp
564 .Ar Rej-thold
565 is the threshold at which messages are considered "bulk,"
566 and so should be rejected or discarded if not whitelisted.
567 .Pp
568 DCC Reputation thresholds in the commercial version
569 of the DCC are controlled by thresholds on checksum types
570 .Ar rep
571 and
572 .Ar rep-total .
573 Messages from an IP address that the DCC database says has sent
574 more than
575 .Fl t Ar rep-total,log-thold
576 messages are logged.
577 A DCC Reputation is computed for messages received
578 from IP addresses that
579 have sent more than
580 .Fl t Ar rep-total,log-thold
581 messages.
582 The DCC Reputation of an IP address is the percentage of its messages
583 that have been detected as bulk
584 or having at least 10 recipients.
585 The defaults are equivalent to
586 .Fl t Ar rep,never
587 and
588 .Fl t Ar rep-total,never,20 .
589 .Pp
590 Bad DCC Reputations do not reject mail unless enabled by an
591 .Ar option DCC-rep-on
592 line in a
593 .Pa whiteclnt
594 file.
595 .Pp
596 The checksums of locally whitelisted messages are not checked with
597 the DCC server and so only the number of targets of the current copy of
598 a whitelisted message are compared against the thresholds.
599 .Pp
600 The default is
601 .Ar ALL,NEVER ,
602 so that nothing is discarded, rejected, or logged.
603 A common choice is
604 .Ar CMN,25,50
605 to reject or discard
606 mail with common bodies except as overridden by
607 the whitelist of the DCC server, the sendmail
608 .Em ${dcc_isspam}
609 and
610 .Em ${dcc_notspam}
611 macros, and
612 .Fl g ,
613 and
614 .Fl w .
615 .It Fl g Xo
616 .Sm off
617 .Op Ar not-
618 .Ar type
619 .Sm on
620 .Xc
621 indicates that whitelisted,
622 .Ar OK
623 or
624 .Ar OK2 ,
625 counts from the DCC server for a type of checksum are to be believed.
626 They should be ignored if prefixed with
627 .Ar not- .
628 .Ar Type
629 is one of the same set of strings as for
630 .Fl t .
631 Only
632 .Ar IP ,
633 .Ar env_From ,
634 and
635 .Ar From
636 are likely choices.
637 By default all three are honored,
638 and hence the need for
639 .Ar not- .
640 .It Fl S Ar hdr
641 adds to the list of substitute or locally chosen headers that
642 are checked with the
643 .Fl w Ar whiteclnt
644 file and sent to the DCC server.
645 The checksum of the last header of type
646 .Ar hdr
647 found in the message is checked.
648 .Ar Hdr
649 can be
650 .Em HELO
651 to specify the SMTP envelope HELO value.
652 .Ar Hdr
653 can also be
654 .Em mail_host
655 to specify the host name from
656 the Mail_from value in the SMTP envelope.
657 As many as six different substitute headers can be specified, but only
658 the checksum of the first of the six will be sent to the DCC server.
659 .It Fl l Ar logdir
660 specifies a directory in which files containing copies of messages processed by
661 .Nm
662 are kept.
663 They can be copied to per-user directories specified with
664 .Fl U .
665 Information about other recipients of a message is deleted from
666 the per-user copies.
667 .Pp
668 See the FILES section below concerning the contents of the files.
669 See also the
670 .Ar option log-subdirectory-{day,hour,minute}
671 lines in
672 .Pa whiteclnt
673 files described in
674 .Xr dcc 8 .
675 .Pp
676 The directory is relative to the DCC home directory if it is not absolute
677 .It Fl R Ar rundir
678 specifies the "run" directory where the file
679 containing the daemon's process ID is stored.
680 The default value is
681 .Pa @dcc_rundir@ .
682 .It Fl T Ar tmpdir
683 changes the default directory for temporary files from the default.
684 The default is the directory specified with
685 .Fl l
686 or the system default if
687 .Fl l
688 is not used.
689 The system default is often
690 .Pa /tmp .
691 .It Fl D Ar local-domain
692 specifies a host or domain name by which the system is known.
693 There can be several
694 .Fl D
695 settings.
696 .Pp
697 To find the per-user log directory and whitelist for each mail recipient,
698 .Nm
699 must know each recipient's user name.
700 The ASCII protocol used between
701 .nm
702 and the MTA includes an optional user name with each
703 SMTP recipient address.
704 When the user name is absent when the ASCII protocol is used or when
705 the subset of ESMTP enabled with
706 .Fl o
707 is used,
708 and when the SMTP recipient address includes an
709 .Em at sign
710 (@)
711 each mail address is checked against the
712 list of
713 .Ar local-domain Ns s.
714 The part of the recipient address remaining after longest matching
715 .Ar local-domain
716 (if any) is taken as the user name.
717 The match is anchored at the right or the end of the recipient address.
718 It must start at a period (.) or
719 .Em at sign
720 (@) in the domain name part of the address.
721 .Pp
722 If
723 .Ar local-domain
724 starts with an asterisk (*) indicating a wildcard,
725 preceding sub-domain names are discarded to compute the user name.
726 Otherwise, the computed user name will include any unmatched sub-domain
727 names.
728 .Pp
729 The default value of
730 .Ar local-domain
731 when there are no
732 .Fl D
733 settings is the host name of the system.
734 .It Fl r Ar rejection-msg
735 specifies the rejection message
736 in
737 .Fl o
738 proxy mode
739 for unsolicited bulk mail or for mail temporarily blocked by
740 .Em greylisting
741 when
742 .Fl G
743 is specified.
744 The first
745 .Fl r Ar rejection-msg
746 replaces the default bulk mail rejection message,
747 .Bk -words
748 "5.7.1 550 mail %ID from %CIP rejected by DCC".
749 .Ek
750 ." see rej_def in reply.c
751 The second replaces
752 .Bk -words
753 "4.2.1 452 mail %ID from %CIP temporary greylist embargoed".
754 .Ek
755 ." see grey_def in reply.c
756 The third
757 .Fl r Ar rejection-msg
758 replaces the default SMTP rejection message
759 .Bk -words
760 "5.7.1 550 %ID bad reputation; see http://commercial-dcc.rhyolite.com/cgi-bin/reps.cgi?tgt=%CIP"
761 .Ek
762 for mail with bad DCC Reputations.
763 If
764 .Ar rejection-msg
765 is the zero-length string,
766 the
767 .Fl r
768 setting is counted but the corresponding message is not changed.
769 .Pp
770 .Ar Rejection-msg
771 can contain specific information about the mail message.
772 The following strings starting with % are replaced with the corresponding
773 values:
774 .Bl -tag -width "%BRESULT" -offset 4n -compact
775 .It %ID
776 message ID such as the unique part of log file name or sendmail queue ID
777 .It %CIP
778 SMTP client IP address
779 .It %BTYPE
780 type of DNS blacklist hit, such as "SMTP client", "mail_host", or "URL NS"
781 .It %BTGT
782 IP address or name declared bad by DNS blacklist
783 .It %BPROBE
784 domain name found in DNS blacklist such as 4.3.2.10.example.com
785 .It %BRESULT
786 value of the %BPROBE domain name found in DNS blacklist
787 .El
788 .Pp
789 A common alternate for the bulk mail rejection message is
790 .Bk -words
791 "4.7.1 451 Access denied by DCC"
792 .Ek
793 to tell the sending mail system to continue trying.
794 Use a 4yz response with caution, because it is likely to delay for days
795 a delivery failure message for false positives.
796 If the rejection message
797 does not start with an RFC 1893 status code and RFC 2821 reply code,
798 5.7.1 and 550 or 4.2.1 and 452 are used.
799 .Pp
800 See also
801 .Fl B Ar set:rej-msg=rejection-msg
802 to set the status message for mail rejected by DNS blacklists.
803 .It Fl j Ar maxjobs
804 limits the number of simultaneous requests that will be processed.
805 The default value is the maximum number that seems to be possible given system
806 limits on open files, select() bit masks, and so forth.
807 Start
808 .Nm
809 with
810 .Fl d
811 and see the starting message in the system log to see the limit.
812 .It Fl B Ar dnsbl-option
813 enables DNS blacklist checks of the SMTP client IP address, SMTP envelope
814 Mail_From sender domain name, and of host names in URLs in the message body.
815 Body URL blacklisting has too many false positives to use on
816 abuse mailboxes.
817 It is less effective than greylisting with
818 .Xr dccm 8
819 or
820 .Xr dccifd 8
821 but can be useful in situations where
822 greylisting cannot be used.
823 .Pp
824 .Ar Dnsbl-option
825 is either one of the
826 .Fl B Ar set:option
827 forms or
828 .Bd -literal -compact -offset 4n
829 .Fl B Xo
830 .Sm off
831 .Ar domain Oo Ar ,IPaddr
832 .Op Ar /xx Op Ar ,bltype Oc
833 .Sm on
834 .Xc
835 .Ed
836 .Ar Domain
837 is a DNS blacklist domain such as example.com
838 that will be searched.
839 .Ar IPaddr Ns Op Ar /xxx
840 is the string "any"
841 an IP address in the DNS blacklist
842 that indicates that the mail message
843 should be rejected,
844 or a CIDR block covering results from the DNS blacklist.
845 "127.0.0.2" is assumed if
846 .Ar IPaddr
847 is absent.
848 IPv6 addresses can be specified with the usual colon (:) notation.
849 Names can be used instead of numeric addresses.
850 The type of DNS blacklist
851 is specified by
852 .Ar bltype
853 as
854 .Ar name ,
855 .Ar IPv4 ,
856 or
857 .Ar IPv6 .
858 Given an envelope sender domain name or a domain name in a URL of
859 spam.domain.org
860 and a blacklist of type
861 .Ar name ,
862 spam.domain.org.example.com will be tried.
863 Blacklist types of
864 .Ar IPv4
865 and
866 .Ar IPv6
867 require that the domain name in a URL sender address
868 be resolved into an IPv4 or IPv6
869 address.
870 The address is then written as a reversed string of decimal
871 octets to check the DNS blacklist, as in 2.0.0.127.example.com,
872 .Pp
873 More than one blacklist can be specified and blacklists can be grouped.
874 All searching within a group is stopped at the first positive result.
875 .Pp
876 Positive results are ignored after being logged unless an
877 .Ar option\ DNSBL-on
878 line appears in the global or per-user
879 .Pa whiteclnt
880 file.
881 .Pp
882 .Bl -tag -width 3n
883 .It Fl B Ar set:no-client
884 says that SMTP client IP addresses and reverse DNS domain names should
885 not be checked in the following blacklists.
886 .br
887 .Fl B Ar set:client
888 restores the default for the following blacklists.
889 .It Fl B Ar set:no-mail_host
890 says that SMTP envelope Mail_From sender domain names should
891 not be checked in the following blacklists.
892 .Fl B Ar set:mail_host
893 restores the default.
894 .It Fl B Ar set:no-URL
895 says that URLs in the message body should not be checked in the
896 in the following blacklists.
897 .Fl B Ar set:URL
898 restores the default.
899 .It Fl B Ar set:no-MX
900 says MX servers of sender Mail_From domain names and host names in URLs
901 should not be checked in the following blacklists.
902 .br
903 .Fl B Ar set:MX
904 restores the default.
905 .It Fl B Ar set:no-NS
906 says DNS servers of sender Mail_From domain names and host names in URLs
907 should not be checked in the following blacklists.
908 .Fl B Ar set:NS
909 restores the default.
910 .It Fl B Ar set:defaults
911 is equivalent to all of
912 .Fl B Ar set:no-temp-fail
913 .Fl B Ar set:client
914 .br
915 .Fl B Ar set:mail_host
916 .Fl B Ar set:URL
917 .Fl B Ar set:MX
918 and
919 .Fl B Ar set:NS
920 .It Fl B Ar set:group=X
921 adds later DNS blacklists specified with
922 .Bd -literal -compact -offset 4n
923 .Fl B Xo
924 .Sm off
925 .Ar domain Oo Ar ,IPaddr
926 .Op Ar /xx Op Ar ,bltype Oc
927 .Sm on
928 .Xc
929 .Ed
930 to group 1, 2, or 3.
931 .It Fl B Ar set:debug=X
932 sets the DNS blacklist logging level
933 .It Fl B Ar set:msg-secs=S
934 limits
935 .Nm
936 to
937 .Ar S
938 seconds total for checking all DNS blacklists.
939 The default is 25.
940 .It Fl B Ar set:URL-secs=S
941 limits
942 .Nm
943 to at most
944 .Ar S
945 seconds resolving and checking any single URL.
946 The default is 11.
947 Some spam contains dozens of URLs and that
948 some "spamvertised" URLs contain host names that need minutes to
949 resolve.
950 Busy mail systems cannot afford to spend minutes checking each incoming
951 mail message.
952 .It Fl B Ar set:rej-msg=rejection-msg
953 sets the SMTP rejection message for the following blacklists.
954 .Ar Rejection-msg
955 must be in the same format as for
956 .Fl r .
957 If
958 .Ar rejection-msg
959 is null, the default is restored.
960 The default DNS blacklist rejection message is the first message set
961 with
962 .Fl r .
963 .It Fl B Ar set:temp-fail
964 causes
965 .Nm
966 to the MTA to answer the SMTP DATA command with
967 .Bd -literal -offset 3n -compact
968 452 4.2.1 mail %ID from %CIP temporary delayed for DNSBL
969 .Ed
970 if any DNS answer required for a DNSBL in the current group times out,
971 including resolving names in URLs.
972 .It Fl B Ar set:no-temp-fail
973 restores the default of assuming a negative answer for DNS responses
974 that take too long.
975 .It Fl B Ar set:maxjobs=X
976 sets maximum number of helper processes to
977 .Ar X .
978 In order to use typical single-threaded DNS resolver libraries,
979 .Nm
980 uses fleets of helper processes.
981 It is rarely a good idea to change the default,
982 which is the same as the maximum number of simultaneous jobs set with
983 .Fl j .
984 .It Fl B Ar set:progpath=@libexecdir@/dns-helper
985 changes the path to the helper program.
986 .El
987 .It Fl L Ar ltype,facility.level
988 specifies how messages should be logged.
989 .Ar Ltype
990 must be
991 .Ar error ,
992 .Ar info ,
993 or
994 .Ar off
995 to indicate which of the two types of messages are being controlled or
996 to turn off all
997 .Xr syslog 3
998 messages from
999 .Nm .
1000 .Ar Level
1001 must be a
1002 .Xr syslog 3
1003 level among
1004 .Ar EMERG ,
1005 .Ar ALERT ,
1006 .Ar CRIT , ERR ,
1007 .Ar WARNING ,
1008 .Ar NOTICE ,
1009 .Ar INFO ,
1010 and
1011 .Ar DEBUG .
1012 .Ar Facility
1013 must be among
1014 .Ar AUTH ,
1015 .Ar AUTHPRIV ,
1016 .Ar CRON ,
1017 .Ar DAEMON ,
1018 .Ar FTP ,
1019 .Ar KERN ,
1020 .Ar LPR ,
1021 .Ar MAIL ,
1022 .Ar NEWS ,
1023 .Ar USER ,
1024 .Ar UUCP ,
1025 and
1026 .Ar LOCAL0
1027 through
1028 .Ar LOCAL7 .
1029 The default is equivalent to
1030 .Dl Fl L Ar info,MAIL.NOTICE Fl L Ar error,MAIL.ERR
1031 .El
1032 .Pp
1033 .Nm
1034 normally sends counts of mail rejected and so forth to the system log at
1035 midnight.
1036 The SIGUSR1 signal sends an immediate report to the system log.
1037 The reports will be repeated every 24 hours at the same minute as the signal
1038 instead of at midnight.
1039 .Ss Protocol
1040 .Nm Dccifd
1041 uses a simple ASCII protocol to receive mail messages to be checked and
1042 to return results.
1043 For each message, the MTA must open a connection to the interface daemon,
1044 send options, envelope recipients, and the message, receive the results,
1045 and close the connection.
1046 .Pp
1047 Instead of the ASCII protocol, a subset of ESMTP is enabled by
1048 .Fl o .
1049 Only the familiar HELO, EHLO, Mail, Rcpt, DATA, RSET, and QUIT
1050 commands and the Postfix extensions XFORWARD and XCLIENT are honored.
1051 Since SMTP has no provisions for user names,
1052 the protocol enabled by
1053 .Fl o
1054 depends on a list of local domain names specified with
1055 .Fl D
1056 to find per-user log directories and whitelist files.
1057 If neither XFORWARD nor XCLIENT are used,
1058 .Nm
1059 uses the IP address of the MTA and the value of the HELO command.
1060 .Pp
1061 In the ASCII protocol, each of the following lines are sent in order to
1062 .Nm .
1063 Each ends with a newline ('\\n') character.
1064 .Bl -tag -offset 2n -width "recipients" -compact
1065 .It options
1066 zero or more blank-separated strings among:
1067 .Bl -tag -offset 2n -width grey-query -compact
1068 .It Ar spam
1069 the message is already known to be spam
1070 .It Ar body
1071 return all of the headers with the added
1072 .Em X-DCC
1073 header line and the body
1074 .It Ar header
1075 return the
1076 .Em X-DCC
1077 header
1078 .It Ar query
1079 ask the DCC server about the message without reporting it, as if
1080 .Nm
1081 were running with
1082 .Fl Q .
1083 .It Ar grey-query
1084 only query the greylist server for this message.
1085 .Fl G Ar on
1086 must be in use.
1087 .It Ar no-reject
1088 suppress the overall, one character line 'R' result.
1089 This can be useful when using
1090 .Nm
1091 only for greylisting.
1092 .It Ar log
1093 ensure that this message is logged as if
1094 .Nm
1095 were running with
1096 .Fl t all,0,
1097 .El
1098 .It client
1099 IP address of the SMTP client in a "dotted" or "coloned" ASCII string
1100 and reverse-DNS host name.
1101 If the host name is present,
1102 it must follow a carriage return character ('\\r') after the IP address.
1103 The client IP address must be present and non-null if the host name is present.
1104 The string "0.0.0.0\\n" is understood the same as the null string,
1105 meaning that both the IP address and host name are absent.
1106 If the client IP address is absent, then the IP address and host name
1107 are taken from the first non-local Received header if it has the standard
1108 "name (name [IP address])..." format.
1109 Non-standard Received headers commonly added by qmail as well as
1110 Received headers specifying IP addresses marked
1111 .Em MX
1112 or
1113 .Em MXDCC
1114 in the global
1115 .Fl w Ar whiteclnt
1116 file are skipped.
1117 .It HELO
1118 SMTP HELO value or nothing, followed by a newline ('\\n') character.
1119 If the HELO value is null and the IP address of the SMTP client are not
1120 supplied, they will be
1121 taken from the same Received: header that supplies the IP address.
1122 .It sender
1123 or SMTP
1124 .Em Mail From
1125 command value for the env_from checksum.
1126 If the sender is null,
1127 the contents of the first Return-Path: or UNIX style From_ header
1128 is used.
1129 .It recipients
1130 or SMTP
1131 .Em Rcpt To
1132 recipient mailboxes followed by corresponding local user names,
1133 one (mailbox,user) pair to a line.
1134 Each optional local user name is separated from the
1135 corresponding mailbox recipient address by a carriage return ('\\r').
1136 A local user name can be null if it is not known, but each recipient
1137 mailbox must be non-null.
1138 If there are no lines of (mailbox,user) pairs and if the
1139 .Ar spam
1140 option is not included, then the
1141 .Ar query
1142 is assumed.
1143 Mailboxes without user names will lack per-user log files
1144 and will not invoke a per-user whitelist.
1145 .El
1146 .Pp
1147 The last recipient-user name pair is followed by an empty line
1148 and the headers and body of the message.
1149 The end of the body of the mail message is signaled by the MTA
1150 half-closing the connection.
1151 See
1152 .Xr shutdown 2 .
1153 .Pp
1154 .Nm Dccifd
1155 responds with three things.
1156 First is a one character line of the overall result advising the MTA:
1157 .Bl -tag -offset 2n -width 3n -compact
1158 .It A
1159 accept the message for all recipients and answer the SMTP DATA command
1160 with a 2yz result.
1161 .It G
1162 answer with a 4yz result to embargo the message for greylisting.
1163 .It R
1164 reject the message and answer the DATA command with a 5yz result.
1165 .It S
1166 accept the message for some recipients
1167 and so answer the DATA command with a 2yz result.
1168 .It T
1169 temporary failure by the DCC system and so answer with a 4yz result.
1170 .El
1171 .Pp
1172 Second is a line of characters indicating the disposition of the
1173 message for each corresponding recipient:
1174 .Bl -tag -offset 2n -width 3n -compact
1175 .It A
1176 deliver the message
1177 .It G
1178 discard the message during a greylist embargo
1179 .It R
1180 discard the message as spam
1181 .El
1182 The SMTP protocol allows only a single
1183 result for the DATA command for all recipients that were not rejected
1184 before body of the message was offered with the DATA command.
1185 To accept the message for some recipients and reject it for others,
1186 the MTA must tell the SMTP client it is accepting the message for all
1187 recipients and then discard it for those that would reject it.
1188 .Pp
1189 Finally, if the
1190 .Em body
1191 or
1192 .Em header
1193 strings are in the first line of
1194 .Em options
1195 sent by the MTA to the daemon,
1196 then the
1197 .Em X-DCC
1198 header line
1199 or the entire body with the
1200 .Em X-DCC
1201 header line follows.
1202 .Sh FILES
1203 .Bl -tag -width dccifd.pid -compact
1204 .It Pa @prefix@
1205 is the DCC home directory in which other files are found.
1206 .It Pa @libexecdir@/start-dccifd
1207 and
1208 .It Pa @libexecdir@/rcDCC
1209 are scripts used to start the daemon.
1210 .It Pa dcc/dcc_conf
1211 contains parameters used by the scripts to start DCC daemons and cron jobs.
1212 .It Pa logdir
1213 is an optional directory specified with
1214 .Fl l
1215 and containing marked mail.
1216 Each file in the directory contains one message, at least one of whose
1217 checksums reached its
1218 .Fl t
1219 thresholds or that is interesting for some other reason.
1220 Each file starts with lines containing the date when the message
1221 was received, the IP address of the SMTP client, and SMTP envelope
1222 values.
1223 Those lines are followed by the body of the SMTP message including its header
1224 as it was received.
1225 Only approximately the first 32 KBytes of the body are recorded
1226 unless modified by
1227 .Em ./configure --with-max-log-size=xx
1228 The checksums for the message follow the body.
1229 They are followed by lines indicate that
1230 one of the checksums is white- or blacklisted by the
1231 .Fl w Ar whiteclnt
1232 file.
1233 Each log file ends with the
1234 .Em X-DCC
1235 header line added to the message and the disposition of
1236 the message.
1237 .It Pa map
1238 is the memory mapped file of information concerning DCC servers
1239 in the DCC home directory.
1240 .It Pa whiteclnt
1241 contains the client whitelist in
1242 the format described in
1243 .Xr dcc 8 .
1244 .It Pa whiteclnt.dccw
1245 is a memory mapped hash table of the
1246 .Pa whiteclnt
1247 file.
1248 .It Pa dccifd.pid
1249 in the
1250 .Fl R Ar rundir
1251 directory contains daemon's process ID.
1252 .El
1253 .Sh EXAMPLES
1254 Dccifd can be used as Postfix Before-Queue Content filter.
1255 In some tests these
1256 values for
1257 .Fl p
1258 and
1259 .Fl o
1260 in
1261 .Pa dcc_conf .
1262 .Bd -literal -offset 4n
1263 DCCIFD_ENABLE=on
1264 DCCIFD_ARGS="-p 127.0.0.1,10025,127.0.0.1/32 -o 127.0.0.1,10026
1265 .Ed
1266 .Pp
1267 worked with these lines in /etc/postfix/master.cf
1268 .Bd -literal -offset 4n
1269 smtp inet n - n - - smtpd
1270 -o smtpd_proxy_filter=127.0.0.1:10025
1271 127.0.0.1:10026 inet n - n - - smtpd
1272 -o smtpd_authorized_xforward_hosts=127.0.0.0/8
1273 -o smtpd_client_restrictions=
1274 -o smtpd_helo_restrictions=
1275 -o smtpd_sender_restrictions=
1276 -o smtpd_recipient_restrictions=permit_mynetworks,reject
1277 -o smtpd_data_restrictions=
1278 -o mynetworks=127.0.0.0/8
1279 -o receive_override_options=no_unknown_recipient_checks
1280 .Ed
1281 .Sh SEE ALSO
1282 .Xr cdcc 8 ,
1283 .Xr dbclean 8 ,
1284 .Xr dcc 8 ,
1285 .Xr dccd 8 ,
1286 .Xr dblist 8 ,
1287 .Xr dccm 8 ,
1288 .Xr dccproc 8 ,
1289 .Xr dccsight 8 ,
1290 .Sh HISTORY
1291 Implementation of
1292 .Nm
1293 Distributed Checksum Clearinghouses are based on an idea of Paul Vixie
1294 with code designed and written at Rhyolite Software starting in 2000.
1295 was started at Rhyolite Software in 2002.
1296 This document describes version 1.3.103.
1297 .Sh BUGS
1298 .Nm
1299 uses
1300 .Fl t
1301 where
1302 .Xr dccproc 8
1303 uses
1304 .Fl c .
1305 .Pp
1306 By default
1307 .Nm
1308 look for its UNIX domain socket in the DCC home directory,
1309 but
1310 .Xr dccm 8
1311 looks in its
1312 .Fl R Ar rundir .
1313 .Pp
1314 Systems without
1315 .Xr setrlimit 2
1316 and
1317 .Xr getrlimit 2
1318 RLIMIT_NOFILE
1319 can have problems with the default limit on the number of simultaneous
1320 jobs, the value of
1321 .Fl j .
1322 Every job requires four open files.
1323 These problems are usually seen with errors messages that say something like
1324 .Dl dccifd[24448]: DCC: accept(): Result too large
1325 A fix is to use a smaller value for
1326 .Fl j
1327 or to allow
1328 .Nm
1329 to open more files.