Mercurial > notdcc

comparison cdcc.0 @ 0:c7f6b056b673

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First import of vendor version
author Peter Gervai <grin@grin.hu>
date Tue, 10 Mar 2009 13:49:58 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:c7f6b056b673
1 cdcc(8) Distributed Checksum Clearinghouse cdcc(8)
2
3 NNAAMMEE
4 ccddcccc -- Control Distributed Checksum Clearinghouse
5
6 SSYYNNOOPPSSIISS
7 ccddcccc [--VVddqq] [--hh _h_o_m_e_d_i_r] [--cc _i_d_s] [_o_p_1 _o_p_2 _._._. [_-]]
8
9 DDEESSCCRRIIPPTTIIOONN
10 CCddcccc is used to clear, control, and query the control file used by Dis-
11 tributed Checksum Clearinghouse clients such as dccm(8). The host names,
12 UDP port numbers, IDs, and passwords local clients use to talk to servers
13 as well as IP addresses, round trip times, and other information are con-
14 tained in the _m_a_p file. While ccddcccc is set-UID, it uses the real UID only
15 when accessing the _m_a_p file. It refuses to display sensitive information
16 such as passwords unless the real UID is the same as the effective UID.
17 Note that ccddcccc needs to be set to a UID that can read and write the _m_a_p
18 file, but that UID need not be 0.
19
20 CCddcccc is also used to send commands to DCC servers to tell them to stop,
21 reload their lists of DCC IDs, turn on tracing, and so forth.
22
23 Many commands sent to DCC servers require a numeric DCC ID and a password
24 recognized by the server. A DCC password is a 1-32 character string that
25 does not contain blank, tab, newline or carriage return characters. The
26 ID is specified with the iidd operation. If ccddcccc is run with a real UID
27 that can read the _i_d_s file and a password is not specified (see the
28 ppaasssswwoorrdd operation), then the current password for the specified ID in
29 the _i_d_s file will be used. If no _i_d_s file is available and a password
30 and DCC ID are not specified, ccddcccc uses the anonymous DCC client-ID. DCC
31 servers do not expect a password from clients using the anonymous client-
32 ID, but they also won't honor control requests.
33
34 Operations that modify the _m_a_p file can only be performed when the real
35 UID is sufficient to modify the file directly. Trying to perform an
36 operation that requires a password without specifying a server-ID or
37 without using a UID that can access the _i_d_s file produces an error mes-
38 sage complaining about a "privileged operation."
39
40 Commands and operations are read from the command line or from stdin. A
41 series of _o_p_1 _o_p_2 _._._. operations followed a _- (a dash) causes operations
42 to be read from stdin after the command line operations are processed.
43 Semi-colons or newlines separate commands in UNIX command-line "words,"
44 as well as when commands are read from stdin. Since each command line
45 operation must be a shell "word," quotes are often required as in
46
47 % cdcc "load map.txt"
48 or
49
50 % cdcc "host localhost;info" stats
51
52 OOPPTTIIOONNSS
53 The following options are available:
54
55 --VV displays the version of the DCC controller.
56
57 --dd enables debugging output from the DCC client software. Additional
58 --dd options increase the number of messages. See the ddeebbuugg command.
59
60 --qq quiets initial complaints about the map file and some messages about
61 successful commands. See the qquuiieett command.
62
63 --hh _h_o_m_e_d_i_r
64 overrides the default DCC home directory, _/_v_a_r_/_d_c_c. See the hhoommeeddiirr
65 operation.
66
67 --cc _i_d_s
68 specifies file containing DCC IDs and passwords known by the local
69 DCC server. An _i_d_s file that can be read by others cannot be used.
70 The format of the _i_d_s file is described in dccd(8).
71
72 _o_p_1 _o_p_2 _._._.
73 are operations or commands such as "id 100; stop". Commands or
74 operations specified on the command line are performed before the
75 first interactive request. The last command can be _- to specify
76 that additional commands should be read from stdin.
77
78 OOPPEERRAATTIIOONNSS
79 Local operations include the following:
80
81 hheellpp [_c_o_m_m_a_n_d]
82 lists information about one or all available commands and opera-
83 tions.
84
85 eexxiitt stops ccddcccc
86
87 ggrreeyy [_o_n | _o_f_f]
88 switches between DCC and greylist servers.
89
90 hhoommeeddiirr [_p_a_t_h]
91 displays or specifies the DCC home directory.
92
93 ffiillee [_m_a_p]
94 displays or specifies the name or path of the map file. The string
95 "-" specifies the default file _m_a_p in the DCC home directory.
96
97 nneeww mmaapp [_m_a_p]
98 creates a new, empty file for DCC server host names, port numbers,
99 passwords, and so forth. There must not already be a file of the
100 same name. The default is _m_a_p in the DCC home directory.
101
102 ddeelleettee _h_o_s_t[,_p_o_r_t]
103 deletes the entry in the _m_a_p file for _h_o_s_t and UDP _p_o_r_t_. If
104 greylist mode has been set with the ggrreeyy oonn command, the entry for
105 the grelist server at _h_o_s_t is deleted.
106
107 aadddd _h_o_s_t[,_p_o_r_t] [_R_T_T_+_a_d_j|_R_T_T_-_a_d_j] [_G_r_e_y_l_i_s_t] [_c_l_i_e_n_t_-_I_D [password]]
108 adds an entry to the _m_a_p file. The _p_o_r_t can be "-" to specify the
109 default DCC server port number.
110
111 An adjustment to the round trip time is a multiple of 10 millisec-
112 onds between -4000 and +4000 following the string _R_T_T. The adjust-
113 ment is added to the average measured round trip time when the DCC
114 client software picks the "nearest" DCC server, or the server with
115 the smallest RTT. If an IP address is mentioned more than once in
116 the list of servers, for example because it is among the addresses
117 for more than one server name, conflicts among RTT adjustments are
118 resolved by picking the adjustment with the largest absolute value.
119
120 _G_r_e_y_l_i_s_t marks an entry for a greylist servers. _G_r_e_y_l_i_s_t is
121 assumed if greylist mode has been set with the ggrreeyy oonn command, See
122 dccd(8).
123
124 If both the client-ID and the password are absent, the anonymous
125 client-ID, 1, is used. The string _a_n_o_n is equivalent to the anony-
126 mous client-ID. A null password string is assumed if the password
127 is missing and the client-ID is 1 or also missing.
128
129 llooaadd _i_n_f_o_-_f_i_l_e
130 loads the current parameter file with the host names, port numbers,
131 IDs, and passwords in _i_n_f_o_-_f_i_l_e. Standard input is understood if
132 _i_n_f_o_-_f_i_l_e is "-".
133
134 A suitable file can be created with the iinnffoo operation. It con-
135 sists of ignored blank or comment lines starting with '#' and other
136 lines in the same format as the arguments to the aadddd operation.
137 Note that output of the iinnffoo command will lack passwords unless it
138 is run by a privileged user.
139
140 hhoosstt [_h_o_s_t_n_a_m_e]
141 specifies the host name of the DCC server to which commands should
142 be sent. If _h_o_s_t_n_a_m_e is "-", the current default DCC server is
143 chosen.
144
145 ppoorrtt [_p_o_r_t]
146 specifies the UDP port number of the DCC server to which commands
147 should be sent. The default is 6277 or 6276 depending on the set-
148 ting of the greylist mode controlled with the ggrreeyy command.
149
150 ppaasssswwoorrdd _s_e_c_r_e_t
151 specifies the password with which to sign commands sent to the DCC
152 server specified with the sseerrvveerr and ppoorrtt operations.
153
154 iidd [_I_D]
155 specifies or displays the numeric DCC ID for commands sent to the
156 DCC server specified with the sseerrvveerr and ppoorrtt operations. If no
157 password is specified with the ppaasssswwoorrdd command, the password is
158 sought in the local _i_d_s.
159
160 iinnffoo [--NN]
161 displays information about the connections to DCC servers. It
162 starts with the current date and name of the current _m_a_p file or
163 says that ccddcccc is using the implicit file created with the sseerrvveerr
164 and ppoorrtt operations. It then says when host names will next be
165 resolved into IP addresses, the smallest round trip time to the IP
166 addresses of known DCC servers. The host name, UDP port number (or
167 dash if it is the default), DCC client-ID, and password (if ccddcccc is
168 used by a privileged user) are shown in one line per configured DCC
169 server.
170
171 The currently preferred IP address is indicated by an asterisk.
172 The "brand" of the server, its DCC ID, and its IP address are dis-
173 played in one line per IP address. The performance of the server
174 at each IP address in the most recent 32 operations is displayed in
175 a second line. The second line ends with the measured delay
176 imposed by the server on requests with this client's ID.
177
178 --NN displays the reverse DNS name of each server.
179
180 RRTTTT [--NN]
181 measures the round trip time to the DCC servers. It does this by
182 discarding accumulated information and forcing a probe of all
183 listed server IP addresses.
184
185 _B_e_w_a_r_e that when run with sufficient privilege, the RRTTTT operation
186 is like the iinnffoo and llooaadd operations and displays cleartext pass-
187 words.
188
189 --NN displays the reverse DNS name of each server.
190
191 ddeebbuugg Op Ar on | off | TTL=x
192 increases or decreases debugging information from the DCC client
193 software or sets the IP TTL on queries to the server. See --dd.
194
195 Some operating systems do not include the functions required to
196 change the IP TTL. Others include the required functions but have
197 no apparent effect.
198
199 qquuiieett [_o_n | _o_f_f]
200 makes commands more quiet or more verbose.
201
202 IIPPvv66 [_o_n | _o_f_f]
203 sets a switch to cause clients using the map file to try to use
204 IPv6.
205
206 SSOOCCKKSS [_o_n _o_f_f]
207 sets a switch to cause DCC clients using the map to use the SOCKS5
208 protocol, if they have been built with a SOCKS library. The socks
209 library linked with the DCC client must be configured appropri-
210 ately, often including knowing which DCC servers must be connected
211 via the SOCKS proxy and which can be reached directly. DCC clients
212 use SOCKS functions such as Rsendto() with all or no servers
213 depending on the setting of this switch.
214
215 ssrrcc [_- | _I_P_a_d_d_r_e_s_s]
216 displays or configures the source address of DCC client requests.
217 _- removes the explicit configuration of the source, while _I_P_a_d_d_r_e_s_s
218 sets it. This makes sense only on multi-homed hosts. It can be
219 useful for passing firewalls.
220
221 DDCCCC SSEERRVVEERR CCOOMMMMAANNDDSS
222 Commands that can be sent to a DCC server include the following. Most of
223 the commands must be used with the server's _I_D specified with the iidd com-
224 mand. The specified ID is included in the commands sent to the server
225 The command itself is digitally signed with the first password associated
226 with the ID in the _i_d_s file. The server requires that the signature
227 match one of the passwords associated with the ID in its _i_d_s file.
228
229 ddeellcckk ttyyppee hheexx11 hheexx22 hheexx33 hheexx44
230 asks the server to delete the _t_y_p_e checksum with value _h_e_x_1 _h_e_x_2
231 _h_e_x_3 _h_e_x_4. The type and checksum values can be found in dccproc(8)
232 and dccm(8) log files or computed with _d_c_c_p_r_o_c --QQCC.
233
234 There are very few situations where it makes sense to bother to
235 delete checksums. For example, mail that was accidentally reported
236 with a target count of "MANY" is either private and so will not be
237 seen by other people and so will not be affected, or it is bulk and
238 its source so must have already been whitelisted by recipients.
239
240 ssttaattss [_a_l_l | _c_l_e_a_r]
241 displays current status and statistics from the current DCC server
242 or for _a_l_l known DCC servers. The server's counters will be cleared
243 after they are displayed when the server's ID has been specified
244 with the iidd _I_D operation.
245
246 cclliieennttss [--nnssiiaaVVAAKK] [_m_a_x [_t_h_o_l_d]] [_a_d_d_r[_/_p_r_e_f_i_x]]
247 displays some of the clients recently seen by the server.
248 --nn displays only the IP addresses and not the names of clients.
249 --ss sorts the clients by the number of requests they have made.
250 --ii counts clients with the same client-ID as single entities.
251 --aa produces 24 hour average numbers of requests.
252 --AA displays only anonymous clients.
253 --KK displays only clients using client-IDs.
254 --VV includes the DCC protocol versions used by clients.
255 _m_a_x displays only the _m_a_x most recent clients.
256 _m_a_x _t_h_o_l_d displays the most recent _m_a_x clients that have made at
257 least _t_h_o_l_d requests.
258 _a_d_d_r[_/_p_r_e_f_i_x] restricts the results to the DCC client with that IP
259 address or clients with addresses in that CIDR block.
260
261 The mechanism that implements this command involves asking the DCC
262 server for the first approximately 100 clients, then the second
263 about 100, and so on, If entries change position in the complete
264 list maintained by the server between requests, the displayed list
265 will have duplicate or missing entries. Only clients heard from
266 since ssttaattss cclleeaarr was last used are displayed.
267
268 ssttoopp
269 tells the DCC server to exit.
270
271 ssyysstteemm ssttoopp
272 tells the DCC server to exit so that the operating system can be
273 shut down. This tells the DCC server on some systems to delete the
274 dcc_db.hash file to speed system shut down. The file will be
275 rebuilt automatically by ddbbcclleeaann when the DCC server is restarted.
276
277 cclleeaann ssttoopp
278 tells the DCC server to exit after applying fsync() to the database.
279
280 rreellooaadd IIDDss
281 tells the local DCC server to reload its DCC _i_d_s file immediately.
282 This command is not strictly needed. Every several minutes, the DCC
283 server notices if the file has been changed and automatically reads
284 it.
285
286 fflloooodd cchheecckk
287 tells the DCC server to check for changes in the _f_l_o_d file and try
288 to restart any of the streams to peers that are broken.
289
290 fflloooodd sshhuuttddoowwnn
291 tells the DCC server to cleanly stop flooding checksums to and from
292 peers. The server will wait for sending and receiving peers to
293 agree to stop. Each fflloooodd sshhuuttddoowwnn or fflloooodd hhaalltt request increases
294 a count of reasons why the server should not flood checksums.
295
296 fflloooodd hhaalltt
297 tells the DCC server to abruptly stop flooding checksums to and from
298 peers.
299
300 fflloooodd rreewwiinndd _s_e_r_v_e_r_-_I_D
301 tells the DCC server to ask its peer with _s_e_r_v_e_r_-_I_D to rewind and
302 resend its stream of checksums.
303
304 fflloooodd ffffwwdd iinn _s_e_r_v_e_r_-_I_D
305 tells the DCC server to ask its peer to "fast forward" or skip to
306 the end of the incoming flood.
307
308 fflloooodd ffffwwdd oouutt _s_e_r_v_e_r_-_I_D
309 tells the DCC server to "fast forward" or skip to the current end of
310 the flood to its peer.
311
312 fflloooodd rreessuummee
313 tells the DCC server to reduce the number of reasons to not flood
314 checksums increased by fflloooodd sshhuuttddoowwnn and fflloooodd hhaalltt.. When the num-
315 ber of reasons reaches zero, the server tries to resume flooding.
316
317 fflloooodd lliisstt
318 displays the list of current incoming and outgoing floods. Each
319 line contains the server-ID of the peer, the IP address and port
320 used for the outgoing flood, the address for the incoming flood if
321 different, and the host name. Only the server-IDs of flooding peers
322 are disclosed with the server's ID.
323
324 fflloooodd ssttaattss [cclleeaarr] { _s_e_r_v_e_r_-_I_D | _a_l_l }
325 displays counts of checksum reports sent and received by the current
326 flooding connections to and from _s_e_r_v_e_r_-_I_D or _a_l_l flooding connec-
327 tions and then optionally clears the counts.
328
329 DDBB cclleeaann
330 is used by ddbbcclleeaann to tell the server that the database expiration
331 has begun.
332
333 DDBB nneeww
334 is used by ddbbcclleeaann to tell the server that the database cleaning is
335 complete.
336
337 fflluusshh ccaacchhee
338 tells the server to flush its cache and to keep it clean.
339
340 ccaacchhee ookk
341 tells the server to resume normal operations after fflluusshh ccaacchhee.
342
343 cclloocckk cchheecckk
344 asks the DCC server to say how much its clock differs from the local
345 clock.
346
347 cclloocckk kklluuddggee ++//--sseeccoonnddss
348 adjusts the timestamps in server commands to make it possible to
349 control servers with inaccurate clocks.
350
351 ttrraaccee _d_e_f_a_u_l_t
352 turns on _A_N_O_N and _C_L_N_T tracing and turns off all others.
353
354 ttrraaccee _m_o_d_e _{_o_n_|_o_f_f_}
355 turns the server's tracing _m_o_d_e on or off. _M_o_d_e must be one of:
356 _A_D_M_N administrative requests from ccddcccc
357 _A_N_O_N errors by anonymous clients
358 _C_L_N_T errors by authenticated clients
359 _R_L_I_M rate-limited messages
360 _Q_U_E_R_Y all queries and reports
361 _R_I_D_C messages concerning the report-ID cache that is used to
362 detect duplicate reports from clients
363 _F_L_O_O_D messages about inter-server flooding connections
364 _F_L_O_O_D_2 messages about flooded reports
365 _I_D_S unknown server-IDs in flooded reports
366 _B_L blacklisted clients
367 _D_B odd database events
368 _W_L_I_S_T reports of whitelisted checksums from authenticated, not
369 anonymous DCC clients
370
371 ccddcccc exits with 0 on success, and >0 if an error occurs in operations
372 specified on the command line.
373
374 FFIILLEESS
375 /var/dcc DCC home directory
376 map memory mapped file in the home DCC home directory of server
377 host names, port numbers, passwords, measured round trip times
378 (RTT), and so forth.
379 ids list of IDs and passwords, as described in dccd(8). It is only
380 required by systems running the DCC server, but is used by ccddcccc
381 if available.
382
383 SSEEEE AALLSSOO
384 dbclean(8), dcc(8), dccd(8), dblist(8), dccifd(8), dccm(8), dccproc(8),
385 dccsight(8).
386
387 HHIISSTTOORRYY
388 Implementation of ccddcccc was started at Rhyolite Software in 2000. This
389 document describes version 1.3.103.
390
391 February 26, 2009