--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/cdcc.0	Tue Mar 10 13:49:58 2009 +0100
@@ -0,0 +1,391 @@
+cdcc(8)               Distributed Checksum Clearinghouse               cdcc(8)
+
+NNAAMMEE
+     ccddcccc -- Control Distributed Checksum Clearinghouse
+
+SSYYNNOOPPSSIISS
+     ccddcccc [--VVddqq] [--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
+     operation that requires a password without specifying a server-ID or
+     without using a UID that can access the _i_d_s file produces an error mes-
+     sage 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.
+
+     --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 file containing DCC IDs and passwords known by the local
+          DCC server.  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
+          operations 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.
+
+     ffiillee [_m_a_p]
+           displays or specifies the name or path of the map file.  The string
+           "-" specifies the default file _m_a_p in the DCC home directory.
+
+     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 a multiple of 10 millisec-
+           onds between -4000 and +4000 following the string _R_T_T.  The adjust-
+           ment 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
+           assumed 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
+           resolved 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
+           imposed 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]
+           sets a switch to cause clients using the map file to try to use
+           IPv6.
+
+     SSOOCCKKSS [_o_n _o_f_f]
+           sets a switch to cause DCC clients using the map 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 appropri-
+           ately, 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]
+           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
+           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] [_m_a_x [_t_h_o_l_d]] [_a_d_d_r[_/_p_r_e_f_i_x]]
+          displays some of the clients recently seen by the server.
+          --nn   displays only the IP addresses and not the names of clients.
+          --ss   sorts the clients by the number of requests they have made.
+          --ii   counts clients with the same client-ID as single entities.
+          --aa   produces 24 hour average numbers of requests.
+          --AA   displays only anonymous clients.
+          --KK   displays only clients using client-IDs.
+          --VV   includes the DCC protocol versions used by clients.
+          _m_a_x  displays only the _m_a_x most recent clients.
+          _m_a_x _t_h_o_l_d displays 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 CIDR block.
+
+          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 heard from
+          since ssttaattss cclleeaarr was last used 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
+          rebuilt 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   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  DCC home directory
+     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 1.3.103.
+
+                               February 26, 2009