--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/cdcc.8.in	Tue Mar 10 13:49:58 2009 +0100
@@ -0,0 +1,641 @@
+.\" Copyright (c) 2008 by Rhyolite Software, LLC
+.\"
+.\" This agreement is not applicable to any entity which sells anti-spam
+.\" solutions to others or provides an anti-spam solution as part of a
+.\" security solution sold to other entities, or to a private network
+.\" which employs the DCC or uses data provided by operation of the DCC
+.\" but does not provide corresponding data to other users.
+.\"
+.\" Permission to use, copy, modify, and distribute this software without
+.\" changes for any purpose with or without fee is hereby granted, provided
+.\" that the above copyright notice and this permission notice appear in all
+.\" copies and any distributed versions or copies are either unchanged
+.\" or not called anything similar to "DCC" or "Distributed Checksum
+.\" Clearinghouse".
+.\"
+.\" Parties not eligible to receive a license under this agreement can
+.\" obtain a commercial license to use DCC by contacting Rhyolite Software
+.\" at sales@rhyolite.com.
+.\"
+.\" A commercial license would be for Distributed Checksum and Reputation
+.\" Clearinghouse software.  That software includes additional features.  This
+.\" free license for Distributed ChecksumClearinghouse Software does not in any
+.\" way grant permision to use Distributed Checksum and Reputation Clearinghouse
+.\" software
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND RHYOLITE SOFTWARE, LLC DISCLAIMS ALL
+.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL RHYOLITE SOFTWARE, LLC
+.\" BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+.\" SOFTWARE.
+.\"
+.\" Rhyolite Software DCC 1.3.103-1.95 $Revision$
+.\"
+.Dd February 26, 2009
+.ds volume-ds-DCC Distributed Checksum Clearinghouse
+.Dt cdcc 8 DCC
+.Os " "
+.Sh NAME
+.Nm cdcc
+.Nd Control Distributed Checksum Clearinghouse
+.Sh SYNOPSIS
+.Nm cdcc
+.Op Fl Vdq
+.Op Fl h Ar homedir
+.Op Fl c Ar ids
+.Op Ar op1 op2 ... Op Ar -
+.Sh DESCRIPTION
+.Nm Cdcc
+is used to clear, control, and query the control file used
+by Distributed Checksum Clearinghouse
+clients such as
+.Xr 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
+.Pa map
+file.
+While
+.Nm
+is set-UID, it uses the real UID only when accessing the
+.Pa map
+file.
+It refuses to display sensitive information such as passwords
+unless the real UID is the same as the effective UID.
+Note that
+.Nm
+needs to be set to a UID that can read and write the
+.Pa map
+file, but that UID need not be 0.
+.Pp
+.Nm 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.
+.Pp
+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
+.Ic id
+operation.
+If
+.Nm cdcc
+is run with a real UID that can read the
+.Pa ids
+file and a password is not specified
+(see the
+.Ic password
+operation),
+then the current password for the specified ID in the
+.Pa ids
+file will be used.
+If no
+.Pa ids
+file is available and a password and DCC ID are not specified,
+.Nm
+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.
+.Pp
+Operations that modify the
+.Pa 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
+.Pa ids
+file produces an error message complaining
+about a "privileged operation."
+.Pp
+Commands and operations are read from the command line or from stdin.
+A series of
+.Ar op1 op2 ...
+operations followed a
+.Ar -
+(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
+.Bd -ragged -offset indent
+% cdcc
+.Qq load map.txt
+.Ed
+or
+.Bd -ragged -offset indent
+% cdcc
+.Qq host localhost;info
+stats
+.Ed
+.Ss OPTIONS
+The following options are available:
+.Bl -tag -width 3n
+.It Fl V
+displays the version of the DCC controller.
+.It Fl d
+enables debugging output from the DCC client software.
+Additional
+.Fl d
+options increase the number of messages.
+See the
+.Ic debug
+command.
+.It Fl q
+quiets initial complaints about the map file
+and some messages about successful commands.
+See the
+.Ic quiet
+command.
+.It Fl h Ar homedir
+overrides the default DCC home directory,
+.Pa @prefix@ .
+See the
+.Ic homedir
+operation.
+.It Fl c Ar ids
+specifies file containing DCC IDs and passwords known by the local DCC server.
+An
+.Pa ids
+file that can be read by others cannot be used.
+The format of the
+.Pa ids
+file is described in
+.Xr dccd 8 .
+.It Ar 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
+.Ar "-"
+to specify that additional commands should be read from stdin.
+.El
+.Ss OPERATIONS
+Local operations include the following:
+.Bl -tag -width info
+.It Ic help Op Ar command
+lists information about one or all available commands and operations.
+.It Ic exit
+stops
+.Nm
+.It Ic grey Op Ar on | off
+switches between DCC and greylist servers.
+.It Ic homedir Op Ar path
+displays or specifies the DCC home directory.
+.It Ic file Op Ar map
+displays or specifies the name or path of the map file.
+The string "-" specifies the default file
+.Pa map
+in the DCC home directory.
+.It Ic new map Op Ar 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
+.Pa map
+in the DCC home directory.
+.It Ic delete Ar host Ns Xo
+.Ns Op , Ns Ar port
+.Xc
+deletes the entry in the
+.Pa map
+file for
+.Ar host
+and UDP
+.Ar port.
+If greylist mode has been set with the
+.Ic grey\ on
+command,
+the entry for the grelist server at
+.Ar host
+is deleted.
+.It Ic add Ar host Ns Xo
+.Ns Op , Ns Ar port
+.Op Ar RTT+adj Ns | Ns Ar RTT-adj
+.Op Ar Greylist
+.Op Ar client-ID Op password
+.Xc
+adds an entry to the
+.Pa map
+file.
+The
+.Ar port
+can be "-" to specify the default DCC server port number.
+.Pp
+An adjustment to the round trip time is a multiple of 10 milliseconds
+between -4000 and +4000 following the string
+.Ar 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.
+.Pp
+.Ar Greylist
+marks an entry for a greylist servers.
+.Ar Greylist
+is assumed if greylist mode has been set with
+the
+.Ic grey\ on
+command,
+See
+.Xr dccd 8 .
+.Pp
+If both the client-ID and the password are absent,
+the anonymous client-ID, 1, is used.
+The string
+.Ar 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.
+.It Ic load Ar info-file
+loads the current parameter file with the host names, port numbers, IDs, and
+passwords in
+.Ar info-file .
+Standard input is understood if
+.Ar info-file
+is "-".
+.Pp
+A suitable file can be created with the
+.Ic info
+operation.
+It consists of ignored blank or comment lines starting with '#' and
+other lines in the same format as the arguments to the
+.Ic add
+operation.
+Note that output of the
+.Ic info
+command will lack passwords unless it is run by a privileged user.
+.It Ic host Op Ar hostname
+specifies the host name of the DCC server to which commands should be sent.
+If
+.Ar hostname
+is "-", the current default DCC server is chosen.
+.It Ic port Op Ar 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
+.Ic grey
+command.
+.It Ic password Ar secret
+specifies the password with which to sign commands sent to the DCC
+server specified with the
+.Ic server
+and
+.Ic port
+operations.
+.It Ic id Op Ar ID
+specifies or displays the numeric DCC ID for commands sent to the DCC
+server specified with the
+.Ic server
+and
+.Ic port
+operations.
+If no password is specified with the
+.Ic password
+command,
+the password is sought in the local
+.Pa ids .
+.It Ic info Op Fl N
+displays information about the connections to DCC servers.
+It starts with the current date and name of the current
+.Ar map
+file or
+says that
+.Nm
+is using the implicit file created with the
+.Ic server
+and
+.Ic 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
+.Nm
+is used by a privileged user)
+are shown in one line per configured DCC server.
+.Pp
+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.
+.Pp
+.Fl N
+displays the reverse DNS name of each server.
+.It Ic RTT Op Fl 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.
+.Pp
+.Em Beware
+that when run with sufficient privilege, the
+.Ic RTT
+operation is like the
+.Ic info
+and
+.Ic load
+operations and displays cleartext passwords.
+.Pp
+.Fl N
+displays the reverse DNS name of each server.
+.It Ic debug Xo
+Op Ar on | off | TTL=x
+.Xc
+increases or decreases debugging information from the DCC client software
+or sets the IP TTL on queries to the server.
+See
+.Fl d .
+.Pp
+Some operating systems do not include the functions required to change the
+IP TTL.
+Others include the required functions
+but have no apparent effect.
+.It Ic quiet Op Ar on | off
+makes commands more quiet or more verbose.
+.It Ic IPv6 Op Ar on | off
+sets a switch to cause clients using the map file to try to use IPv6.
+.It Ic SOCKS Op Ar 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 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.
+.It Ic src Op Ar - | IPaddress
+displays or configures the source address of DCC client requests.
+.Ar -
+removes the explicit configuration of the source, while
+.Ar IPaddress
+sets it.
+This makes sense only on multi-homed hosts.
+It can be useful for passing firewalls.
+.El
+.Pp
+.Ss 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 
+.Ar ID
+specified with the
+.Ic 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
+.Pa ids
+file.
+The server requires that the signature match one of the passwords associated
+with the ID in its
+.Pa ids
+file.
+.Bl -tag -width xxx
+.It Ic delck type hex1 hex2 hex3 hex4
+asks the server to delete the
+.Ar type
+checksum with value
+.Ar hex1 hex2 hex3 hex4 .
+The type and checksum values can be found in
+.Xr dccproc 8
+and
+.Xr dccm 8
+log files
+or computed with
+.Em dccproc Fl QC .
+.Pp
+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.
+.It Ic stats Op Ar all | clear
+displays current status and statistics from the current DCC server
+or for
+.Ar 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
+.Ic id Ar ID
+operation.
+.It Ic clients Xo
+.Op Fl nsiaVAK
+.Op Ar max Op Ar thold
+.Op Ar addr Ns Op Ar /prefix
+.Xc
+displays some of the clients recently seen by the server.
+.Bl -hang -compact -width xxx
+.It Fl n
+displays only the IP addresses and not the names of clients.
+.It Fl s
+sorts the clients by the number of requests they have made.
+.It Fl i
+counts clients with the same client-ID as single entities.
+.It Fl a
+produces 24 hour average numbers of requests.
+.It Fl A
+displays only anonymous clients.
+.It Fl K
+displays only clients using client-IDs.
+.It Fl V
+includes the DCC protocol versions used by clients.
+.It Ar max
+displays only the
+.Ar max
+most recent clients.
+.It Ar max Ar thold
+displays the most recent
+.Ar max
+clients that have made at least
+.Ar thold
+requests.
+.It Ar addr Ns Op Ar /prefix
+restricts the results to the DCC client with that IP address or
+clients with addresses in that CIDR block.
+.El
+.Pp
+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
+.Ic stats clear
+was last used are displayed.
+.It Ic stop
+tells the DCC server to exit.
+.It Ic 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 automatically by
+.Nm dbclean
+when the DCC server is restarted.
+.It Ic clean stop
+tells the DCC server to exit after applying fsync() to the database.
+.It Ic reload IDs
+tells the local DCC server to reload its DCC
+.Pa 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.
+.It Ic flood check
+tells the DCC server to check for changes in the
+.Pa flod
+file and try to restart any of the streams to peers that are broken.
+.It Ic 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
+.Ic flood shutdown
+or
+.Ic flood halt
+request increases a count of reasons why the server should not
+flood checksums.
+.It Ic flood halt
+tells the DCC server to abruptly stop flooding checksums to and from peers.
+.It Ic flood rewind Ar server-ID
+tells the DCC server to ask its peer with
+.Ar server-ID
+to rewind and resend its stream of checksums.
+.It Ic flood ffwd in Ar server-ID
+tells the DCC server to ask its peer to "fast forward" or skip to
+the end of the incoming flood.
+.It Ic flood ffwd out Ar server-ID
+tells the DCC server to "fast forward" or skip to the current end
+of the flood to its peer.
+.It Ic flood resume
+tells the DCC server to reduce the number of reasons to
+not flood checksums increased by
+.Ic flood shutdown
+and
+.Ic flood halt.
+When the number of reasons reaches zero,
+the server tries to resume flooding.
+.It Ic 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.
+.It Ic flood stats Xo
+.Op Ic clear
+.No {
+.Ar server-ID | all
+.No }
+.Xc
+displays counts of checksum reports sent and received by the current
+flooding connections to and from
+.Ar server-ID
+or
+.Ar all
+flooding connections
+and then optionally clears the counts.
+.It Ic DB clean
+is used by
+.Nm dbclean
+to tell the server that the database expiration has begun.
+.It Ic DB new
+is used by
+.Nm dbclean
+to tell the server that the database cleaning is complete.
+.It Ic flush cache
+tells the server to flush its cache and to keep it clean.
+.It Ic cache ok
+tells the server to resume normal operations after
+.Ic flush cache .
+.It Ic clock check
+asks the DCC server to say how much its clock differs from the local clock.
+.It Ic clock kludge +/-seconds
+adjusts the timestamps in server commands to make it possible to
+control servers with inaccurate clocks.
+.It Ic trace Ar default
+turns on
+.Ar ANON
+and
+.Ar CLNT
+tracing
+and turns off all others.
+.It Ic trace Ar mode {on|off}
+turns the server's tracing 
+.Ar mode
+on or off.
+.Ar Mode
+must be one of:
+.Bl -tag -width FLOOD2 -offset 2n -compact
+.It Ar ADMN
+administrative requests from
+.Nm
+.It Ar ANON
+errors by anonymous clients
+.It Ar CLNT
+errors by authenticated clients
+.It Ar RLIM
+rate-limited messages
+.It Ar QUERY
+all queries and reports
+.It Ar RIDC
+messages concerning the report-ID cache that is used
+to detect duplicate reports from clients
+.It Ar FLOOD
+messages about inter-server flooding connections
+.It Ar FLOOD2
+messages about flooded reports
+.It Ar IDS
+unknown server-IDs in flooded reports
+.It Ar BL
+blacklisted clients
+.It Ar DB
+odd database events
+.It Ar WLIST
+reports of whitelisted checksums from authenticated, not anonymous DCC clients
+.El
+.El
+.Pp
+.Nm
+exits with 0 on success,
+and >0 if an error occurs in operations specified on the command line.
+.Sh FILES
+.Bl -tag -width @prefix@ -compact
+.It Pa @prefix@
+DCC home directory
+.It Pa 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.
+.It Pa ids
+list of IDs and passwords, as described in
+.Xr dccd 8 .
+It is only required by systems running the DCC server,
+but is used by
+.Nm
+if available.
+.El
+.Sh SEE ALSO
+.Xr dbclean 8 ,
+.Xr dcc 8 ,
+.Xr dccd 8 ,
+.Xr dblist 8 ,
+.Xr dccifd 8 ,
+.Xr dccm 8 ,
+.Xr dccproc 8 ,
+.Xr dccsight 8 .
+.Sh HISTORY
+Implementation of
+.Nm
+was started at Rhyolite Software in 2000.
+This document describes version 1.3.103.