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 Distributed Checksum Clearinghouse clients such as dc

cm(8). The host names, UDP port numbers, IDs, and passwords lo

cal 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 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 opera

tion), 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 "privi

leged 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 complaints about the map file, and some messages about

successful commands.

-h homedir

overrides the default DCC home directory, which is of

ten /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 dc

cd(8).

op1 op2 ...

are operations or commands such as "id 100; stop".

Commands or operations specified on the command line are per

formed 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 operations.

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 di

rectory.

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 milliseconds between -4000 and +4000 following 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. Standard input is

understood if info-file is "-".

A suitable file can be created with the info opera

tion. It consists of blank lines and comment lines starting with

'#' other lines in the same format as the arguments to the add

and load operations. 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 de

pending 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 opera

tions.

id [ID]

specifies or displays the numeric DCC ID for commands

sent to the DCC server specified with the server and port opera

tions. 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 ad

dress 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

cleartext passwords.
-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 li

brary. The socks library linked with the DCC client must be con

figured 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.

DCC SERVER COMMANDS

Commands that can be sent to a DCC server include the fol

lowing. 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 acciden

tally reported with a target count of "MANY" is either private

and so will not be seen by other people and so will not be af

fected, 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 serv

er.
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 aver

age 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 bro

ken.

flood shutdown

tells the DCC server to cleanly stop flooding checksums

to and from peers. The server will wait for sending and receiv

ing 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 check

sums 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 re

sume flooding.

flood list

displays the list of current incoming and outgoing

floods. Each line contains the server-ID of the peer, the IP ad

dress 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 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 opera

tions specified 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 dc

cd(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.

BSD December 8, 2007

BSD