Mercurial > notdcc

comparison cdcc.8.in @ 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 .\" Copyright (c) 2008 by Rhyolite Software, LLC
2 .\"
3 .\" This agreement is not applicable to any entity which sells anti-spam
4 .\" solutions to others or provides an anti-spam solution as part of a
5 .\" security solution sold to other entities, or to a private network
6 .\" which employs the DCC or uses data provided by operation of the DCC
7 .\" but does not provide corresponding data to other users.
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software without
10 .\" changes for any purpose with or without fee is hereby granted, provided
11 .\" that the above copyright notice and this permission notice appear in all
12 .\" copies and any distributed versions or copies are either unchanged
13 .\" or not called anything similar to "DCC" or "Distributed Checksum
14 .\" Clearinghouse".
15 .\"
16 .\" Parties not eligible to receive a license under this agreement can
17 .\" obtain a commercial license to use DCC by contacting Rhyolite Software
18 .\" at sales@rhyolite.com.
19 .\"
20 .\" A commercial license would be for Distributed Checksum and Reputation
21 .\" Clearinghouse software. That software includes additional features. This
22 .\" free license for Distributed ChecksumClearinghouse Software does not in any
23 .\" way grant permision to use Distributed Checksum and Reputation Clearinghouse
24 .\" software
25 .\"
26 .\" THE SOFTWARE IS PROVIDED "AS IS" AND RHYOLITE SOFTWARE, LLC DISCLAIMS ALL
27 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
28 .\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL RHYOLITE SOFTWARE, LLC
29 .\" BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
30 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
31 .\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
32 .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
33 .\" SOFTWARE.
34 .\"
35 .\" Rhyolite Software DCC 1.3.103-1.95 $Revision$
36 .\"
37 .Dd February 26, 2009
38 .ds volume-ds-DCC Distributed Checksum Clearinghouse
39 .Dt cdcc 8 DCC
40 .Os " "
41 .Sh NAME
42 .Nm cdcc
43 .Nd Control Distributed Checksum Clearinghouse
44 .Sh SYNOPSIS
45 .Nm cdcc
46 .Op Fl Vdq
47 .Op Fl h Ar homedir
48 .Op Fl c Ar ids
49 .Op Ar op1 op2 ... Op Ar -
50 .Sh DESCRIPTION
51 .Nm Cdcc
52 is used to clear, control, and query the control file used
53 by Distributed Checksum Clearinghouse
54 clients such as
55 .Xr dccm 8 .
56 The host names, UDP port numbers, IDs, and passwords local clients use
57 to talk to servers as well as IP addresses, round trip times, and other
58 information are contained in the
59 .Pa map
60 file.
61 While
62 .Nm
63 is set-UID, it uses the real UID only when accessing the
64 .Pa map
65 file.
66 It refuses to display sensitive information such as passwords
67 unless the real UID is the same as the effective UID.
68 Note that
69 .Nm
70 needs to be set to a UID that can read and write the
71 .Pa map
72 file, but that UID need not be 0.
73 .Pp
74 .Nm Cdcc
75 is also used to send commands to DCC servers to tell them
76 to stop, reload their lists of DCC IDs, turn on tracing, and so forth.
77 .Pp
78 Many commands sent to DCC servers require a numeric DCC ID
79 and a password recognized by the server.
80 A DCC password is a 1-32 character string that does not contain
81 blank, tab, newline or carriage return characters.
82 The ID is specified with the
83 .Ic id
84 operation.
85 If
86 .Nm cdcc
87 is run with a real UID that can read the
88 .Pa ids
89 file and a password is not specified
90 (see the
91 .Ic password
92 operation),
93 then the current password for the specified ID in the
94 .Pa ids
95 file will be used.
96 If no
97 .Pa ids
98 file is available and a password and DCC ID are not specified,
99 .Nm
100 uses the anonymous DCC client-ID.
101 DCC servers do not expect a password from clients using the
102 anonymous client-ID,
103 but they also won't honor control requests.
104 .Pp
105 Operations that modify the
106 .Pa map
107 file can only be performed when
108 the real UID is sufficient to modify the file directly.
109 Trying to perform an operation that requires a password without
110 specifying a server-ID or without using a UID that can access the
111 .Pa ids
112 file produces an error message complaining
113 about a "privileged operation."
114 .Pp
115 Commands and operations are read from the command line or from stdin.
116 A series of
117 .Ar op1 op2 ...
118 operations followed a
119 .Ar -
120 (a dash) causes operations to be read from stdin after the command line
121 operations are processed.
122 Semi-colons or newlines separate commands in UNIX command-line "words,"
123 as well as when commands are read from stdin.
124 Since each command line operation must be a shell "word," quotes are
125 often required as in
126 .Bd -ragged -offset indent
127 % cdcc
128 .Qq load map.txt
129 .Ed
130 or
131 .Bd -ragged -offset indent
132 % cdcc
133 .Qq host localhost;info
134 stats
135 .Ed
136 .Ss OPTIONS
137 The following options are available:
138 .Bl -tag -width 3n
139 .It Fl V
140 displays the version of the DCC controller.
141 .It Fl d
142 enables debugging output from the DCC client software.
143 Additional
144 .Fl d
145 options increase the number of messages.
146 See the
147 .Ic debug
148 command.
149 .It Fl q
150 quiets initial complaints about the map file
151 and some messages about successful commands.
152 See the
153 .Ic quiet
154 command.
155 .It Fl h Ar homedir
156 overrides the default DCC home directory,
157 .Pa @prefix@ .
158 See the
159 .Ic homedir
160 operation.
161 .It Fl c Ar ids
162 specifies file containing DCC IDs and passwords known by the local DCC server.
163 An
164 .Pa ids
165 file that can be read by others cannot be used.
166 The format of the
167 .Pa ids
168 file is described in
169 .Xr dccd 8 .
170 .It Ar op1 op2 ...
171 are operations or commands such as "id\ 100;\ stop".
172 Commands or operations specified on the command line are performed
173 before the first interactive request.
174 The last command can be
175 .Ar "-"
176 to specify that additional commands should be read from stdin.
177 .El
178 .Ss OPERATIONS
179 Local operations include the following:
180 .Bl -tag -width info
181 .It Ic help Op Ar command
182 lists information about one or all available commands and operations.
183 .It Ic exit
184 stops
185 .Nm
186 .It Ic grey Op Ar on | off
187 switches between DCC and greylist servers.
188 .It Ic homedir Op Ar path
189 displays or specifies the DCC home directory.
190 .It Ic file Op Ar map
191 displays or specifies the name or path of the map file.
192 The string "-" specifies the default file
193 .Pa map
194 in the DCC home directory.
195 .It Ic new map Op Ar map
196 creates a new, empty file for DCC server host names,
197 port numbers, passwords, and so forth.
198 There must not already be a file of the same name.
199 The default is
200 .Pa map
201 in the DCC home directory.
202 .It Ic delete Ar host Ns Xo
203 .Ns Op , Ns Ar port
204 .Xc
205 deletes the entry in the
206 .Pa map
207 file for
208 .Ar host
209 and UDP
210 .Ar port.
211 If greylist mode has been set with the
212 .Ic grey\ on
213 command,
214 the entry for the grelist server at
215 .Ar host
216 is deleted.
217 .It Ic add Ar host Ns Xo
218 .Ns Op , Ns Ar port
219 .Op Ar RTT+adj Ns | Ns Ar RTT-adj
220 .Op Ar Greylist
221 .Op Ar client-ID Op password
222 .Xc
223 adds an entry to the
224 .Pa map
225 file.
226 The
227 .Ar port
228 can be "-" to specify the default DCC server port number.
229 .Pp
230 An adjustment to the round trip time is a multiple of 10 milliseconds
231 between -4000 and +4000 following the string
232 .Ar RTT .
233 The adjustment is added to the average measured round trip time when
234 the DCC client software picks the "nearest" DCC server, or the server
235 with the smallest RTT.
236 If an IP address is mentioned more than once in the list of servers,
237 for example because it is among the addresses for more than one server name,
238 conflicts among RTT adjustments are resolved by picking
239 the adjustment with the largest absolute value.
240 .Pp
241 .Ar Greylist
242 marks an entry for a greylist servers.
243 .Ar Greylist
244 is assumed if greylist mode has been set with
245 the
246 .Ic grey\ on
247 command,
248 See
249 .Xr dccd 8 .
250 .Pp
251 If both the client-ID and the password are absent,
252 the anonymous client-ID, 1, is used.
253 The string
254 .Ar anon
255 is equivalent to the anonymous client-ID.
256 A null password string is assumed if the password is missing
257 and the client-ID is 1 or also missing.
258 .It Ic load Ar info-file
259 loads the current parameter file with the host names, port numbers, IDs, and
260 passwords in
261 .Ar info-file .
262 Standard input is understood if
263 .Ar info-file
264 is "-".
265 .Pp
266 A suitable file can be created with the
267 .Ic info
268 operation.
269 It consists of ignored blank or comment lines starting with '#' and
270 other lines in the same format as the arguments to the
271 .Ic add
272 operation.
273 Note that output of the
274 .Ic info
275 command will lack passwords unless it is run by a privileged user.
276 .It Ic host Op Ar hostname
277 specifies the host name of the DCC server to which commands should be sent.
278 If
279 .Ar hostname
280 is "-", the current default DCC server is chosen.
281 .It Ic port Op Ar port
282 specifies the UDP port number of the DCC server to which commands should
283 be sent.
284 The default is 6277 or 6276 depending on the setting of the greylist
285 mode controlled with the
286 .Ic grey
287 command.
288 .It Ic password Ar secret
289 specifies the password with which to sign commands sent to the DCC
290 server specified with the
291 .Ic server
292 and
293 .Ic port
294 operations.
295 .It Ic id Op Ar ID
296 specifies or displays the numeric DCC ID for commands sent to the DCC
297 server specified with the
298 .Ic server
299 and
300 .Ic port
301 operations.
302 If no password is specified with the
303 .Ic password
304 command,
305 the password is sought in the local
306 .Pa ids .
307 .It Ic info Op Fl N
308 displays information about the connections to DCC servers.
309 It starts with the current date and name of the current
310 .Ar map
311 file or
312 says that
313 .Nm
314 is using the implicit file created with the
315 .Ic server
316 and
317 .Ic port
318 operations.
319 It then says when host names will next be resolved into IP addresses,
320 the smallest round trip time to the IP addresses of known DCC servers.
321 The host name, UDP port number (or dash if it is the default),
322 DCC client-ID, and password (if
323 .Nm
324 is used by a privileged user)
325 are shown in one line per configured DCC server.
326 .Pp
327 The currently preferred IP address is indicated by an asterisk.
328 The "brand" of the server, its DCC ID, and its IP address
329 are displayed in one line per IP address.
330 The performance of the server at each IP address in the most recent
331 32 operations is displayed in a second line.
332 The second line ends with the measured delay imposed by the server on requests
333 with this client's ID.
334 .Pp
335 .Fl N
336 displays the reverse DNS name of each server.
337 .It Ic RTT Op Fl N
338 measures the round trip time to the DCC servers.
339 It does this by discarding accumulated information and forcing
340 a probe of all listed server IP addresses.
341 .Pp
342 .Em Beware
343 that when run with sufficient privilege, the
344 .Ic RTT
345 operation is like the
346 .Ic info
347 and
348 .Ic load
349 operations and displays cleartext passwords.
350 .Pp
351 .Fl N
352 displays the reverse DNS name of each server.
353 .It Ic debug Xo
354 Op Ar on | off | TTL=x
355 .Xc
356 increases or decreases debugging information from the DCC client software
357 or sets the IP TTL on queries to the server.
358 See
359 .Fl d .
360 .Pp
361 Some operating systems do not include the functions required to change the
362 IP TTL.
363 Others include the required functions
364 but have no apparent effect.
365 .It Ic quiet Op Ar on | off
366 makes commands more quiet or more verbose.
367 .It Ic IPv6 Op Ar on | off
368 sets a switch to cause clients using the map file to try to use IPv6.
369 .It Ic SOCKS Op Ar on off
370 sets a switch to cause DCC clients using the map to use the SOCKS5
371 protocol, if they have been built with a SOCKS library.
372 The socks library linked with the DCC client must be configured appropriately,
373 often including knowing which DCC servers must be connected via the
374 SOCKS proxy and which can be reached directly.
375 DCC clients use SOCKS functions such as Rsendto() with all or no servers
376 depending on the setting of this switch.
377 .It Ic src Op Ar - | IPaddress
378 displays or configures the source address of DCC client requests.
379 .Ar -
380 removes the explicit configuration of the source, while
381 .Ar IPaddress
382 sets it.
383 This makes sense only on multi-homed hosts.
384 It can be useful for passing firewalls.
385 .El
386 .Pp
387 .Ss DCC SERVER COMMANDS
388 Commands that can be sent to a DCC server include the following.
389 Most of the commands must be used with the server's
390 .Ar ID
391 specified with the
392 .Ic id
393 command.
394 The specified ID is included in the commands sent to the server
395 The command itself is digitally signed with the first password associated
396 with the ID in the
397 .Pa ids
398 file.
399 The server requires that the signature match one of the passwords associated
400 with the ID in its
401 .Pa ids
402 file.
403 .Bl -tag -width xxx
404 .It Ic delck type hex1 hex2 hex3 hex4
405 asks the server to delete the
406 .Ar type
407 checksum with value
408 .Ar hex1 hex2 hex3 hex4 .
409 The type and checksum values can be found in
410 .Xr dccproc 8
411 and
412 .Xr dccm 8
413 log files
414 or computed with
415 .Em dccproc Fl QC .
416 .Pp
417 There are very few situations where it makes sense to bother to delete
418 checksums.
419 For example, mail that was accidentally reported with a target
420 count of "MANY" is either private and so will not be seen by other
421 people and so will not be affected, or it is bulk and its source
422 so must have already been whitelisted by recipients.
423 .It Ic stats Op Ar all | clear
424 displays current status and statistics from the current DCC server
425 or for
426 .Ar all
427 known DCC servers.
428 The server's counters will be cleared after they are displayed
429 when the server's ID has been specified with the
430 .Ic id Ar ID
431 operation.
432 .It Ic clients Xo
433 .Op Fl nsiaVAK
434 .Op Ar max Op Ar thold
435 .Op Ar addr Ns Op Ar /prefix
436 .Xc
437 displays some of the clients recently seen by the server.
438 .Bl -hang -compact -width xxx
439 .It Fl n
440 displays only the IP addresses and not the names of clients.
441 .It Fl s
442 sorts the clients by the number of requests they have made.
443 .It Fl i
444 counts clients with the same client-ID as single entities.
445 .It Fl a
446 produces 24 hour average numbers of requests.
447 .It Fl A
448 displays only anonymous clients.
449 .It Fl K
450 displays only clients using client-IDs.
451 .It Fl V
452 includes the DCC protocol versions used by clients.
453 .It Ar max
454 displays only the
455 .Ar max
456 most recent clients.
457 .It Ar max Ar thold
458 displays the most recent
459 .Ar max
460 clients that have made at least
461 .Ar thold
462 requests.
463 .It Ar addr Ns Op Ar /prefix
464 restricts the results to the DCC client with that IP address or
465 clients with addresses in that CIDR block.
466 .El
467 .Pp
468 The mechanism that implements this command involves
469 asking the DCC server for the first approximately 100 clients, then
470 the second about 100, and so on,
471 If entries change position in the complete list maintained by the server
472 between requests,
473 the displayed list will have duplicate or missing entries.
474 Only clients heard from since
475 .Ic stats clear
476 was last used are displayed.
477 .It Ic stop
478 tells the DCC server to exit.
479 .It Ic system stop
480 tells the DCC server to exit so that the operating system can be shut down.
481 This tells the DCC server on some systems to delete the dcc_db.hash file
482 to speed system shut down.
483 The file will be rebuilt automatically by
484 .Nm dbclean
485 when the DCC server is restarted.
486 .It Ic clean stop
487 tells the DCC server to exit after applying fsync() to the database.
488 .It Ic reload IDs
489 tells the local DCC server to reload its DCC
490 .Pa ids
491 file immediately.
492 This command is not strictly needed.
493 Every several minutes, the DCC server notices if the file has been changed
494 and automatically reads it.
495 .It Ic flood check
496 tells the DCC server to check for changes in the
497 .Pa flod
498 file and try to restart any of the streams to peers that are broken.
499 .It Ic flood shutdown
500 tells the DCC server to cleanly stop flooding checksums to and from peers.
501 The server will wait for sending and receiving peers to agree to stop.
502 Each
503 .Ic flood shutdown
504 or
505 .Ic flood halt
506 request increases a count of reasons why the server should not
507 flood checksums.
508 .It Ic flood halt
509 tells the DCC server to abruptly stop flooding checksums to and from peers.
510 .It Ic flood rewind Ar server-ID
511 tells the DCC server to ask its peer with
512 .Ar server-ID
513 to rewind and resend its stream of checksums.
514 .It Ic flood ffwd in Ar server-ID
515 tells the DCC server to ask its peer to "fast forward" or skip to
516 the end of the incoming flood.
517 .It Ic flood ffwd out Ar server-ID
518 tells the DCC server to "fast forward" or skip to the current end
519 of the flood to its peer.
520 .It Ic flood resume
521 tells the DCC server to reduce the number of reasons to
522 not flood checksums increased by
523 .Ic flood shutdown
524 and
525 .Ic flood halt.
526 When the number of reasons reaches zero,
527 the server tries to resume flooding.
528 .It Ic flood list
529 displays the list of current incoming and outgoing floods.
530 Each line contains the server-ID of the peer,
531 the IP address and port used for the outgoing flood,
532 the address for the incoming flood if different,
533 and the host name.
534 Only the server-IDs of flooding peers are disclosed with the server's ID.
535 .It Ic flood stats Xo
536 .Op Ic clear
537 .No {
538 .Ar server-ID | all
539 .No }
540 .Xc
541 displays counts of checksum reports sent and received by the current
542 flooding connections to and from
543 .Ar server-ID
544 or
545 .Ar all
546 flooding connections
547 and then optionally clears the counts.
548 .It Ic DB clean
549 is used by
550 .Nm dbclean
551 to tell the server that the database expiration has begun.
552 .It Ic DB new
553 is used by
554 .Nm dbclean
555 to tell the server that the database cleaning is complete.
556 .It Ic flush cache
557 tells the server to flush its cache and to keep it clean.
558 .It Ic cache ok
559 tells the server to resume normal operations after
560 .Ic flush cache .
561 .It Ic clock check
562 asks the DCC server to say how much its clock differs from the local clock.
563 .It Ic clock kludge +/-seconds
564 adjusts the timestamps in server commands to make it possible to
565 control servers with inaccurate clocks.
566 .It Ic trace Ar default
567 turns on
568 .Ar ANON
569 and
570 .Ar CLNT
571 tracing
572 and turns off all others.
573 .It Ic trace Ar mode {on|off}
574 turns the server's tracing
575 .Ar mode
576 on or off.
577 .Ar Mode
578 must be one of:
579 .Bl -tag -width FLOOD2 -offset 2n -compact
580 .It Ar ADMN
581 administrative requests from
582 .Nm
583 .It Ar ANON
584 errors by anonymous clients
585 .It Ar CLNT
586 errors by authenticated clients
587 .It Ar RLIM
588 rate-limited messages
589 .It Ar QUERY
590 all queries and reports
591 .It Ar RIDC
592 messages concerning the report-ID cache that is used
593 to detect duplicate reports from clients
594 .It Ar FLOOD
595 messages about inter-server flooding connections
596 .It Ar FLOOD2
597 messages about flooded reports
598 .It Ar IDS
599 unknown server-IDs in flooded reports
600 .It Ar BL
601 blacklisted clients
602 .It Ar DB
603 odd database events
604 .It Ar WLIST
605 reports of whitelisted checksums from authenticated, not anonymous DCC clients
606 .El
607 .El
608 .Pp
609 .Nm
610 exits with 0 on success,
611 and >0 if an error occurs in operations specified on the command line.
612 .Sh FILES
613 .Bl -tag -width @prefix@ -compact
614 .It Pa @prefix@
615 DCC home directory
616 .It Pa map
617 memory mapped file in the home DCC home directory of server host names,
618 port numbers,
619 passwords, measured round trip times (RTT), and so forth.
620 .It Pa ids
621 list of IDs and passwords, as described in
622 .Xr dccd 8 .
623 It is only required by systems running the DCC server,
624 but is used by
625 .Nm
626 if available.
627 .El
628 .Sh SEE ALSO
629 .Xr dbclean 8 ,
630 .Xr dcc 8 ,
631 .Xr dccd 8 ,
632 .Xr dblist 8 ,
633 .Xr dccifd 8 ,
634 .Xr dccm 8 ,
635 .Xr dccproc 8 ,
636 .Xr dccsight 8 .
637 .Sh HISTORY
638 Implementation of
639 .Nm
640 was started at Rhyolite Software in 2000.
641 This document describes version 1.3.103.