Mercurial > notdcc
diff cdcc.html.in @ 0:c7f6b056b673
First import of vendor version
| author | Peter Gervai <grin@grin.hu> |
|---|---|
| date | Tue, 10 Mar 2009 13:49:58 +0100 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cdcc.html.in Tue Mar 10 13:49:58 2009 +0100 @@ -0,0 +1,436 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <TITLE>cdcc.0.8</TITLE> + <META http-equiv="Content-Style-Type" content="text/css"> + <STYLE type="text/css"> + BODY {background-color:white; color:black} + ADDRESS {font-size:smaller} + IMG.logo {width:6em; vertical-align:middle} + </STYLE> +</HEAD> +<BODY> +<PRE> +<!-- Manpage converted by man2html 3.0.1 --> +<B><A HREF="cdcc.html">cdcc(8)</A></B> Distributed Checksum Clearinghouse <B><A HREF="cdcc.html">cdcc(8)</A></B> + + +</PRE> +<H2><A NAME="NAME">NAME</A></H2><PRE> + <B>cdcc</B> -- Control Distributed Checksum Clearinghouse + + +</PRE> +<H2><A NAME="SYNOPSIS">SYNOPSIS</A></H2><PRE> + <B>cdcc</B> [<B>-Vdq</B>] [<B>-h</B> <I>homedir</I>] [<B>-c</B> <I>ids</I>] [<I>op1</I> <I>op2</I> <I>...</I> [<I>-</I>]] + + +</PRE> +<H2><A NAME="DESCRIPTION">DESCRIPTION</A></H2><PRE> + <B>Cdcc</B> is used to clear, control, and query the control file used by Dis- + tributed Checksum Clearinghouse clients such as <B><A HREF="dccm.html">dccm(8)</A></B>. 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 <I>map</I> file. While <B>cdcc</B> is set-UID, it uses the real UID only + when accessing the <I>map</I> file. It refuses to display sensitive information + such as passwords unless the real UID is the same as the effective UID. + Note that <B>cdcc</B> needs to be set to a UID that can read and write the <I>map</I> + file, but that UID need not be 0. + + <B>Cdcc</B> 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 <B>id</B> operation. If <B>cdcc</B> is run with a real UID + that can read the <I>ids</I> file and a password is not specified (see the + <B>password</B> operation), then the current password for the specified ID in + the <I>ids</I> file will be used. If no <I>ids</I> file is available and a password + and DCC ID are not specified, <B>cdcc</B> 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 <I>map</I> 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>ids</I> 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 <I>op1</I> <I>op2</I> <I>...</I> operations followed a <I>-</I> (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 + + <A NAME="OPTIONS"><B>OPTIONS</B></A> + The following options are available: + + <A NAME="OPTION-V"><B>-V</B></A> displays the version of the DCC controller. + + <A NAME="OPTION-d"><B>-d</B></A> enables debugging output from the DCC client software. Additional + <B>-d</B> options increase the number of messages. See the <B>debug</B> command. + + <A NAME="OPTION-q"><B>-q</B></A> quiets initial complaints about the map file and some messages about + successful commands. See the <B>quiet</B> command. + + <A NAME="OPTION-h"><B>-h</B></A> <I>homedir</I> + overrides the default DCC home directory, <I>@prefix@</I>. See the <B>homedir</B> + operation. + + <A NAME="OPTION-c"><B>-c</B></A> <I>ids</I> + specifies file containing DCC IDs and passwords known by the local + DCC server. An <I>ids</I> file that can be read by others cannot be used. + The format of the <I>ids</I> file is described in <B><A HREF="dccd.html">dccd(8)</A></B>. + + <I>op1</I> <I>op2</I> <I>...</I> + 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 <I>-</I> to specify + that additional commands should be read from stdin. + + <A NAME="OPERATIONS"><B>OPERATIONS</B></A> + Local operations include the following: + + <A NAME="OPERATION-help"><B>help</B></A> [<I>command</I>] + lists information about one or all available commands and opera- + tions. + + <A NAME="OPERATION-exit"><B>exit</B></A> stops <B>cdcc</B> + + <A NAME="OPERATION-grey"><B>grey</B></A> [<I>on</I> | <I>off</I>] + switches between DCC and greylist servers. + + <A NAME="OPERATION-homedir"><B>homedir</B></A> [<I>path</I>] + displays or specifies the DCC home directory. + + <A NAME="OPERATION-file"><B>file</B></A> [<I>map</I>] + displays or specifies the name or path of the map file. The string + "-" specifies the default file <I>map</I> in the DCC home directory. + + <A NAME="OPERATION-new-map"><B>new map</B></A> [<I>map</I>] + 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 <I>map</I> in the DCC home directory. + + <A NAME="OPERATION-delete"><B>delete</B></A> <I>host</I>[,<I>port</I>] + deletes the entry in the <I>map</I> file for <I>host</I> and UDP <I>port.</I> If + greylist mode has been set with the <B>grey on</B> command, the entry for + the grelist server at <I>host</I> is deleted. + + <A NAME="OPERATION-add"><B>add</B></A> <I>host</I>[,<I>port</I>] [<I>RTT+adj</I>|<I>RTT-adj</I>] [<I>Greylist</I>] [<I>client-ID</I> [password]] + adds an entry to the <I>map</I> file. The <I>port</I> 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 <I>RTT</I>. 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. + + <I>Greylist</I> marks an entry for a greylist servers. <I>Greylist</I> is + assumed if greylist mode has been set with the <B>grey on</B> command, See + <B><A HREF="dccd.html">dccd(8)</A></B>. + + If both the client-ID and the password are absent, the anonymous + client-ID, 1, is used. The string <I>anon</I> 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. + + <A NAME="OPERATION-load"><B>load</B></A> <I>info-file</I> + loads the current parameter file with the host names, port numbers, + IDs, and passwords in <I>info-file</I>. Standard input is understood if + <I>info-file</I> is "-". + + A suitable file can be created with the <B>info</B> operation. It con- + sists of ignored blank or comment lines starting with '#' and other + lines in the same format as the arguments to the <B>add</B> operation. + Note that output of the <B>info</B> command will lack passwords unless it + is run by a privileged user. + + <A NAME="OPERATION-host"><B>host</B></A> [<I>hostname</I>] + specifies the host name of the DCC server to which commands should + be sent. If <I>hostname</I> is "-", the current default DCC server is + chosen. + + <A NAME="OPERATION-port"><B>port</B></A> [<I>port</I>] + 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 <B>grey</B> command. + + <A NAME="OPERATION-password"><B>password</B></A> <I>secret</I> + specifies the password with which to sign commands sent to the DCC + server specified with the <B>server</B> and <B>port</B> operations. + + <A NAME="OPERATION-id"><B>id</B></A> [<I>ID</I>] + specifies or displays the numeric DCC ID for commands sent to the + DCC server specified with the <B>server</B> and <B>port</B> operations. If no + password is specified with the <B>password</B> command, the password is + sought in the local <I>ids</I>. + + <A NAME="OPERATION-info"><B>info</B></A> [<B>-N</B>] + displays information about the connections to DCC servers. It + starts with the current date and name of the current <I>map</I> file or + says that <B>cdcc</B> is using the implicit file created with the <B>server</B> + and <B>port</B> 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 <B>cdcc</B> 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. + + <B>-N</B> displays the reverse DNS name of each server. + + <A NAME="OPERATION-RTT"><B>RTT</B></A> [<B>-N</B>] + 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. + + <I>Beware</I> that when run with sufficient privilege, the <B>RTT</B> operation + is like the <B>info</B> and <B>load</B> operations and displays cleartext pass- + words. + + <B>-N</B> displays the reverse DNS name of each server. + + <A NAME="OPERATION-debug"><B>debug</B></A> 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 <B>-d</B>. + + Some operating systems do not include the functions required to + change the IP TTL. Others include the required functions but have + no apparent effect. + + <A NAME="OPERATION-quiet"><B>quiet</B></A> [<I>on</I> | <I>off</I>] + makes commands more quiet or more verbose. + + <A NAME="OPERATION-IPv6"><B>IPv6</B></A> [<I>on</I> | <I>off</I>] + sets a switch to cause clients using the map file to try to use + IPv6. + + <A NAME="OPERATION-SOCKS"><B>SOCKS</B></A> [<I>on</I> <I>off</I>] + 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. + + <A NAME="OPERATION-src"><B>src</B></A> [<I>-</I> | <I>IPaddress</I>] + displays or configures the source address of DCC client requests. + <I>-</I> removes the explicit configuration of the source, while <I>IPaddress</I> + sets it. This makes sense only on multi-homed hosts. It can be + useful for passing firewalls. + + <A NAME="DCC-SERVER-COMMANDS"><B>DCC SERVER COMMANDS</B></A> + Commands that can be sent to a DCC server include the following. Most of + the commands must be used with the server's <I>ID</I> specified with the <B>id</B> 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>ids</I> file. The server requires that the signature + match one of the passwords associated with the ID in its <I>ids</I> file. + + <A NAME="OPERATION-delck-type-hex1-hex2-hex3-hex4"><B>delck type hex1 hex2 hex3 hex4</B></A> + asks the server to delete the <I>type</I> checksum with value <I>hex1</I> <I>hex2</I> + <I>hex3</I> <I>hex4</I>. The type and checksum values can be found in <B><A HREF="dccproc.html">dccproc(8)</A></B> + and <B><A HREF="dccm.html">dccm(8)</A></B> log files or computed with <I>dccproc</I> <B>-QC</B>. + + 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. + + <A NAME="OPERATION-stats"><B>stats</B></A> [<I>all</I> | <I>clear</I>] + displays current status and statistics from the current DCC server + or for <I>all</I> known DCC servers. The server's counters will be cleared + after they are displayed when the server's ID has been specified + with the <B>id</B> <I>ID</I> operation. + + <A NAME="OPERATION-clients"><B>clients</B></A> [<B>-nsiaVAK</B>] [<I>max</I> [<I>thold</I>]] [<I>addr</I>[<I>/prefix</I>]] + displays some of the clients recently seen by the server. + <B>-n</B> displays only the IP addresses and not the names of clients. + <B>-s</B> sorts the clients by the number of requests they have made. + <B>-i</B> counts clients with the same client-ID as single entities. + <B>-a</B> produces 24 hour average numbers of requests. + <B>-A</B> displays only anonymous clients. + <B>-K</B> displays only clients using client-IDs. + <B>-V</B> includes the DCC protocol versions used by clients. + <I>max</I> displays only the <I>max</I> most recent clients. + <I>max</I> <I>thold</I> displays the most recent <I>max</I> clients that have made at + least <I>thold</I> requests. + <I>addr</I>[<I>/prefix</I>] 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 <B>stats clear</B> was last used are displayed. + + <A NAME="OPERATION-stop"><B>stop</B></A> + tells the DCC server to exit. + + <A NAME="OPERATION-system-stop"><B>system stop</B></A> + 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 <B>dbclean</B> when the DCC server is restarted. + + <A NAME="OPERATION-clean-stop"><B>clean stop</B></A> + tells the DCC server to exit after applying fsync() to the database. + + <A NAME="OPERATION-reload-IDs"><B>reload IDs</B></A> + tells the local DCC server to reload its DCC <I>ids</I> 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. + + <A NAME="OPERATION-flood-check"><B>flood check</B></A> + tells the DCC server to check for changes in the <I>flod</I> file and try + to restart any of the streams to peers that are broken. + + <A NAME="OPERATION-flood-shutdown"><B>flood shutdown</B></A> + 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 <B>flood shutdown</B> or <B>flood halt</B> request increases + a count of reasons why the server should not flood checksums. + + <A NAME="OPERATION-flood-halt"><B>flood halt</B></A> + tells the DCC server to abruptly stop flooding checksums to and from + peers. + + <A NAME="OPERATION-flood-rewind"><B>flood rewind</B></A> <I>server-ID</I> + tells the DCC server to ask its peer with <I>server-ID</I> to rewind and + resend its stream of checksums. + + <A NAME="OPERATION-flood-ffwd-in"><B>flood ffwd in</B></A> <I>server-ID</I> + tells the DCC server to ask its peer to "fast forward" or skip to + the end of the incoming flood. + + <A NAME="OPERATION-flood-ffwd-out"><B>flood ffwd out</B></A> <I>server-ID</I> + tells the DCC server to "fast forward" or skip to the current end of + the flood to its peer. + + <A NAME="OPERATION-flood-resume"><B>flood resume</B></A> + tells the DCC server to reduce the number of reasons to not flood + checksums increased by <B>flood shutdown</B> and <B>flood halt.</B> When the num- + ber of reasons reaches zero, the server tries to resume flooding. + + <A NAME="OPERATION-flood-list"><B>flood list</B></A> + 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. + + <A NAME="OPERATION-flood-stats"><B>flood stats</B></A> [<B>clear</B>] { <I>server-ID</I> | <I>all</I> } + displays counts of checksum reports sent and received by the current + flooding connections to and from <I>server-ID</I> or <I>all</I> flooding connec- + tions and then optionally clears the counts. + + <A NAME="OPERATION-DB-clean"><B>DB clean</B></A> + is used by <B>dbclean</B> to tell the server that the database expiration + has begun. + + <A NAME="OPERATION-DB-new"><B>DB new</B></A> + is used by <B>dbclean</B> to tell the server that the database cleaning is + complete. + + <A NAME="OPERATION-flush-cache"><B>flush cache</B></A> + tells the server to flush its cache and to keep it clean. + + <A NAME="OPERATION-cache-ok"><B>cache ok</B></A> + tells the server to resume normal operations after <B>flush cache</B>. + + <A NAME="OPERATION-clock-check"><B>clock check</B></A> + asks the DCC server to say how much its clock differs from the local + clock. + + <B>clock kludge +/-seconds</B> + adjusts the timestamps in server commands to make it possible to + control servers with inaccurate clocks. + + <A NAME="OPERATION-trace"><B>trace</B></A> <I>default</I> + turns on <I>ANON</I> and <I>CLNT</I> tracing and turns off all others. + + <A NAME="OPERATION-trace"><B>trace</B></A> <I>mode</I> <I>{on|off}</I> + turns the server's tracing <I>mode</I> on or off. <I>Mode</I> must be one of: + <I>ADMN</I> administrative requests from <B>cdcc</B> + <I>ANON</I> errors by anonymous clients + <I>CLNT</I> errors by authenticated clients + <I>RLIM</I> rate-limited messages + <I>QUERY</I> all queries and reports + <I>RIDC</I> messages concerning the report-ID cache that is used to + detect duplicate reports from clients + <I>FLOOD</I> messages about inter-server flooding connections + <I>FLOOD2</I> messages about flooded reports + <I>IDS</I> unknown server-IDs in flooded reports + <I>BL</I> blacklisted clients + <I>DB</I> odd database events + <I>WLIST</I> reports of whitelisted checksums from authenticated, not + anonymous DCC clients + + <A NAME="OPERATION-cdcc"><B>cdcc</B></A> exits with 0 on success, and >0 if an error occurs in operations + specified on the command line. + + +</PRE> +<H2><A NAME="FILES">FILES</A></H2><PRE> + <A NAME="FILE-@prefix@">@prefix@</A> DCC home directory + <A NAME="FILE-map">map</A> memory mapped file in the home DCC home directory of server + host names, port numbers, passwords, measured round trip times + (RTT), and so forth. + <A NAME="FILE-ids">ids</A> list of IDs and passwords, as described in <B><A HREF="dccd.html">dccd(8)</A></B>. It is only + required by systems running the DCC server, but is used by <B>cdcc</B> + if available. + + +</PRE> +<H2><A NAME="SEE-ALSO">SEE ALSO</A></H2><PRE> + <B><A HREF="dbclean.html">dbclean(8)</A></B>, <B><A HREF="dcc.html">dcc(8)</A></B>, <B><A HREF="dccd.html">dccd(8)</A></B>, <B><A HREF="dblist.html">dblist(8)</A></B>, <B><A HREF="dccifd.html">dccifd(8)</A></B>, <B><A HREF="dccm.html">dccm(8)</A></B>, <B><A HREF="dccproc.html">dccproc(8)</A></B>, + <B><A HREF="dccsight.html">dccsight(8)</A></B>. + + +</PRE> +<H2><A NAME="HISTORY">HISTORY</A></H2><PRE> + Implementation of <B>cdcc</B> was started at Rhyolite Software in 2000. This + document describes version 1.3.103. + + February 26, 2009 +</PRE> +<HR> +<ADDRESS> +Man(1) output converted with +<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a> +modified for the DCC $Date 2001/04/29 03:22:18 $ +<BR> +<A HREF="http://www.dcc-servers.net/dcc/"> + <IMG SRC="http://logos.dcc-servers.net/border.png" + class=logo ALT="DCC logo"> + </A> +<A HREF="http://validator.w3.org/check?uri=referer"> + <IMG class=logo ALT="Valid HTML 4.01 Strict" + SRC="http://www.w3.org/Icons/valid-html401"> + </A> +</ADDRESS> +</BODY> +</HTML>