cdcc(8) FreeBSD System Manager's Manual cdcc(8) NNAAMMEE ccddcccc -- Control Distributed Checksum Clearinghouse SSYYNNOOPPSSIISS ccddcccc [--VVBBddqq] [--hh _h_o_m_e_d_i_r] [--cc _i_d_s] [_o_p_1 _o_p_2 _._._. [_-]] DDEESSCCRRIIPPTTIIOONN CCddcccc is used to clear, control, and query the control file used by Dis- tributed Checksum Clearinghouse clients such as dccm(8). The host names, UDP port numbers, IDs, and passwords local clients use to talk to servers as well as IP addresses, round trip times, and other information are con- tained in the _m_a_p file. While ccddcccc is set-UID, it uses the real UID only when accessing the _m_a_p file. It refuses to display sensitive information such as passwords unless the real UID is the same as the effective UID. Note that ccddcccc needs to be set to a UID that can read and write the _m_a_p file, but that UID need not be 0. CCddcccc is also used to send commands to DCC servers to tell them to stop, reload their lists of DCC IDs, turn on tracing, and so forth. Many commands sent to DCC servers require a numeric DCC ID and a password recognized by the server. A DCC password is a 1-32 character string that does not contain blank, tab, newline or carriage return characters. The ID is specified with the iidd operation. If ccddcccc is run with a real UID that can read the _i_d_s file and a password is not specified (see the ppaasssswwoorrdd operation), then the current password for the specified ID in the _i_d_s file will be used. If no _i_d_s file is available and a password and DCC ID are not specified, ccddcccc uses the anonymous DCC client-ID. DCC servers do not expect a password from clients using the anonymous client- ID, but they also won't honor control requests. Operations that modify the _m_a_p file can only be performed when the real UID is sufficient to modify the file directly. Trying to perform an op- eration that requires a password without specifying a server-ID or with- out using a UID that can access the _i_d_s file produces an error message complaining about a "privileged operation." Commands and operations are read from the command line or from stdin. A series of _o_p_1 _o_p_2 _._._. operations followed a _- (a dash) causes operations to be read from stdin after the command line operations are processed. Semi-colons or newlines separate commands in UNIX command-line "words," as well as when commands are read from stdin. Since each command line operation must be a shell "word," quotes are often required as in % cdcc "load map.txt" or % cdcc "host localhost;info" stats OOPPTTIIOONNSS The following options are available: --VV displays the version of the DCC controller. Two or more --VV options show the options with which it was built. --BB sends error messages from the DCC server to both stderr and stdout instead of only stderr. --dd enables debugging output from the DCC client software. Additional --dd options increase the number of messages. See the ddeebbuugg command. --qq quiets initial complaints about the map file and some messages about successful commands. See the qquuiieett command. --hh _h_o_m_e_d_i_r overrides the default DCC home directory, _/_v_a_r_/_d_c_c. See the hhoommeeddiirr operation. --cc _i_d_s specifies the file containing DCC IDs and passwords known by local DCC servers. An _i_d_s file that can be read by others cannot be used. The format of the _i_d_s file is described in dccd(8). _o_p_1 _o_p_2 _._._. are operations or commands such as "id 100; stop". Commands or op- erations specified on the command line are performed before the first interactive request. The last command can be _- to specify that additional commands should be read from stdin. OOPPEERRAATTIIOONNSS Local operations include the following: hheellpp [_c_o_m_m_a_n_d] lists information about one or all available commands and opera- tions. eexxiitt stops ccddcccc ggrreeyy [_o_n | _o_f_f] switches between DCC and greylist servers. hhoommeeddiirr [_p_a_t_h] displays or specifies the DCC home directory, _/_v_a_r_/_d_c_c. ffiillee [_m_a_p] displays or specifies the name or path of the map file. The string "-" specifies the default file _/_v_a_r_/_d_c_c_/_m_a_p. nneeww mmaapp [_m_a_p] creates a new, empty file for DCC server host names, port numbers, passwords, and so forth. There must not already be a file of the same name. The default is _m_a_p in the DCC home directory. ddeelleettee _h_o_s_t[,_p_o_r_t] deletes the entry in the _m_a_p file for _h_o_s_t and UDP _p_o_r_t_. If greylist mode has been set with the ggrreeyy oonn command, the entry for the grelist server at _h_o_s_t is deleted. aadddd _h_o_s_t[,_p_o_r_t] [_R_T_T_+_a_d_j|_R_T_T_-_a_d_j] [_G_r_e_y_l_i_s_t] [_c_l_i_e_n_t_-_I_D [password]] adds an entry to the _m_a_p file. The _p_o_r_t can be "-" to specify the default DCC server port number. An adjustment to the round trip time is between -2000 and +2000 and follows the string _R_T_T. The adjustment is added to the average measured round trip time when the DCC client software picks the "nearest" DCC server, or the server with the smallest RTT. If an IP address is mentioned more than once in the list of servers, for example because it is among the addresses for more than one server name, conflicts among RTT adjustments are resolved by picking the adjustment with the largest absolute value. _G_r_e_y_l_i_s_t marks an entry for a greylist servers. _G_r_e_y_l_i_s_t is as- sumed if greylist mode has been set with the ggrreeyy oonn command, See dccd(8). If both the client-ID and the password are absent, the anonymous client-ID, 1, is used. The string _a_n_o_n is equivalent to the anony- mous client-ID. A null password string is assumed if the password is missing and the client-ID is 1 or also missing. llooaadd _i_n_f_o_-_f_i_l_e loads the current parameter file with the host names, port numbers, IDs, and passwords in _i_n_f_o_-_f_i_l_e. Standard input is understood if _i_n_f_o_-_f_i_l_e is "-". A suitable file can be created with the iinnffoo operation. It con- sists of ignored blank or comment lines starting with '#' and other lines in the same format as the arguments to the aadddd operation. Note that output of the iinnffoo command will lack passwords unless it is run by a privileged user. hhoosstt [_h_o_s_t_n_a_m_e] specifies the host name of the DCC server to which commands should be sent. If _h_o_s_t_n_a_m_e is "-", the current default DCC server is chosen. ppoorrtt [_p_o_r_t] specifies the UDP port number of the DCC server to which commands should be sent. The default is 6277 or 6276 depending on the set- ting of the greylist mode controlled with the ggrreeyy command. ppaasssswwoorrdd _s_e_c_r_e_t specifies the password with which to sign commands sent to the DCC server specified with the sseerrvveerr and ppoorrtt operations. iidd [_I_D] specifies or displays the numeric DCC ID for commands sent to the DCC server specified with the sseerrvveerr and ppoorrtt operations. If no password is specified with the ppaasssswwoorrdd command, the password is sought in the local _i_d_s. iinnffoo [--NN] displays information about the connections to DCC servers. It starts with the current date and name of the current _m_a_p file or says that ccddcccc is using the implicit file created with the sseerrvveerr and ppoorrtt operations. It then says when host names will next be re- solved into IP addresses, the smallest round trip time to the IP addresses of known DCC servers. The host name, UDP port number (or dash if it is the default), DCC client-ID, and password (if ccddcccc is used by a privileged user) are shown in one line per configured DCC server. The currently preferred IP address is indicated by an asterisk. The "brand" of the server, its DCC ID, and its IP address are dis- played in one line per IP address. The performance of the server at each IP address in the most recent 32 operations is displayed in a second line. The second line ends with the measured delay im- posed by the server on requests with this client's ID. --NN displays the reverse DNS name of each server. RRTTTT [--NN] measures the round trip time to the DCC servers. It does this by discarding accumulated information and forcing a probe of all listed server IP addresses. _B_e_w_a_r_e that when run with sufficient privilege, the RRTTTT operation is like the iinnffoo and llooaadd operations and displays cleartext pass- words. --NN displays the reverse DNS name of each server. ddeebbuugg Op Ar on | off | TTL=x increases or decreases debugging information from the DCC client software or sets the IP TTL on queries to the server. See --dd. Some operating systems do not include the functions required to change the IP TTL. Others include the required functions but have no apparent effect. qquuiieett [_o_n | _o_f_f] makes commands more quiet or more verbose. IIPPvv66 [_o_n | _o_f_f | _o_n_l_y] clients to try to use IPv6 and IPv4, IPv4 only, or IPv6 only. SSOOCCKKSS [_o_n | _o_f_f] tell DCC to use the SOCKS5 protocol if they have been built with a SOCKS library. The socks library linked with the DCC client must be configured appropriately, often including knowing which DCC servers must be connected via the SOCKS proxy and which can be reached directly. DCC clients use SOCKS functions such as Rsendto() with all or no servers depending on the setting of this switch. ssrrcc [_- |] _I_P_a_d_d_r_e_s_s[_,_I_P_v_6_a_d_d_r_e_s_s] displays or configures the source address of DCC client requests. _- removes the explicit configuration of the source, while _I_P_a_d_d_r_e_s_s or _I_P_a_d_d_r_e_s_s_,_I_P_v_6_a_d_d_r_e_s_s sets it. This makes sense only on multi- homed hosts. It can be useful for passing firewalls. DDCCCC SSEERRVVEERR CCOOMMMMAANNDDSS Commands that can be sent to a DCC server include the following. Most of the commands must be used with the server's _I_D specified with the iidd com- mand. The specified ID is included in the commands sent to the server The command itself is digitally signed with the first password associated with the ID in the _i_d_s file. The server requires that the signature match one of the passwords associated with the ID in its _i_d_s file. ddeellcckk ttyyppee hheexx11 hheexx22 hheexx33 hheexx44 asks the server to delete the _t_y_p_e checksum with value _h_e_x_1 _h_e_x_2 _h_e_x_3 _h_e_x_4. The type and checksum values can be found in dccproc(8) and dccm(8) log files or computed with _d_c_c_p_r_o_c --QQCC. There are very few situations where it makes sense to bother to delete checksums. For example, mail that was accidentally reported with a target count of "MANY" is either private and so will not be seen by other people and so will not be affected, or it is bulk and its source so must have already been whitelisted by recipients. ssttaattss [_a_l_l | _c_l_e_a_r] displays current status and statistics from the current DCC server or for _a_l_l known DCC servers. The server's counters will be cleared after they are displayed when the server's ID has been specified with the iidd _I_D operation. cclliieennttss [--nnssiiaaVVAAKK] [--II _i_d] [_m_a_x [_t_h_o_l_d]] [_a_d_d_r[_/_p_r_e_f_i_x]] display some of the clients recently seen by the server. --nn display only the IP addresses and not the names of clients. --ss sort the clients by the number of requests they have made. --ii count clients with the same client-ID as single entities. --II _i_d display information only about clients using client-ID _i_d. --aa produce 24 hour average numbers of requests. --AA display only anonymous clients. --KK display only clients using client-IDs other than the anony- mous ID of 1. --VV include the DCC protocol versions used by clients. _m_a_x display only the _m_a_x most recent clients. _m_a_x _t_h_o_l_d display the most recent _m_a_x clients that have made at least _t_h_o_l_d requests. _a_d_d_r[_/_p_r_e_f_i_x] restricts the results to the DCC client with that IP address or clients with addresses in that block of addresses. Individual clients in a blacklisted block of addresses in the server's _/_v_a_r_/_d_c_c_/_b_l_a_c_k_l_i_s_t file are not displayed unless ex- plicitly requested by address or address block. Clients with IDs marked with an asterisk (*) used the wrong password for that client-ID. The mechanism that implements this command involves asking the DCC server for the first approximately 100 clients, then the second about 100, and so on, If entries change position in the complete list maintained by the server between requests, the displayed list will have duplicate or missing entries. Only clients since the last use of ssttaattss cclleeaarr are displayed. ssttoopp tells the DCC server to exit. ssyysstteemm ssttoopp tells the DCC server to exit so that the operating system can be shut down. This tells the DCC server on some systems to delete the dcc_db.hash file to speed system shut down. The file will be re- built automatically by ddbbcclleeaann when the DCC server is restarted. cclleeaann ssttoopp tells the DCC server to exit after applying fsync() to the database. rreellooaadd IIDDss tells the local DCC server to reload its DCC _i_d_s file immediately. This command is not strictly needed. Every several minutes, the DCC server notices if the file has been changed and automatically reads it. fflloooodd cchheecckk tells the DCC server to check for changes in the _f_l_o_d file and try to restart any of the streams to peers that are broken. fflloooodd sshhuuttddoowwnn tells the DCC server to cleanly stop flooding checksums to and from peers. The server will wait for sending and receiving peers to agree to stop. Each fflloooodd sshhuuttddoowwnn or fflloooodd hhaalltt request increases a count of reasons why the server should not flood checksums. fflloooodd hhaalltt tells the DCC server to abruptly stop flooding checksums to and from peers. fflloooodd rreewwiinndd _s_e_r_v_e_r_-_I_D tells the DCC server to ask its peer with _s_e_r_v_e_r_-_I_D to rewind and resend its stream of checksums. fflloooodd ffffwwdd iinn _s_e_r_v_e_r_-_I_D tells the DCC server to ask its peer to "fast forward" or skip to the end of the incoming flood. fflloooodd ffffwwdd oouutt _s_e_r_v_e_r_-_I_D tells the DCC server to "fast forward" or skip to the current end of the flood to its peer. fflloooodd rreessuummee tells the DCC server to reduce the number of reasons to not flood checksums increased by fflloooodd sshhuuttddoowwnn and fflloooodd hhaalltt.. When the num- ber of reasons reaches zero, the server tries to resume flooding. fflloooodd lliisstt displays the list of current incoming and outgoing floods. Each line contains the server-ID of the peer, the IP address and port used for the outgoing flood, the address for the incoming flood if different, and the host name. Only the server-IDs of flooding peers are disclosed with the server's ID. fflloooodd ssttaattss [cclleeaarr] { _s_e_r_v_e_r_-_I_D | _a_l_l } displays counts of checksum reports sent and received by the current flooding connections to and from _s_e_r_v_e_r_-_I_D or _a_l_l flooding connec- tions and then optionally clears the counts. DDBB cclleeaann is used by ddbbcclleeaann to tell the server that the database expiration has begun. DDBB nneeww is used by ddbbcclleeaann to tell the server that the database cleaning is complete. fflluusshh ccaacchhee tells the server to flush its cache and to keep it clean. ccaacchhee ookk tells the server to resume normal operations after fflluusshh ccaacchhee. cclloocckk cchheecckk asks the DCC server to say how much its clock differs from the local clock. cclloocckk kklluuddggee ++//--sseeccoonnddss adjusts the timestamps in server commands to make it possible to control servers with inaccurate clocks. ttrraaccee _d_e_f_a_u_l_t turns on _A_N_O_N and _C_L_N_T tracing and turns off all others. ttrraaccee _m_o_d_e _{_o_n_|_o_f_f_} turns the server's tracing _m_o_d_e on or off. _M_o_d_e must be one of: _A_D_M_N administrative requests from ccddcccc _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 messages concerning the report-ID cache that is used to detect duplicate reports from clients _F_L_O_O_D_1 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 blacklisted clients _D_B odd database events _W_L_I_S_T reports of whitelisted checksums from authenticated, not anonymous DCC clients ccddcccc exits with 0 on success, and >0 if an error occurs in operations specified on the command line. FFIILLEESS /var/dcc default DCC home directory unless changed by the _h_o_m_e_d_i_r opera- tion. map memory mapped file in the home DCC home directory of server host names, port numbers, passwords, measured round trip times (RTT), and so forth. ids list of IDs and passwords, as described in dccd(8). It is only required by systems running the DCC server, but is used by ccddcccc if available. SSEEEE AALLSSOO dbclean(8), dcc(8), dccd(8), dblist(8), dccifd(8), dccm(8), dccproc(8), dccsight(8). HHIISSTTOORRYY Implementation of ccddcccc was started at Rhyolite Software in 2000. This document describes version RHYOLITE_VERSION. March 22, 2024