Man Pages

cdcc(8) - phpMan cdcc(8) - phpMan

Command: man perldoc info search(apropos)  


cdcc(8)                   BSD System Manager's Manual                  cdcc(8)

NAME
     cdcc - Control Distributed Checksum Clearinghouse

SYNOPSIS
     cdcc [-VBdq] [-h homedir] [-c ids] [op1 op2 ... [-]]

DESCRIPTION
     Cdcc is used to clear, control, and query the control file used by Distributed 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 contained 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 pass-
     word 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 message complaining about a "privileged operation."

     Commands and operations are read from the command line or from stdin.  A series of op1 op2 ... operations fol-
     lowed 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.  Two or more -V options show the options with which it was
          built.

     -B   sends error messages from the DCC server to both stderr and stdout instead of only stderr.

     -d   enables debugging output from the DCC client software.  Additional -d options increase the number of mes-
          sages.  See the debug command.

     -q   quiets initial complaints about the map file and some messages about successful commands.  See the quiet
          command.

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

     -c ids
          specifies the file containing DCC IDs and passwords known by local DCC servers.  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 com-
          mands should be read from stdin.

   OPERATIONS
     Local operations include the following:

     help [command]
           lists information about one or all available commands and operations.

     exit  stops cdcc

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

     homedir [path]
           displays or specifies the DCC home directory, /var/dcc.

     file [map]
           displays or specifies the name or path of the map file.  The string "-" specifies the default file
           /var/dcc/map.

     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 between -2000 and +2000 and follows the string RTT.  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.

           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 anonymous 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.  Stan-
           dard input is understood if info-file is "-".

           A suitable file can be created with the info operation.  It consists of ignored blank or comment lines
           starting with '#' and other lines in the same format as the arguments to the add operation.  Note that out-
           put 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 cur-
           rent 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 setting 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 displayed 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 passwords.

           -N displays the reverse DNS name of each server.

     debug 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 -d.

           Some operating systems do not include the functions required to change the IP TTL.  Others include the
           required functions but have no apparent effect.

     quiet [on | off]
           makes commands more quiet or more verbose.

     IPv6 [on | off | only]
           clients to try to use IPv6 and IPv4, IPv4 only, or IPv6 only.

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

     src [- |] IPaddress[,IPv6address]
           displays or configures the source address of DCC client requests.  - removes the explicit configuration of
           the source, while IPaddress or IPaddress,IPv6address sets it.  This makes sense only on multi-homed hosts.
           It can be useful for passing firewalls.

   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 command.  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 whitelisted by
          recipients.

     stats [all | clear]
          displays current status and statistics from the current DCC server or for all known DCC servers.  The
          server's counters will be cleared after they are displayed when the server's ID has been specified with the
          id ID operation.

     clients [-nsiaVAK] [-I id] [max [thold]] [addr[/prefix]]
          display some of the clients recently seen by the server.
          -n     display only the IP addresses and not the names of clients.
          -s     sort the clients by the number of requests they have made.
          -i     count clients with the same client-ID as single entities.
          -I id  display information only about clients using client-ID id.
          -a     produce 24 hour average numbers of requests.
          -A     display only anonymous clients.
          -K     display only clients using client-IDs other than the anonymous ID of 1.
          -V     include the DCC protocol versions used by clients.
          max    display only the max most recent clients.
          max thold display the most recent max clients that have made at least thold requests.
          addr[/prefix] 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
                 /var/dcc/blacklist file are not displayed unless explicitly 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 stats clear are displayed.

     stop
          tells the DCC server to exit.

     system stop
          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 automati-
          cally by dbclean when the DCC server is restarted.

     clean stop
          tells the DCC server to exit after applying fsync() to the database.

     reload IDs
          tells the local DCC server to reload its DCC ids 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.

     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 rea-
          sons 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 number 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 connections and then optionally clears the counts.

     DB clean
          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.

     flush cache
          tells the server to flush its cache and to keep it clean.

     cache ok
          tells the server to resume normal operations after flush cache.

     clock check
          asks the DCC server to say how much its clock differs from the local clock.

     clock kludge +/-seconds
          adjusts the timestamps in server commands to make it possible to control servers with inaccurate clocks.

     trace default
          turns on ANON and CLNT tracing and turns off all others.

     trace mode {on|off}
          turns the server's tracing mode on or off.  Mode must be one of:
            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
            FLOOD1  messages about inter-server flooding connections
            FLOOD2  messages about flooded reports
            IDS     unknown server-IDs in flooded reports
            BL      blacklisted clients
            DB      odd database events
            WLIST   reports of whitelisted checksums from authenticated, not anonymous DCC clients

     cdcc exits with 0 on success, and >0 if an error occurs in operations specified on the command line.

FILES
     /var/dcc  default DCC home directory unless changed by the homedir operation.
     map       memory mapped file in the home DCC home directory of server host names, port numbers, passwords, mea-
               sured 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 document describes version 1.3.158.

                                April 03, 2015