dccd(8)

NAME

dccd - Distributed Checksum Clearinghouse Daemon

SYNOPSIS

dccd [-64dVbfFQ] -i server-ID [-n brand] [-h homedir]
     [-a  [server-addr][,server-port]]  [-I   host-ID]   [-q
qsize]
     [-G
[on,][weak-body,][weak-IP,][embargo][,wait][,white]]
     [-t [type],threshold] [-K [no-]type] [-T tracemode] [-u
anon-delay[*inflate]] [-C dbclean] [-L ltype,facility.level]
     [-R [RL_SUB],[RL_ANON],[RL_ALL_ANON],[RL_BUGS]]

DESCRIPTION

Dccd receives reports of checksums related to mail received

by DCC clients and queries about the total number of reports of

particular checksums. A DCC server never receives mail, address,

headers, or other information from clients, but only cryptograph

ically secure checksums of such information. A DCC server cannot

determine the text or other information that corresponds to the

checksums it receives. It only acts as a clearinghouse of total

counts of checksums computed by clients.

Each DCC server or close cluster of DCC servers is identi

fied by a numeric server-ID. Each DCC client is identified by a

client-ID, either explicitly listed in the ids file or the spe

cial anonymous client-ID. Many computers are expected to share a

single client-ID. A server-ID is less than 32768 while a

client-ID is between 32768 and 16777215. DCC server-IDs need be

known only to DCC servers and the people running them. The pass

words associated with DCC server-IDs should be protected, because

DCC servers listen to commands authenticated with server-IDs and

their associated passwords. Each client that does not use the

anonymous ID must know the client-ID and password used by each of

its servers. A single client computer can use different pass

words with different server computers. See the ids file.

A whitelist of known good (or bad) sources of email prevents

legitimate mailing lists from being seen as unsolicited bulk

email by DCC clients. The whitelist used by a DCC server is

built into the database when old entries are removed by db

clean(8). Each DCC client has its own, local whitelist, and in

general, whitelists work better in DCC clients than servers.

The effectiveness of a Distributed Checksum Clearinghouse

increases as the number of subscribers increases. Flooding re

ports of checksums among DCC servers increases the effective num

ber of subscribers to each server. Each dccd daemon tries to

maintain TCP/IP connections to the other servers listed in the

flod file, and send them reports containing checksums with total

counts exceeding thresholds. Changes in the flod file are no

ticed automatically within minutes.

Controls on report flooding are specified in the flod file.

Each line specifies a hostname and port number to which reports

should be flooded, a server-ID to identify and authenticate the

output stream, a server-ID to identify and authenticate an input

stream from the same server, and flags with each ID. The ability

to delete reports of checksums is handy, but could be abused. If

del is not present among the in-opts options for the incoming ID,

incoming delete requests are logged and then ignored. Floods

from DCC "brands" that count only mail to "spam traps" and whose

servers use the -Q option to count extremely "bulk" mail should

be marked with traps. They can be seen as counting millions of

targets, so the traps flag on their flod file entry changes their

incoming flooded reports counts to "many."

Dccd automatically checks its flod and ids files periodical

ly. Cdcc(8) has the server commands new ids and flood check to

tell dccd to check those two files immediately. Both files are

also checked for changes in response to the SIGHUP signal.

OPTIONS

The following options are available:

-6 enable IPv6. The default is equivalent to -4. See al

so the IPv4 and IPv6 options in the flod file.

-4 disable IPv6. See also -6.

-d enables debugging output. Additional -d options in

crease the number of messages.

-V displays the version of the DCC server daemon.

-b causes the server to not detach itself from the con

trolling tty or put itself into the background.

-F uses read() and write() instead of mmap() in some cases

to access the DCC database. It is never the default.

-f turns off -F.

-Q causes the server to treat reports of checksums as

queries except from DCC clients marked trusted in the ids file

with rpt-ok. See -u to turn off access by anonymous or unauthen

ticated clients

-i server-ID

specifies the ID of this DCC server. Each server iden

tifies itself as responsible for checksums that it forwards to

other servers.

-n brand

is an arbitrary string of letters and numbers that

identifies the organization running the DCC server. The brand is

required, and appears in the SMTP X-DCC headers generated by the

DCC.

-h homedir

overrides the default DCC home directory, which is of

ten /var/dcc.

-a [server-addr][,server-port]

adds an hostname or IP address to the list of local IP

addresses that the server answers. Multiple -a options can be

used to specify a subset of the available network interfaces or

to use more than one port number. The default is to listen on

all local IP addresses. It can be useful to list some or all of

the IP addresses of multi-homed hosts to deal with local or re

mote firewalls. By default server-port is 6277 for DCC servers

and 6276 for Greylist servers. It is the UDP port at which DCC

requests are received and the TCP port for incoming floods of re

ports.

If server-addr is absent and if the getifaddrs(8) func

tion is supported, separate UDP sockets are bound to each config

ured network interface so that each DCC clients receives replies

from the IP addresses to which corresponding request are sent.

If dccd is started before all network interfaces are turned on or

there are interfaces that are turned on and off or change their

addresses such as PPP interfaces, then the special string @

should be used to tell dccd to bind to an IN_ADDRANY UDP socket.

Outgoing TCP connections to flood checksum reports to

other DCC servers used the IP address of a single -a option, but

only if there is single option. Note that this means that -a

-127.0.0.1 breaks flooding, often with "Invalid argument" mes

sages. See also the flod file.

-I host-ID

changes the server's globally unique identity from the

default value consisting of the first 16 characters of the host

name. Host-ID is a string of up to 16 characters to be used in

stead of the first 16 characters of the system's hostname.

-q qsize

specifies the maximum size of the queue of requests

from anonymous or unauthenticated clients. The default value is

the maximum DCC RTT in seconds times 200 or 1000.

-t [type],threshold

sets the threshold below which checksum reports are not

sent or flooded to peer DCC servers. Checksums whose total

counts are less than to the number threshold are not flooded. If

threshold is the string "many," a value of millions is under

stood. It must be at least 10. If type is absent, only the

thresholds for the body checksums are set. The thresholds built

into dccd for the body checksums, Body, Fuz1, and Fuz2 are 20.

The thresholds for the other checksums are so high by default

that by themselves they can never cause reports to be flooded.

The script commonly used to start dccd sets the body thresholds

to one third of DCCM_REJECT_AT in the dcc_conf file but no less

than 10 or more than 20. That is the rejection threshold for dc

cm(8),

This threshold has no direct effect on which checksums

are marked "bulk" by DCC clients. Instead, it allows cooperating

DCC servers to share only the checksums of bulk mail and reduce

inter-server communications. The thresholds should be larger

than the number of addressees of typical private email but not

much larger, because reports of checksums that total less than

their thresholds can be flooded as many extra times as there are

other thresholds.

Reports containing any checksums marked "OK or "OK2"

are not sent to other servers. This reduces the bandwidth needed

for the inter-server flooding, the sizes of DCC database files,

and helps protect the privacy of email of clients of a DCC serv

er.

-G [on,][weak-body,][weak-IP,][embargo][,wait][,white]

changes dccd to a Greylist server for dccm(8) or dc

cifd(8). Greylisting consists of temporarily rejecting or embar

going mail from unfamiliar combinations of SMTP client IP ad

dress, SMTP envelope sender, and SMTP envelope recipient. If the

SMTP client persists for embargo seconds and so is probably not

an "open proxy," worm-infected personal computer, or other tran

sient source of spam, the triple of (IP address,sender,recipient)

is added to a database similar to the usual DCC database. If the

SMTP client does not try again after embargo seconds and before

wait seconds after the first attempt, the triple is forgotten.

If the SMTP client persists past the embargo, the triple is added

to the database and becomes familiar and the message is accepted.

Familiar triples are remembered for white seconds after the last

accepted mail message. The triple is forgotten if it is ever as

sociated with unsolicited bulk email.

All three durations can be a number of minutes, hours,

days, or weeks followed by MINUTES, M, HOURS, H, DAYS, D, WEEKS

or W. The default is -G 270seconds,7days,63days. The first du

ration or the embargo should be longer than open proxies can

linger retransmitting. The second wait time should be as long as

legitimate mail servers persist in retransmitting to recognize

embargoed messages whose retransmissions were not received be

cause of network or other problems. The white time should be

long enough to recognize and not embargo messages from regular

senders.

Usually the DCC greylist system requires that an almost

identical copy of the message be retransmitted during the

embargo. If weak-body is present, any message with the same

triple of sender IP address, sender mail address, and target mail

address ends the embargo.

If weak-IP is present, all mail from an SMTP client at

an IP address is accept after any message from the same IP ad

dress has been accepted.

Unlike DCC checksums, the contents of greylist databas

es are private and do not benefit from broad sharing. However,

large installations can use more two or more greylist servers

flooding triples among themselves. Flooding among greylist

servers is controlled by the grey_flod file.

Note: All greylist cooperating or flooding greylist

servers must use the same -G values.

Clients of greylist servers cannot be anonymous and

must have client-IDs and passwords assigned in the ids file.

White- and blacklists are honored by the DCC clients.

White-listed messages are embargoed or checked with a greylist

server. The greylist triples of blacklisted messages, messages

whose DCC counts make them spam, and other messages known to be

spam are sent to a greylist server to be removed from the

greylist database and cause an embargo on the next messages with

those triples.

Messages whose checksums match greylist server

whitelists are not embargoed and the checksums of their triples

are not added to the greylist database.

The target counts of embargoed messages are reported to

the DCC network to improve the detection of bulk mail.

-K [no-]type

marks checksums of type (not) be "kept" or counted in

the database unless they appear in the whitelist. The default is

equivalent to -K no-all -K Body -K Fuz1 -K Fuz2 to count only the

body checksums.

-T tracemode

causes the server to trace or record some operations.

tracemode must be one of the following:

ALL all tracing
ADMN administrative requests from the control pro

gram, cdcc(8)
ANON errors by anonymous clients
CLNT errors by authenticated clients
RLIM rate-limited messages
QUERY all queries and reports
RIDC some messages concerning the report-ID cache

that is used to detect duplicate reports from clients
FLOOD messages about inter-server flooding
IDS unknown server-IDs in flooded reports
BL requests from clients with IP addresses in the

blacklist file.

The default is ANON CLNT.

-u anon-delay[*inflate]

changes the number of milliseconds anonymous or unau

thenticated clients must wait for answers to their queries and

reports. The purpose of this delay is to discourage anonymous

clients.. The anon-delay is multiplied by 1 plus the number of

recent anonymous requests from an IP address divided by the

inflate value.

The string FOREVER turns off all anonymous or unauthen

ticated access not only for checksum queries and reports but also

cdcc(8) stats requests. A missing value for inflate turns off

inflation.

The default value is 50,none, except when -G is used in

which case FOREVER is assumed and required.

-C dbclean

changes the default name or path of the program used to

rebuild the hash table when it becomes too full. The default

value is libexec/dbclean in the DCC home directory. The value

can include arguments as in -C '$DCC_LIBEXEC/dbclean -F'.

-L ltype,facility.level

specifies how messages should be logged. Ltype must be

error or info to indicate which of the two types of messages are

being controlled. Level must be a syslog(3) level among EMERG,

ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG. Facility

must be among AUTH, AUTHPRIV, CRON, DAEMON, FTP, KERN, LPR, MAIL,

NEWS, USER, UUCP, and LOCAL0 through LOCAL7. The default is

equivalent to

-L info,MAIL.NOTICE -L error,MAIL.ERR

-R [RL_SUB],[RL_ANON],[RL_ALL_ANON],[RL_BUGS]

sets the four categories of rate-limits. RL_SUB limits

the number of DCC transactions per second from subscribers or DCC

clients with known client-IDs and passwords. This limit applies

to each IP address independently.

RL_ANON limits the number of DCC transactions per sec

ond from anonymous DCC clients. This limit applies to each IP

address independently. It is better to use -u than to change

this value to exclude anonymous clients.

RL_ALL_ANON limits the number of DCC transactions per

second from all anonymous DCC clients. Its default value is set

by the compile-time value of DCCD_RL_ALL_ANON. This limit ap

plies to all anonymous clients as a group, regardless of their IP

addresses.

RL_BUGS limits the number of complaints or error mes

sages per second for all anonymous DCC clients as a group as well

as for each DCC client by IP address.

The default is equivalent to -R 200,50,200,0.1

FILES

/var/dcc is the DCC home directory containing data and con

trol files.
dcc_db is the database of mail checksums.
dcc_db.hash is the mail checksum database hash table.
grey_db is the database of greylist checksums.
grey_db.hash is the greylist database hash table.
flod contains lines controlling DCC flooding of the

form:

host[,port][;src] rem-ID [passwd-ID [o-opts

[i-opts]]]

where absent optional values are signaled with "-"

and

host is the IP address or name of a DCC server.
port is the name or number of the UDP port used

by the server.
src is the IP address or host name from which the

outgoing connection should come.
rem-id is the server-ID of the remote DCC server. passwd-ID is a server-ID that is not assigned to

a server, but whose first password is used to sign checksum re

ports sent to the remote system. Either of its passwords are re

quired with incoming reports. If it is absent or "-", outgoing

floods are signed with the first password of the local server in

the ids file and incoming floods must be signed with either pass

word of the remote server-ID.
i-opts and o-opts are comma-separated lists of

off turns off flooding to the remote or lo

cal system.
traps indicates that the remote sending or

local receiving system has only "spam traps."
no-del says checksum delete requests are re

fused by the remote or local server and so turns off sending or

accepting delete requests, respectively. By default, delete re

quests are not sent to remote servers and refused in incoming

floods.
del says delete requests are accepted by the

remote or local server.
no-log-del turns off logging of incoming re

quests to delete checksums.
passive is used to tell a server outside a

firewall to expect a peer inside to create both of the pair of

input and output TCP connections used for flooding. The peer in

side the firewall should use SOCKS on its flod file entry for

this system.
SOCKS is used to tell a server inside a

firewall that it should create both of the TCP connections used

for flooding and that SOCKS protocol should be used. The peer

outside the firewall should use passive on its flod file entry

for this system.
ID1->ID2 converts server-ID ID1 in flooded

reports to server-ID ID2. Either ID1 or ID2 may be the string

'self' to specify the server's own ID. ID1 can be the string

'all' to specify all server-IDs or a pair of server-IDs separated

by a dash to specify an inclusive range. ID2 can be the string

'ok' to send or receive reports without translation or the string

'reject' to not send outgoing or refuse incoming reports. Only

the first matching conversion is applied. For example, when

'self->ok,all->reject' is applied to a locally generated report,

the first conversion is applied and the second is ignored.
leaf=path-len does not send reports with

paths longer than path-len server-IDs.
IPv4 overrides a -6 setting for this flood

ing peer.
IPv6 overrides the default or an explicit -4

setting.
vers specifies the version of the DCC flood

ing protocol used by the remote DCC server with a string such as

'version2'.

grey_flod is the equivalent of flod used by dccd when it is

a greylist server.

flod.map is an automatically generated file in which dccd

records its progress sending or flooding reports to DCC peers.

grey_flod.map is the equivalent of flod.map used by dccd

when it is a greylist server.

ids contains the IDs and passwords known by the DCC

server. An ids file that can be read by others cannot be used.

It contains blank lines, comments starting with "#" and lines of

the form:

id[,rpt-ok][,delay=ms[*inflate]] passwd1

[passwd2]

where

id is a DCC client-ID or server-ID. Rpt-ok if present overrides -Q by saying that

this client is trusted to report only checksums for unsolicited

bulk mail.
delay=ms[*inflate] delays answers to systems us

ing the client id. The delay in milliseconds is multiplied by 1

plus the number of recent requests from an IP address using id

divided by the inflate value. See -U.
passwd1 is the password currently used by clients

with identifier id. It is a 1 to 32 character string that does

not contain blank, tab, newline or carriage return characters.
passwd2 is the optional next password that those

clients will use. A DCC server accepts either password if both

are present in the file.

Both passwords can be absent if the entry not used

except to tell dccd that server-IDs in the flooded reports are

valid. The string unknown is equivalent to the null string.

whitelist contains the DCC server whitelist. It is not used

directly but is loaded into the database when dbclean(8) is run.

grey_whitelist contains the greylist server whitelist. It

is not used directly but is loaded into the database when db

clean(8) is run with -G.

blacklist if present, contains a list of IP addresses and

blocks of IP addresses DCC clients that are ignored. Each line

in the file should be blank, a comment starting with '#', an IP

address, or a block of IP addresses in the xxx.xxx.xxx.xxx/yy

form. Changes to the file are automatically noticed and acted

upon within a few minutes. Addresses can be followed with com

ments starting with '#'. This mechanism is intended for no more

than a few dozen blocks of addresses.

EXAMPLES

dccd is usually started with other system daemons with some

thing like the script misc/start-dccd. It uses values in the

file dcc_conf in the DCC home directory to start the server.

The following is useful for cleanly stopping the daemon:

cdcc 'id 100; stop'

Again, the ID of the local server must be used instead of

"100."

Unless old reports are removed from the database, it grows

too large. dbclean(8) should be run daily with script like

/var/dcc/libexec/cron-dccd.

SEE ALSO

cdcc(8), dcc(8), dbclean(8), dblist(8), dccifd(8), dccm(8),

dccproc(8). dccsight(8),

HISTORY

dccd is based on an idea from Paul Vixie. It was designed

and written at Rhyolite Software starting in 2000. This document

describes version 1.2.74.

BSD December 8, 2007

BSD