Mercurial > notdcc
diff dccd.0 @ 0:c7f6b056b673
First import of vendor version
| author | Peter Gervai <grin@grin.hu> |
|---|---|
| date | Tue, 10 Mar 2009 13:49:58 +0100 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dccd.0 Tue Mar 10 13:49:58 2009 +0100 @@ -0,0 +1,439 @@ +dccd(8) Distributed Checksum Clearinghouse dccd(8) + +NNAAMMEE + ddccccdd -- Distributed Checksum Clearinghouse Daemon + +SSYYNNOOPPSSIISS + ddccccdd [--6644ddVVbbffFFQQ] --ii _s_e_r_v_e_r_-_I_D [--nn _b_r_a_n_d] [--hh _h_o_m_e_d_i_r] --II [_h_o_s_t_-_I_D][_,_u_s_e_r] + [--aa [_s_e_r_v_e_r_-_a_d_d_r][_,_s_e_r_v_e_r_-_p_o_r_t]] [--qq _q_s_i_z_e] + [--GG [_o_n_,][_w_e_a_k_-_b_o_d_y_,][_w_e_a_k_-_I_P_,][_e_m_b_a_r_g_o][_,_w_i_n_d_o_w][_,_w_h_i_t_e]] + [--WW [_r_a_t_e][_,_c_h_g][_,_d_b_s_i_z_e]] [--KK [_n_o_-]_t_y_p_e] [--TT _t_r_a_c_e_m_o_d_e] + [--uu _a_n_o_n_-_d_e_l_a_y[_*_i_n_f_l_a_t_e]] [--CC _d_b_c_l_e_a_n] [--LL _l_t_y_p_e_,_f_a_c_i_l_i_t_y_._l_e_v_e_l] + [--RR [_R_L___S_U_B],[_R_L___A_N_O_N],[_R_L___A_L_L___A_N_O_N],[_R_L___B_U_G_S]] + +DDEESSCCRRIIPPTTIIOONN + DDccccdd 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 cryptographically secure checksums of + such information. A DCC server cannot determine the text or other infor- + mation 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 identified by a + numeric _s_e_r_v_e_r_-_I_D. Each DCC client is identified by a _c_l_i_e_n_t_-_I_D, either + explicitly listed in the _i_d_s file or the special anonymous client-ID. + Many computers are expected to share a single _c_l_i_e_n_t_-_I_D. A _s_e_r_v_e_r_-_I_D is + less than 32768 while a _c_l_i_e_n_t_-_I_D is between 32768 and 16777215. DCC + server-IDs need be known only to DCC servers and the people running them. + The passwords 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 sin- + gle client computer can use different passwords with different server + computers. See the _i_d_s 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 dbclean(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 reports of checksums among + DCC servers increases the effective number of subscribers to each server. + Each ddccccdd daemon tries to maintain TCP/IP connections to the other + servers listed in the _f_l_o_d file, and send them reports containing check- + sums with total counts exceeding thresholds. Changes in the _f_l_o_d file + are noticed automatically within minutes. + + Controls on report flooding are specified in the _f_l_o_d 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 _d_e_l is not present among the _i_n_-_o_p_t_s 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 --QQ option to count extremely bulk mail should be marked + with _t_r_a_p_s. They can be seen as counting millions of targets, so the + _t_r_a_p_s flag on their _f_l_o_d file entry changes their incoming flooded + reports counts to _m_a_n_y_. + + DDccccdd automatically checks its _f_l_o_d and _i_d_s files periodically. Cdcc(8) + has the commands nneeww iiddss and fflloooodd cchheecckk to tell ddccccdd to check those two + files immediately. Both files are also checked for changes after the + SIGHUP signal. + + OOPPTTIIOONNSS + The following options are available: + + --66 enable IPv6. The default is equivalent to --44. See also the IPv4 + and IPv6 options in the _f_l_o_d file description below and the _I_P_v_6 _o_n + cdcc(8) command. + + --44 disable IPv6. See also --66. + + --dd enables debugging output. Additional --dd options increase the number + of messages. + + --VV displays the version of the DCC server daemon. + + --bb causes the server to not detach itself from the controlling tty or + put itself into the background. + + --FF uses write() instead of mmap() in some cases to modify the DCC data- + base. It is the default on Solaris. + + --ff turns off --FF. + + --QQ causes the server to treat reports of checksums as queries except + from DCC clients marked trusted in the _i_d_s file with _r_p_t_-_o_k. See --uu + to turn off access by anonymous or unauthenticated clients + + --ii _s_e_r_v_e_r_-_I_D + specifies the ID of this DCC server. Each server identifies itself + as responsible for checksums that it forwards to other servers. + + --nn _b_r_a_n_d + 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_-_D_C_C headers generated by the DCC. + + --hh _h_o_m_e_d_i_r + overrides the default DCC home directory, _/_v_a_r_/_d_c_c. + + --II [_h_o_s_t_-_I_D][_,_u_s_e_r] + changes the server's globally unique identity for flooding from the + default value consisting of the first 16 characters of the host + name. or changes the UID and GID of the process _H_o_s_t_-_I_D is a string + of up to 16 characters that replaces the first 16 characters of the + system's hostname in assertions of the server-ID that are flooded to + peers. _U_s_e_r must be valid user name. + + --aa [_s_e_r_v_e_r_-_a_d_d_r][_,_s_e_r_v_e_r_-_p_o_r_t] + adds an hostname or IP address to the list of local IP addresses + that the server answers. Multiple --aa options can be used to specify + a subset of the available network interfaces or to use more than one + port number. The default without any --aa options is to listen on all + local IP addresses. It can be useful to list some of the IP + addresses of multi-homed hosts to deal with firewalls. By default + _s_e_r_v_e_r_-_p_o_r_t 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 reports. + + If _s_e_r_v_e_r_-_a_d_d_r is absent and if the getifaddrs(8) function is sup- + ported, separate UDP sockets are bound to each configured network + interface so that each DCC clients receives replies from the IP + addresses to which corresponding request are sent. If ddccccdd 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 + ddccccdd 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 --aa option, but only if there + is single option that is not localhost. See also the _f_l_o_d file. + + --qq _q_s_i_z_e + 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. + + --GG [_o_n_,][_w_e_a_k_-_b_o_d_y_,][_w_e_a_k_-_I_P_,][_e_m_b_a_r_g_o][_,_w_i_n_d_o_w][_,_w_h_i_t_e] + changes ddccccdd to a Greylist server for dccm(8) or dccifd(8). + Greylisting consists of temporarily rejecting or embargoing mail + from unfamiliar combinations of SMTP client IP address, SMTP enve- + lope sender, and SMTP envelope recipient. If the SMTP client per- + sists for _e_m_b_a_r_g_o _s_e_c_o_n_d_s and so is probably not an open proxy, + worm-infected personal computer, or other transient source of spam, + the triple of _(_I_P _a_d_d_r_e_s_s_,_s_e_n_d_e_r_,_r_e_c_i_p_i_e_n_t_) is added to a database + similar to the usual DCC database. If the SMTP client does not try + again after _e_m_b_a_r_g_o seconds and before _w_i_n_d_o_w 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 remem- + bered for _w_h_i_t_e seconds after the last accepted mail message. The + triple is forgotten if it is ever associated with unsolicited bulk + email. + + All three durations can be a number of minutes, hours, days, or + weeks followed by _M_I_N_U_T_E_S, _M, _H_O_U_R_S, _H, _D_A_Y_S, _D, _W_E_E_K_S or _W. The + default is --GG _2_7_0_s_e_c_o_n_d_s_,_7_d_a_y_s_,_6_3_d_a_y_s. The first duration or the + _e_m_b_a_r_g_o should be longer than open proxies can linger retransmit- + ting. The second _w_i_n_d_o_w time should be as long as legitimate mail + servers persist in retransmitting to recognize embargoed messages + whose retransmissions were not received because of network or other + problems. The _w_h_i_t_e 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 _e_m_b_a_r_g_o. If + _w_e_a_k_-_b_o_d_y is present, any message with the same triple of sender IP + address, sender mail address, and target mail address ends the + embargo, even if the body of the message differs. + + If _w_e_a_k_-_I_P is present, all mail from an SMTP client at an IP address + is accept after any message from the same IP address has been + accepted. + + Unlike DCC checksums, the contents of greylist databases 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 + _g_r_e_y___f_l_o_d file. + + All greylist cooperating or flooding greylist servers _m_u_s_t use the + same --GG values. + + Clients of greylist servers cannot be anonymous and must have + client-IDs and passwords assigned in the _i_d_s file. This implies + that cdcc commands directed to greylist servers must specify the + server-ID. + + White- and blacklists are honored by the DCC clients. whitelisted + 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 net- + work to improve the detection of bulk mail. + + --WW [_r_a_t_e][_,_c_h_g][_,_d_b_s_i_z_e] + controls quick database cleaning. If the database is larger than + _d_b_s_i_z_e, it seems that the database has not recently and is not about + to be cleaned, ddccccdd is receiving fewer than _r_a_t_e requests per sec- + ond, and if telling DCC clients that the database is about to be + cleaned reduces that rate by _c_h_g%, then ddccccdd starts dbclean(8) for a + quick database cleaning. The cleaning is abandoned if it takes too + long. The default values are equivalent to --WW _1_._0_,_4_0_._0_,_R_S_S where + _R_S_S is the maximum dccd resident set displayed the system log by --dd + when ssttaarrttss. + + --KK [_n_o_-]_t_y_p_e + marks checksums of _t_y_p_e (not) be kept or counted in the database + unless they appear in the whitelist. Explicit settings add to or + remove from the initial contents of the list, which is equivalent to + --KK _B_o_d_y --KK _F_u_z_1 --KK _F_u_z_2. + + --TT _t_r_a_c_e_m_o_d_e + causes the server to trace or record some operations. _t_r_a_c_e_m_o_d_e + must be one of the following: + _A_D_M_N administrative requests from the control program, cdcc(8) + _A_N_O_N errors by anonymous clients + _C_L_N_T errors by authenticated clients + _R_L_I_M rate-limited messages + _Q_U_E_R_Y all queries and reports + _R_I_D_C some messages concerning the report-ID cache that is used + to detect duplicate reports from clients + _F_L_O_O_D messages about inter-server flooding connections + _F_L_O_O_D_2 messages about flooded reports + _I_D_S unknown server-IDs in flooded reports + _B_L requests from clients in the _b_l_a_c_k_l_i_s_t file. + _D_B odd database events including long chains of duplicate + checksums + _W_L_I_S_T reports of whitelisted checksums from authenticated, not + anonymous DCC clients + The default is _A_N_O_N _C_L_N_T. + + --uu _a_n_o_n_-_d_e_l_a_y[_*_i_n_f_l_a_t_e] + changes the number of milliseconds anonymous or unauthenticated + clients must wait for answers to their queries and reports. The + purpose of this delay is to discourage large anonymous clients. The + _a_n_o_n_-_d_e_l_a_y is multiplied by 1 plus the number of recent anonymous + requests from an IP address divided by the _i_n_f_l_a_t_e value. + + The string _F_O_R_E_V_E_R turns off all anonymous or unauthenticated access + not only for checksum queries and reports but also cdcc(8) ssttaattss + requests. A missing value for _i_n_f_l_a_t_e turns off inflation. + + The default value is _5_0_,_n_o_n_e, except when --GG is used in which case + _F_O_R_E_V_E_R is assumed and required. + + --CC _d_b_c_l_e_a_n + changes the default name or path of the program used to rebuild the + hash table when it becomes too full. The default value is + _/_v_a_r_/_d_c_c_/_l_i_b_e_x_e_c_/_d_b_c_l_e_a_n in the _/_v_a_r_/_d_c_c_/_l_i_b_e_x_e_c directory. The + value can include arguments as in _-_C _'_$_D_C_C___L_I_B_E_X_E_C_/_d_b_c_l_e_a_n _-_F_'. + + Dbclean _s_h_o_u_l_d _n_o_t be run by ddccccdd except in emergencies such as + database corruption or hash table overflow. Dbclean(8) should be + run daily with the /var/dcc/libexec/cron-dccd cron script + + --LL _l_t_y_p_e_,_f_a_c_i_l_i_t_y_._l_e_v_e_l + specifies how messages should be logged. _L_t_y_p_e must be _e_r_r_o_r, _i_n_f_o, + or _o_f_f to indicate which of the two types of messages are being con- + trolled or to turn off all syslog(3) messages from ddccccdd. _L_e_v_e_l must + be a syslog(3) level among _E_M_E_R_G, _A_L_E_R_T, _C_R_I_T, _E_R_R, _W_A_R_N_I_N_G, _N_O_T_I_C_E, + _I_N_F_O, and _D_E_B_U_G. _F_a_c_i_l_i_t_y must be among _A_U_T_H, _A_U_T_H_P_R_I_V, _C_R_O_N, + _D_A_E_M_O_N, _F_T_P, _K_E_R_N, _L_P_R, _M_A_I_L, _N_E_W_S, _U_S_E_R, _U_U_C_P, and _L_O_C_A_L_0 through + _L_O_C_A_L_7. The default is equivalent to + --LL _i_n_f_o_,_M_A_I_L_._N_O_T_I_C_E --LL _e_r_r_o_r_,_M_A_I_L_._E_R_R + + --RR [_R_L___S_U_B],[_R_L___A_N_O_N],[_R_L___A_L_L___A_N_O_N],[_R_L___B_U_G_S] + sets one or more of the four rate-limits. _R_L___S_U_B 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. + + _R_L___A_N_O_N limits the number of DCC transactions per second from anony- + mous DCC clients. This limit applies to each IP address indepen- + dently. It is better to use --uu than to change this value to exclude + anonymous clients. + + _R_L___A_L_L___A_N_O_N limits the number of DCC transactions per second from + all anonymous DCC clients. This limit applies to all anonymous + clients as a group, regardless of their IP addresses. + + _R_L___B_U_G_S limits the number of complaints or error messages 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 --RR _4_0_0_,_5_0_,_6_0_0_,_0_._1 + +FFIILLEESS + /var/dcc is the DCC home directory containing data and control 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: + _h_o_s_t[_,_r_p_o_r_t][_;_s_r_c[_,_l_p_o_r_t]] _r_e_m_-_I_D [_p_a_s_s_w_d_-_I_D [_o_-_o_p_t [_i_-_o_p_t]]] + where absent optional values are signaled with "-" and + _h_o_s_t is the IP address or name of a DCC server and _r_p_o_r_t is + the name or number of the TCP port used by the remote + server. + _s_r_c and _l_p_o_r_t are the IP address or host name and TCP port + from which the outgoing flooding connection should come. + Incoming flooding connections must arrive at an address + and port specified with --aa. + _r_e_m_-_i_d is the server-ID of the remote DCC server. + _p_a_s_s_w_d_-_I_D is a server-ID that is not assigned to a server, but + whose first password is used to sign checksum reports sent + to the remote system. Either of its passwords are + required with incoming reports. If it is absent or "-", + outgoing floods are signed with the first password of the + local server in the _i_d_s file and incoming floods must be + signed with either password of the remote server-ID. + _i_-_o_p_t and _o_-_o_p_t are comma separated lists of + _o_f_f turns off flooding to the remote or local system. + _t_r_a_p_s indicates that the remote sending or local receiv- + ing system has only spam traps. + _n_o_-_d_e_l says checksum delete requests are refused by the + remote or local server and so turns off sending or + accepting delete requests, respectively. By default, + delete requests are sent to remote servers and + accepted in incoming floods if and only if the peers + are exchanging DCC reputations. + _d_e_l says delete requests are accepted by the remote or + local server. + _n_o_-_l_o_g_-_d_e_l turns off logging of incoming requests to + delete checksums. + _p_a_s_s_i_v_e 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 inside the firewall should use _S_O_C_K_S or _N_A_T + on its _f_l_o_d file entry for this system. + _S_O_C_K_S 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 _p_a_s_s_i_v_e on its + _f_l_o_d file entry for this system. + _N_A_T differs from _S_O_C_K_S only by not using the SOCKS proto- + col. + _I_D_1_-_>_I_D_2 converts server-ID _I_D_1 in flooded reports to + server-ID _I_D_2. Either _I_D_1 or _I_D_2 may be the string + `self' to specify the server's own ID. _I_D_1 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. _I_D_2 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 con- + version is applied and the second is ignored. + _l_e_a_f_=_p_a_t_h_-_l_e_n does not send reports with paths longer + than _p_a_t_h_-_l_e_n server-IDs. + _I_P_v_4 overrides a --66 setting for this flooding peer. + _I_P_v_6 overrides the default or an explicit --44 setting. + _v_e_r_s specifies the version of the DCC flooding protocol + used by the remote DCC server with a string such as + `version2'. + _t_r_a_c_e sends information about a single peer like the + cdcc(8) command ttrraaccee FFLLOOOODD oonn does for all peers. + _t_r_a_c_e_2 sends information about individual flooded reports + like the cdcc(8) command ttrraaccee FFLLOOOODD22 oonn does for all + peers. + grey_flod is the equivalent of _f_l_o_d used by ddccccdd when it is a greylist + server. + flod.map is an automatically generated file in which ddccccdd records its + progress sending or flooding reports to DCC peers. + grey_flod.map is the equivalent of _f_l_o_d_._m_a_p _u_s_e_d _b_y ddccccdd when it is a + greylist server. + ids contains the IDs and passwords known by the DCC server. An _i_d_s + file that can be read by others cannot be used. It contains + blank lines, comments starting with "#" and lines of the form: + _i_d[_,_r_p_t_-_o_k][_,_d_e_l_a_y_=_m_s[_*_i_n_f_l_a_t_e]] _p_a_s_s_w_d_1 [_p_a_s_s_w_d_2] + where + _i_d is a DCC _c_l_i_e_n_t_-_I_D or _s_e_r_v_e_r_-_I_D. + _R_p_t_-_o_k if present overrides --QQ by saying that this client is + trusted to report only checksums for unsolicited bulk + mail. + _d_e_l_a_y_=_m_s[_*_i_n_f_l_a_t_e] delays answers to systems using the client + _i_d. The _d_e_l_a_y in milliseconds is multiplied by 1 plus the + number of recent requests from an IP address using _i_d + divided by the _i_n_f_l_a_t_e value. See --uu. + _p_a_s_s_w_d_1 is the password currently used by clients with identi- + fier _i_d. It is a 1 to 32 character string that does not + contain blank, tab, newline or carriage return characters. + _p_a_s_s_w_d_2 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 ddccccdd that server-IDs in the flooded reports are valid. + The string _u_n_k_n_o_w_n 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 dbclean(8) is run + with --GG. + 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 '#', or an IP address + or block of IP addresses in the form + [_t_r_a_c_e_,] [_o_k_,] [_b_a_d] xxx.xxx.xxx.xxx[/yy] + Changes to the file are automatically noticed and acted upon + within a few minutes. Addresses or blocks of addresses can be + preceded with _o_k to "punch holes" in blacklisted blocks or with + _t_r_a_c_e to log activity. This mechanism is intended for no more + than a few dozen blocks of addresses. + dccd_clients contains client IP addresses and activity counts. + grey_clients contains greylist client IP addresses and activity counts. + +EEXXAAMMPPLLEESS + ddccccdd is usually started with other system daemons with something like the + script _/_v_a_r_/_d_c_c_/_l_i_b_e_x_e_c_/_r_c_D_C_C. That scripts uses values in + /var/dcc/dcc_conf to start the server. With the argument _s_t_o_p, + _/_v_a_r_/_d_c_c_/_l_i_b_e_x_e_c_/_r_c_D_C_C can be used to stop the daemon. + + The database grows too large unless old reports are removed. dbclean(8) + should be run daily with the /var/dcc/libexec/cron-dccd cron script + +SSEEEE AALLSSOO + cdcc(8), dcc(8), dbclean(8), dblist(8), dccifd(8), dccm(8), dccproc(8). + dccsight(8), + +HHIISSTTOORRYY + ddccccdd is based on an idea from Paul Vixie. It was designed and written at + Rhyolite Software, starting in 2000. This document describes version + 1.3.103. + + February 26, 2009