cdcc.8

    cdcc(8)               Distributed Checksum Clearinghouse               cdcc(8)

## NAME

         cdcc -- Control Distributed Checksum Clearinghouse

## SYNOPSIS

         cdcc [-Vdq] [-h homedir] [-c ids] [op1 op2 ... [-]]

## DESCRIPTION

         Cdcc 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 map file.  While cdcc is set-UID, it uses the real UID only
         when accessing the map file.  It refuses to display sensitive information
         such as passwords unless the real UID is the same as the effective UID.
         Note that cdcc needs to be set to a UID that can read and write the map
         file, but that UID need not be 0.

         Cdcc 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 id operation.  If cdcc is run with a real UID
         that can read the ids file and a password is not specified (see the
         password operation), then the current password for the specified ID in
         the ids file will be used.  If no ids file is available and a password
         and DCC ID are not specified, cdcc 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 map 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 ids 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 op1 op2 ... 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

       OPTIONS
         The following options are available:

         -V   displays the version of the DCC controller.

         -d   enables debugging output from the DCC client library.  Additional -d
              options increase the number of messages.  -q quiets initial com-
              plaints about the map file, and some messages about successful com-
              mands.

         -h homedir
              overrides the default DCC home directory, which is often /var/dcc.
              See the homedir operation.

         -c ids
              specifies file containing DCC IDs and passwords known by the local
              DCC server.  An ids file that can be read by others cannot be used.
              The format of the ids file is described in dccd(8).

         op1 op2 ...
              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.

       OPERATIONS
         Local operations include the following:

         help [command]
               lists information about one or all available commands and opera-
               tions.

         exit  stops cdcc

         grey [on | off]
               switches between DCC and greylist servers.

         homedir [path]
               displays or specifies the DCC home directory.

         file [map]
               displays or specifies the name or path of the map file.  The string
               "-" specifies the default file map in the DCC home directory.

         new map [map]
               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 map in the DCC home directory.

         delete host[,port]
               deletes the entry in the map file for host and UDP port. If
               greylist mode has been set with the grey on command, the entry for
               the grelist server at host is deleted.

         add host[,port] [RTT+adj|RTT-adj] [Greylist] [client-ID [password]]
               adds an entry to the map file.  The port 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 RTT.  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.

               Greylist marks an entry for a greylist servers.  Greylist is
               assumed if greylist mode has been set with the grey on command, See
               dccd(8).

               If both the client-ID and the password are absent, the anonymous
               client-ID, 1, is used.  The string anon 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.

         load info-file
               loads the current parameter file with the host names, port numbers,
               IDs, and passwords in info-file.  Standard input is understood if
               info-file is "-".

               A suitable file can be created with the info operation.  It con-
               sists of blank lines and comment lines starting with '#' other
               lines in the same format as the arguments to the add and load oper-
               ations.  Note that output of the info command will lack passwords
               unless it is run by a privileged user.

         host [hostname]
               specifies the host name of the DCC server to which commands should
               be sent.  If hostname is "-", the current default DCC server is
               chosen.

         port [port]
               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 grey command.

         password secret
               specifies the password with which to sign commands sent to the DCC
               server specified with the server and port operations.

         id [ID]
               specifies or displays the numeric DCC ID for commands sent to the
               DCC server specified with the server and port operations.  If no
               password is specified with the password command, the password is
               sought in the local ids.

         info [-N]
               displays information about the connections to DCC servers.  It
               starts with the current date and name of the current map file or
               says that cdcc is using the implicit file created with the server
               and port 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 cdcc 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.

               -N displays the reverse DNS name of each server.

         RTT [-N]
               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.

               Beware that when run with sufficient privilege, the RTT operation
               is like the info and load operations and displays cleartext pass-
               words.

               -N displays the reverse DNS name of each server.

         debug [on | off | TTL=x]
               increases or decreases debugging information from the DCC client
               library or sets the IP TTL on queries to the server.  See -d.

               Some systems do not include the functions required to change the IP
               TTL.  Others apparently including Microsoft Windows XP include
               required functions but have no apparent effect.

         IPv6 [on | off]
               sets a switch to cause clients using the map file to try to use
               IPv6.

         SOCKS [on off]
               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.

       DCC SERVER COMMANDS
         Commands that can be sent to a DCC server include the following.  Most of
         the commands must be used with the server's ID specified with the id 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 ids file.  The server requires that the signature
         match one of the passwords associated with the ID in its ids file.

         delck type hex1 hex2 hex3 hex4
              asks the server to delete the type checksum with value hex1 hex2
              hex3 hex4.  The type and checksum values can be found in dccproc(8)
              and dccm(8) log files or computed with dccproc-QC.

              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 white-listed by recipients.

         stats [all | clear]
              displays current status and statistics from the current DCC server
              or for all known DCC servers.

         clients [-n] [-s] [-i] [-a] [max [thold]]
              displays some of the clients recently seen by the server.
              clients -n displays only the IP addresses and not the names of
              clients.  clients -s sorts the clients by the number of requests
              they have made.  clients -i counts clients with the same client-ID
              as single entities.  clients -a produces 24 hour average values.
              clients max displays only the most recent max clients.  clients max
              thold displays the most recent max clients that have made at least
              thold requests.

              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 the server was started or stats clear
              was last used are displayed.

         stop
              tells the DCC server to exit.

         reload IDs
              tells the DCC server to reload its DCC ids file.  This is handy to
              cause the server to notice changes in the file.

         flood check
              tells the DCC server to check for changes in the flod file and try
              to restart any of the streams to peers that are broken.

         flood shutdown
              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 flood shutdown or flood halt request increases
              a count of reasons why the server should not flood checksums.

         flood halt
              tells the DCC server to abruptly stop flooding checksums to and from
              peers.

         flood rewind server-ID
              tells the DCC server to ask its peer with server-ID to rewind and
              resend its stream of checksums.

         flood ffwd in server-ID
              tells the DCC server to ask its peer to "fast forward" or skip to
              the end of the incoming flood.

         flood ffwd out server-ID
              tells the DCC server to "fast forward" or skip to the current end of
              the flood to its peer.

         flood resume
              tells the DCC server to reduce the number of reasons to not flood
              checksums increased by flood shutdown and flood halt. When the num-
              ber of reasons reaches zero, the server tries to resume flooding.

         flood list
              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.

         flood stats [clear] { server-ID | all }
              displays counts of checksum reports sent and received by the current
              flooding connections to and from server-ID or all flooding connec-
              tions and then optionally clears the counts.

         DB unlock
              is used by dbclean to tell the server that the database expiration
              has begun.

         DB new
              is used by dbclean to tell the server that the database cleaning is
              complete.

         trace mode {on|off}
              turns the server's tracing mode on or off.  Mode must be one of:
                ALL    all tracing
                ADMN   administrative requests from cdcc
                ANON   errors by anonymous clients
                CLNT   errors by authenticated clients
                RLIM   rate-limited messages
                QUERY  all queries and reports
                RIDC   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     blacklisted clients

         cdcc exits 0 on success, and >0 if an error occurs in operations speci-
         fied on the command line.

## FILES

         /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 cdcc
                   if available.

## SEE ALSO

         dbclean(8), dcc(8), dccd(8), dblist(8), dccifd(8), dccm(8), dccproc(8),
         dccsight(8).

## HISTORY

         Implementation of cdcc was started at Rhyolite Software in 2000.  This
         describes version 1.2.74.

    FreeBSD 4.9                     March 20, 2005                     FreeBSD 4.9