chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / doc / man / actsync.8
1 .\" By: Landon Curt Noll        chongo@toad.com         (chongo was here /\../\)
2 .\"
3 .\" Copyright (c) Landon Curt Noll, 1993.
4 .\" All rights reserved.
5 .\"
6 .\" Permission to use and modify is hereby granted so long as this
7 .\" notice remains.  Use at your own risk.  No warranty is implied.
8 .\"
9 .\" @(#) $Id: actsync.8 6731 2004-05-16 22:00:46Z rra $
10 .\" @(#) Under RCS control in /usr/local/news/src/inn/local/RCS/actsync.8,v
11 .\"
12 .TH ACTSYNC 8
13 .SH NAME
14 actsync, actsyncd \- synchronize newsgroups
15 .SH SYNOPSIS
16 .B actsync
17 [\fB\-A\fP] [\fB\-b\fP\fI hostid\fP] [\fB\-d\fP\fI hostid\fP] [\fB\-g\fP\fI max\fP]
18 .br
19            [\fB\-i\fP\fI ignore_file\fP] [\fB\-I\fP\fI hostid\fP] [\fB\-k\fP] [\fB\-l\fP\fI hostid\fP] [\fB\-m\fP]
20 .br
21            [\fB\-n\fP\fI name\fP] [\fB\-o\fP\fI fmt\fP] [\fB\-p\fP\fI min_%_unchg\fP] [\fB\-q\fP\fI hostid\fP]
22 .br
23            [\fB\-s\fP\fI size\fP] [\fB\-t\fP\fI hostid\fP] [\fB\-T\fP] [\fB\-v\fP\fI verbosity\fP]
24 .br
25            [\fB\-z\fP\fI sec\fP] [\fIhost1\fP] \fIhost2\fP
26 .sp 1
27 .B actsyncd
28 [\fB\-x\fP] \fIactsync.cfg\fP [\fIdebug_level\fP [\fIdebug_outfmt\fP] ]
29 .SH DESCRIPTION
30 .IR Actsync (8)
31 permits one to synchronize, compare, or merge two
32 .I active
33 files.
34 With this utility one may add, change, or remove newsgroups on the
35 local news server to make it similar to the list the newsgroups
36 found on another system or file.
37 The synchronization need not be exact.
38 Local differences in newsgroup lists may be maintained and preserved.
39 Certain newsgroup errors may be detected and optionally corrected.
40 .PP
41 There are several reasons to run
42 .IR actsync (8)
43 (or
44 .IR actsyncd (8)),
45 on a periodic basis.
46 Among the reasons are:
47 .in +0.5i
48 .sp 1
49 A control message to add, change or remove a newsgroup
50 may fail to reach your site.
51 .sp 1
52 Your
53 .I control.ctl
54 may be out of date or incomplete.
55 .sp 1
56 News articles for a new newsgroup can arrive ahead (sometimes days ahead)
57 of the control message.
58 .sp 1
59 Control messages may be forged, thus bypassing the restrictions
60 found in
61 .I control.ctl .
62 .sp 1
63 Your
64 .I active
65 file may have been trashed.
66 .sp 1
67 .in -0.5i
68 .PP
69 If
70 .I host1
71 or
72 .I host2
73 begins with a
74 .B ``.''
75 or
76 .BR ``/'' ,
77 then it is assumed to be a name of a file containing information in the
78 .IR active (5)
79 format.
80 The
81 .IR getlist (1)
82 utility may be used to obtain copy a remote system's active file
83 via its NNTP server, or an FTP client program can retrieve such a
84 file from an FTP archive (such as
85 ftp://ftp.isc.org/pub/usenet/CONFIG/active; see more about this below).
86 Newsgroup information from a file
87 may be treated as if it was obtained from a host.
88 In this man page
89 .I host1
90 and
91 .I host2
92 are called hosts, even though they may be file names.
93 .PP
94 If a host argument does not begin with
95 .B ``.''
96 or
97 .BR ``/'' ,
98 is assumed to be a
99 hostname or Internet address.
100 In this case,
101 .IR actsync (8)
102 will attempt to use the
103 .B NNTP
104 protocol to obtain a copy of the the specified system's active file.
105 If the host argument contains a
106 .B ``:'' ,
107 the right side will be considerd the port to connect to on the remote system.
108 If no port number is specified,
109 .IR actsync (8)
110 will connect to port 119.
111 .PP
112 Regardless how the active file information is obtained,
113 the actions of
114 .IR actsync (8)
115 remain the same.
116 .PP
117 If only one host is specified, it is assumed to be
118 .IR host2 ;
119 if
120 .IR host1
121 is not specified, it assumed to be the default local
122 NNTP server as specified by the
123 .B NNTPSERVER
124 environment variable, or by the
125 .B server
126 value found in
127 .IR inn.conf .
128 .PP
129 The newsgroup synchronization, by default, involves all newsgroups
130 found on both hosts.
131 One may also synchronize a subset of newsgroups by directing
132 .IR actsync (8)
133 to ignore certain newsgroups from both systems.  Only newsgroups with
134 valid names will be synchronized.  To be valid, a newsgroup name must
135 consist only of alphanumeric characters, ``.'', ``+'', ``-'', and ``_''.
136 One may not have two ``.''s in a row.  The first character must be
137 alphanumeric, as must any character following a ``.''.  The name may not
138 end in a ``.'' character.
139 .PP
140 The
141 .IR actsyncd (8)
142 daemon provides a convenient interface to configure and run
143 .IR actsync (8).
144 If a host is not initially reachable,
145 the daemon will retry up to 9 additional times, waiting 6 minutes before
146 each retry.
147 This daemon runs in the foreground, sending output to standard output
148 and standard error.
149 .PP
150 If the \fB\-x\fP flag is given to
151 .IR actsyncd (8),
152 then a
153 .IR ctlinnd\ xexec
154 will be used instead of a
155 .IR ctlinnd\ reload
156 to load the newly modified active file.
157 .PP
158 The configuration filename for the daemon is given as a
159 commandline argument, usually
160 .I <pathetc in inn.conf>/actsync.cfg
161 The config file can contain the following options:
162 .sp 1
163 .in +0.5i
164 .nf
165 \fBhost=\fP\fIhost2\fP
166 \fBftppath=\fP\fI/remote/path/to/active/file\fP
167 \fBspool=\fP\fI<normally patharticles in inn.conf>\fP
168 \fBignore_file=\fP\fIignore_file\fP
169 \fBflags=\fP\fIactsyncd\fP(8) options
170 .fi
171 .in -0.5i
172 .sp 1
173 The \fBhost\fP, \fBignore_file\fP, and \fBflags\fP lines are mandatory.
174 .sp 1
175 The keyword must start at the beginning of the line, and there
176 may be no whitespace before the
177 .B ``=''
178 character.
179 Blank lines are ignored.
180 Comment lines start with
181 .B ``#''
182 and are ignored.
183 Any other lines may produce undefined results.
184 .sp 1
185 The \fBhost\fP config file line refers to the \fIhost2\fP parameter to
186 .IR actsync (8).
187 The \fBftppath\fP directive causes the machine named in the \fBhost\fP
188 line to accessed as an ftp server, retrieving the file named.  If
189 the filename ends in \fB.gz\fP or \fB.Z\fP, then it will automatically
190 be uncompressed after retrieval.
191 The \fBspool\fP config file lines determines where the top of the
192 news spool tree is to be found.
193 The \fBignore_file\fP config file line names the ignore file to be
194 used by
195 .IR actsync (8).
196 The \fBflags\fP config file line contains any flags that you wish to pass to
197 .IR actsync (8).
198 .sp 1
199 Note that the \fB\-i ignore_file\fP option
200 and the \fB-o format\fP option
201 should not be given
202 in the \fBflags=\fP line because they are automatically taken care of by
203 .IR actsyncd (8).
204 .sp 1
205 INN is shipped with default values of \fIftp.isc.org\fP for \fBhost\fP
206 and \fI/pub/usenet/CONFIG/active\fP for \fBftppath\fP.  You can read
207 about the policies used for maintaining that active file at
208 \fIftp://ftp.isc.org/pub/usenet/CONFIG/README\fP.  Consider
209 sychronizing from this file on a daily basis by using
210 .IR cron (8).
211 .SH OPTIONS
212 The options to
213 .IR actsync (8)
214 are as follows:
215 .PP
216 .TP
217 .B \-A
218 .IR actsync (8)
219 tries to authenticate before issuing LIST command.
220 .TP
221 .BI \-b " hostid"
222 This flag causes
223 .IR actsync (8)
224 to ignore newsgroups with ``bork.bork.bork'' style names.
225 That is, newsgroups whose last 3 components are identical.
226 For example, the following newsgroups have bork style names:
227 .sp 1
228 .in +0.5i
229 .nf
230 alt.helms.dork.dork.dork
231 alt.auto.accident.sue.sue.sue
232 alt.election.vote.vote.vote
233 .fi
234 .in -0.5i
235 .sp 1
236 The value
237 .I hostid
238 determines on which hosts this action is performed:
239 .sp 1
240 .in +0.5i
241 .nf
242 0       neither host
243 1       local default server
244 2       remove server
245 12      both servers
246 21      both servers
247 .fi
248 .in -0.5i
249 .sp 1
250 The default is
251 .BR "\-b 0" ;
252 no newsgroups are ignored because of bork-style names.
253 .TP
254 .BI \-d " hostid"
255 This flag causes
256 .IR actsync (8)
257 to ignore newsgroups that have all numeric path components.
258 The
259 .B hostid
260 value is interpreted the same as in
261 .BR \-b .
262 For example, the following newsgroups have numeric path components:
263 .sp
264 .in +0.5i
265 .nf
266 alt.prime.chongo.23209
267 391581.times.2.to_the.216193.power.-1
268 99.bottles.of.treacle.on.the.wall
269 linfield.class.envio_bio.101.d
270 .fi
271 .in -0.5i
272 .sp 1
273 The newsgroups directory of a newsgroups with a all numeric component
274 could conflict with an article from another group if stored using the
275 ``tradspool'' storage method; see
276 .IR storage.conf (5).
277 For example, the directory for the first newsgroup listed above
278 is the same path as article number 23209 from the newsgroup:
279 .sp
280 .in +0.5i
281 .nf
282 alt.prime.chongo
283 .fi
284 .in -0.5i
285 .sp 1
286 The default is
287 .BR "\-d 0" ;
288 all numeric newsgroups from both hosts will be processed.
289 .TP
290 .BI \-g " max"
291 Ignore any newsgroup with more than
292 .B max
293 levels.  For example,
294 .BI \-g " 6"
295 would ignore:
296 .sp 1
297 .in +0.5i
298 .nf
299 alt.feinstien.votes.to.trash.freedom.of.speech
300 alt.senator.exon.enemy.of.the.internet
301 alt.crypto.export.laws.dumb.dumb.dumb
302 .fi
303 .in -0.5i
304 .sp 1
305 but would not ignore:
306 .sp 1
307 .in +0.5i
308 .nf
309 alt.feinstien.acts.like.a.republican
310 alt.exon.amendment
311 alt.crypto.export.laws
312 .fi
313 .in -0.5i
314 .sp 1
315 If
316 .B max
317 is 0, then the max level feature is disabled.
318 .sp 1
319 By default,
320 the max level feature is disabled.
321 .TP
322 .BI \-i " ignore_file"
323 The
324 .I ignore_file ,
325 usually
326 .I <pathetc in inn.conf>/actsync.ign ,
327 allows one to have a fine degree of control over which newsgroups are ignored.
328 It contains a set of rules that specifies
329 which newsgroups will be checked and which will be ignored.
330 .sp 1
331 By default, these rules apply to both hosts.
332 This can be modified by using the
333 .BI \-I " hostid"
334 flag.
335 .sp 1
336 By default, all newsgroups are checked.
337 If no
338 .I ignore_file
339 if specified, or if the ignore file contains no rule lines,
340 all newsgroups will be checked.
341 .sp 1
342 Blank lines and text after a
343 .B ``#''
344 are considered comments and are ignored.
345 .sp 1
346 Rule lines consist of tokens separated by whitespace.
347 Rule lines may be one of two forms:
348 .sp 1
349 .in +0.5i
350 .nf
351 \fBc    newsgroup       [type ...]\fP
352 \fBi    newsgroup       [type ...]\fP
353 .fi
354 .in -0.5i
355 .sp 1
356 If the rule begins with a
357 .B c
358 then the rule requests certain newsgroups to be checked.
359 If the rule begins with an
360 .B i
361 then the rule requests certain newsgroups to be ignored.
362 The
363 .B newsgroup
364 field may be a specific newsgroup, or a
365 .IR uwildmat (3)
366 pattern.
367 .sp 1
368 If one or more
369 .BR type s
370 are specified, then the rule applies to the newsgroup only if
371 is of the specified type.
372 Types refer to the 4th field of the
373 .I active
374 file; that is, a type may be one of:
375 .sp 1
376 .in +0.5i
377 .nf
378 \fBy\fP
379 \fBn\fP
380 \fBm\fP
381 \fBj\fP
382 \fBx\fP
383 \fB=group.name\fP
384 .fi
385 .in -0.5i
386 .sp 1
387 Unlike active files, the
388 .B group.name
389 in an alias type may be a newsgroup name or a
390 .IR uwildmat (3)
391 pattern.
392 Also,
393 .B ``=''
394 is equivalent to
395 .BR ``=*'' .
396 .sp 1
397 On each rule line, no pattern type may not be repeated.
398 For example, one may not have more than one type that begins with
399 .BR ``='' ,
400 per line.
401 However, one may achieve an effect equivalent to using multiple
402 .B ``=''
403 types by using multiple rule lines affecting the same newsgroup.
404 .sp 1
405 By default, all newsgroups are candidates to be checked.
406 If an ignore file is used, each newsgroup in turn is checked
407 against the ignore file.
408 If multiple lines match a given newsgroup, the last line
409 in the ignore file is used.
410 .sp 1
411 For example, consider the following ignore file lines:
412 .sp 1
413 .in +0.5i
414 .nf
415 i *.general
416 c *.general m
417 i nsa.general
418 .fi
419 .in -0.5i
420 .sp 1
421 The newsgroups
422 .B ba.general
423 and
424 .B mod.general
425 would be synchronized if moderated and ignored if not moderated.
426 The newsgroup
427 .B nsa.general
428 would be ignored regardless of moderation status.
429 All newsgroups not matching
430 .B *.general
431 would be synchronized by default.
432 .TP
433 .BI \-I " hostid"
434 This flag restricts which hosts are affected by the ignore file.
435 The
436 .B hostid
437 value is interpreted the same as in
438 .BR \-b
439 described above.
440 .sp 1
441 This flag may be useful in conjunction with the
442 .B \-m
443 merge flag.
444 For example:
445 .sp 1
446 .in +0.5i
447 actsync \-i actsync.ign \-I 2 \-m
448 .I host1
449 .I host2
450 .in -0.5i
451 .sp 1
452 will keep all newsgroups currently on
453 .I host1 .
454 It will also will only compare
455 .I host1
456 groups with non-ignored newsgroups from
457 .I host2 .
458 .sp 1
459 The default is
460 .BR "\-I 12" ,
461 newsgroups from both hosts to be ignored per the
462 .I \-i " actsync.ign"
463 file.
464 .TP
465 .B \-k
466 By default, any newsgroup on
467 .I host1
468 that is in error will be considered for removal.
469 This causes
470 .IR actsync (8)
471 simply ignore such newsgroups.
472 This flag, used in combination with
473 .I \-m ,
474 will prevent any newsgroup from being scheduled for removal.
475 .TP
476 .BR \-l " hostid"
477 This flag causes ``problem newsgroups'' of type
478 .B ``=''
479 from
480 .B host1
481 or
482 .B host2
483 to be considered as errors.
484 The
485 .B hostid
486 value is interpreted the same as in
487 .BR \-b .
488 Newsgroups of type
489 .B ``=''
490 are newsgroups active entries that have 4th field
491 that begins with
492 .BR ``='' ,
493 i.e. newsgroups that are equivalent to other newsgroups.  A ``problem''
494 newsgroup is one which is:
495 .sp 1
496 .in +0.5i
497 .nf
498 *  equivalent to itself
499 *  in an equivalence chain that loops around
500    to itself
501 *  in an equivalence chain longer than 16 groups
502 *  equivalent to a non-existant newsgroup
503 *  equivalent to a newsgroup that has an error
504    of some kind
505 .fi
506 .in -0.5i
507 .sp 1
508 However, a newsgroup that is equivalent to an ignored newsgroup is
509 not a problem.
510 .sp 1
511 By default, problem newsgroups from both hosts are
512 marked as errors.
513 .TP
514 .B \-m
515 Merge newsgroups instead of sync.
516 By default, if a newsgroup exists on
517 .B host1
518 but not
519 .BR host2 ,
520 it will be scheduled to be removed.
521 This flag disables this process, permitting newsgroups unique to
522 .B host1
523 to be kept.
524 .TP
525 .B \-n " name"
526 The
527 .IR ctlinnd (8)
528 command is used to create newsgroups as necessary.
529 By default, the creator name used is
530 .BR "actsync" .
531 This flag changes the creator name to
532 .BR "name" .
533 .TP
534 .B \-o " fmt"
535 Determine the output / action format of this utility.
536 The
537 .B "fmt"
538 may one of:
539 .sp 1
540 .in +0.5i
541 .nf
542 \fBa\fP output in \fIactive\fP\fR(5)\fP\fR format\fP
543 \fBa1\fP        output in \fIactive\fP\fR(5)\fP\fR format,\fP
544         and output host1 non-error ignored groups
545 \fBak\fP        output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP
546         hi & low (2nd & 3rd active fields) values
547         for any newsgroup being created
548 \fBaK\fP        output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP
549         hi & low (2nd & 3rd active fields) values
550         for all newsgroups found in host2
551 \fBa1k\fP       output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP
552         hi & low (2nd & 3rd active fields) values
553         for any newsgroup being created,
554         and output host1 non-error ignored groups
555 \fBa1K\fP       output in \fIactive\fP\fR(5)\fP\fR format, but use host2\fP
556         hi & low (2nd & 3rd active fields) values
557         for all newsgroups found in host2,
558         and output host1 non-error ignored groups
559 \fBak1\fP       same as \fBa1k\fP
560 \fBaK1\fP       same as \fBa1K\fP
561 \fBc\fP output in \fIctlinnd\fP\fR(8)\fP\fR format\fP
562 \fBx\fP no output, directly exec \fIctlinnd\fP\fR(8)\fP\fR commands\fP
563 \fBxi\fP        no output, directly exec \fIctlinnd\fP\fR(8)\fP\fR commands,\fP
564         in an interactive mode
565 .fi
566 .in -0.5i
567 .sp 1
568 The \fBa\fP, \fBa1\fP, \fBak\fP, \fBaK\fP, \fBa1k\fP,
569 \fBa1K\fP, \fBak1\fP and \fBaK1\fP style formats allow one to form
570 a new active file instead of producing
571 .IR ctlinnd (8)
572 commands.
573 They use hi & low values of
574 .B 0000000000
575 and
576 .B 0000000001
577 respectively for newsgroups that are created.
578 The \fBak\fP and \fBaK\fP variants change the the hi & low (2nd & 3rd
579 active fields).
580 In the case of \fBak\fP, newsgroups created take their hi & low values from
581 .BR host2 .
582 In the case of \fBaK\fP, all newsgroups found on host2 take their
583 hi & low values from
584 .BR host2 .
585 .sp 1
586 The \fBc\fP format produces
587 .IR ctlinnd (8)
588 commands.
589 No actions are taken because
590 .IR actsync (8)
591 simply prints
592 .IR ctlinnd (8)
593 commands on standard output.
594 The sync (or merge) with
595 .B host2
596 may be accomplished by piping this output into
597 .IR sh (1).
598 A paranoid person might prefer to use \fBx\fP or \fBxi\fP
599 in case a newsgroup name or type contains bogus characters
600 that might be interpreted by
601 .IR sh (1).
602 Even so, this output format is useful to let you see how
603 .B host1
604 will be affected by the sync (or merge) with
605 .BR host2 .
606 .sp 1
607 The sync (or merge) may be accomplished directly
608 by use of the \fBx\fP format.
609 With this format,
610 .IR actsync (8)
611 uses the
612 .IR execl (2)
613 system call to directly execute
614 .IR ctlinnd (8)
615 commands.
616 Because of the exec, there is no risk
617 of bogus newsgroups containing bogus characters causing
618 a shell to do bogus (or dangerous) things.
619 The output of such exec calls may be seen if the verbosity level
620 is at least
621 .BR 2 .
622 .sp 1
623 The
624 .IR actsync (8)
625 utility will pause for
626 .B 4
627 seconds before each command is executed if
628 .BI \-o " x"
629 is selected.
630 See the
631 .BR \-z " sec"
632 flag below for discussion of this delay and how to customize it.
633 .sp 1
634 The \fBxi\fP format interactively prompts on standard output
635 and reads directives on standard input.
636 One may pick and choose changes using this format.
637 .sp 1
638 Care should be taken when producing
639 \fIactive\fP\fR(5)\fP\fR formatted output\fP.
640 One should check to be sure that
641 .IR actsync (8)
642 exited with a zero status prior to using such output.
643 Also one should realize that such output will not
644 contain lines ignored due to
645 .BI \-i " ignore_file"
646 even if
647 .BI \-p " 100"
648 is used.
649 .sp 1
650 By default,
651 .BI \-o " c"
652 is assumed.
653 .TP
654 .BI \-p " min_%_unchg"
655 By default, the
656 .IR actsync (8)
657 utility has safeguards against performing massive changes.
658 If fewer than
659 .B min_%_unchg
660 percent of the non-ignored lines from
661 .B host1
662 remain unchanged, no actions (output, execution, etc.)
663 are performed and
664 .IR actsync (8)
665 exits with a non-zero exit status.
666 The
667 .B min_%_unchg
668 may be a floating point value such as
669 .BR 66.667 .
670 .sp 1
671 A change is considered a
672 .B host1
673 line that was removed, added, changed, or found to be in error.
674 Changing the 2nd or 3rd active fields via
675 .BI \-o "ak"
676 or
677 .BI \-o " aK"
678 are not considered changes by
679 .BR \-p .
680 .sp 1
681 To force
682 .IR actsync (8)
683 to accept any amount of change, use the
684 .BI \-p " 0"
685 option.
686 To force
687 .IR actsync (8)
688 to reject any changes, use the
689 .BI \-p " 100"
690 option.
691 .sp 1
692 Care should be taken when producing
693 \fIactive\fP\fR(5)\fP\fR-formatted output\fP;
694 be sure to check that
695 .IR actsync (8)
696 exited with a zero status prior to using such output.
697 Also one should realize that such output will not
698 contain lines ignored by the
699 .BI \-i " ignore_file"
700 process even if
701 .BI \-p " 100"
702 is used.
703 .sp 1
704 By default, 96% of the lines not ignored in host1 must
705 be unchanged.
706 That is, by default,
707 .BI \-p " 96"
708 is assumed.
709 .TP
710 .BI \-q " hostid"
711 By default, all newsgroup errors are reported on standard error.
712 This flag quiets errors from
713 .B host1
714 or
715 .BR host2 .
716 The
717 .B hostid
718 value is interpreted the same as in
719 .BR \-b .
720 .TP
721 .BR \-s " size"
722 If
723 .BR size\ >\ 0,
724 then ignore newsgroups with names longer than
725 .BR size ,
726 and ignore newsgroups equivalent (by following
727 .B ``=''
728 chains) to names longer than
729 .BR size .
730 Length checking is performed on both the local and remote hosts.
731 .sp 1
732 By default,
733 .B size
734 is 0 and thus no length checking is performed.
735 .TP
736 .BR \-t " hostid"
737 Ignore improper newsgroups consisting of only a top component
738 from
739 .B host1
740 or
741 .BR host2 .
742 The
743 .B hostid
744 value is interpreted the same as in
745 .BR \-b .
746 The following newsgroups are considered proper newsgroups
747 despite top only names and therefore are exempt from this flag:
748 .sp 1
749 .in +0.5i
750 .nf
751 control
752 general
753 junk
754 test
755 to
756 .fi
757 .in -0.5i
758 .sp 1
759 For example, the following newsgroup names are improper because they
760 only contain a top level component:
761 .sp 1
762 .in +0.5i
763 .nf
764 dole_for_pres
765 dos
766 microsoft
767 windows95
768 .fi
769 .in -0.5i
770 .sp 1
771 The default is
772 .BR "\-t 2" ,
773 that is, all improper top-level-only newsgroups from the remote
774 are ignored.
775 .TP
776 .B \-T
777 This flag causes
778 .B host2
779 newsgroups from new hierarchies to be ignored.
780 Normally a newsgroup which only exists on
781 .B host2 ,
782 for example
783 .B chongo.was.here ,
784 will be created for
785 .BR host1 .
786 However, if this flag is given and
787 .B host1
788 does not have any other newsgroups in the same hierarchy,
789 e.g. ``\fBchongo.*\fP'', then the newsgroup in question
790 will be ignored and will not be created on
791 .BR host1 .
792 .TP
793 .BI \-v " verbosity"
794 By default,
795 .IR actsync (8)
796 is not verbose.
797 This flag controls the verbosity level as follows:
798 .sp 1
799 .in +0.5i
800 .nf
801 \fB0\fP no debug or status reports (default)
802 \fB1\fP print summary,
803         but only if work was needed or done
804 \fB2\fP print actions, exec output, and summary,
805         but only if work was needed or done
806 \fB3\fP print actions, exec output, and summary
807 \fB4\fP full debug output
808 .fi
809 .TP
810 .BI \-z " sec"
811 If
812 .BI \-o " x"
813 is selected,
814 .IR actsync (8)
815 will pause for
816 .B sec
817 seconds before each command is executed.
818 This helps prevent
819 .IR innd (8)
820 from being busied-out if a large number of
821 .IR ctlinnd (8)
822 commands are needed.
823 One can entirely disable this sleeping by using
824 .BI \-z " 0".
825 .sp 1
826 By default,
827 .IR actsync (8)
828 will pause for
829 .B 4
830 seconds before each command is executed if
831 .BI \-o " x"
832 is selected.
833 .in -0.5i
834 .SH EXAMPLES
835 Determine the difference (but don't change anything) between your
836 newsgroup set and uunet's set:
837 .PP
838 .in +0.5i
839 actsync news.uu.net
840 .in -0.5i
841 .PP
842 Same as above, with full debug and progress reports:
843 .PP
844 .in +0.5i
845 actsync \-v 4 news.uu.net
846 .in -0.5o
847 .PP
848 Force a site to have the same newsgroups some other site:
849 .PP
850 .in +0.5i
851 actsync \-o x master
852 .in -0.5i
853 .PP
854 This may be useful to sync a slave site to its master, or
855 to sync internal site to a gateway.
856 .PP
857 Compare your site with uunet, disregarding local groups and
858 certain local differences with uunet.
859 Produce a report if
860 any differences were encountered:
861 .PP
862 .in +0.5i
863 actsync \-v 2 \-i actsync.ign news.uu.net
864 .in -0.5i
865 .PP
866 where
867 .B actsync.ign
868 contains:
869 .PP
870 .in +0.5i
871 .nf
872 # Don't compare to.* groups as they will differ.
873 #
874 i       to.*
875
876 # These are our local groups that nobody else
877 # (should) carry.  So ignore them for the sake
878 # of the compare.
879 #
880 i       nsa.*
881
882 # These groups are local favorites, so keep them
883 # even if uunet does not carry them.
884 #
885 i       ca.dump.bob.dorman
886 i       ca.keep.bob.dorman
887 i       alt.tv.dinosaurs.barney.die.die.die
888 i       alt.tv.dinosaurs.barney.love.love.love
889 i       alt.sounds.*    =alt.binaries.sounds.*
890 .PP
891 .fi
892 .in -0.5i
893 .PP
894 To interactively sync against news.uu.net, using the same
895 ignore file:
896 .PP
897 .in +0.5i
898 actsync \-o xi \-v 2 \-i actsync.ign news.uu.net
899 .in -0.5i
900 .PP
901 Based on newsgroups that you decided to keep, one could
902 make changes to the
903 .B actsync.ign
904 file:
905 .PP
906 .in +0.5i
907 .nf
908 # Don't compare to.* groups as they will differ.
909 #
910 i       to.*
911
912 # These are our local groups that nobody else
913 # (should) carry.  So ignore them for the sake
914 # of the compare.
915 #
916 i       nsa.*
917
918 # These groups are local favorites, so keep them
919 # even if uunet does not carry them.
920 #
921 i       ca.dump.bob.dorman
922 i       alt.tv.dinosaurs.barney.die.die.die
923 i       alt.sounds.*    =alt.binaries.sounds.*
924
925 # Don't sync test groups, except for ones that are
926 # moderated or that are under the gnu hierarchy.
927 i       *.test
928 c       *.test  m       # check moderated test groups
929 c       gnu.*.test
930 c       gnu.test        # just in case it ever exists
931 .PP
932 .fi
933 .in -0.5i
934 .PP
935 Automatic processing may be setup by using the following
936 .B actsync.cfg
937 file:
938 .PP
939 .in +0.5i
940 .nf
941 # host to sync off of (host2)
942 host=news.uu.net
943
944 # location of the ignore file
945 ignore_file=<pathetc in inn.conf>/actsync.ign
946
947 # where news articles are kept
948 spool=<patharticles in inn.conf>
949
950 # actsync(8) flags
951 #
952 # Automatic execs, report if something was done,
953 #       otherwise don't say anything, don't report
954 #       uunet active file problems, just ignore
955 #       the affected entries.
956 flags=\-o x \-v 2 \-q 2
957 .fi
958 .in -0.5i
959 .PP
960 and then by running
961 .IR actsyncd (8)
962 with the path to the config
963 file:
964 .PP
965 .in +0.5i
966 actsyncd <pathetc in inn.conf>/actsync.cfg
967 .in -0.5i
968 .PP
969 One may produce a trial
970 .IR actsyncd (8)
971 run without changing anything
972 on the server by supplying the \fBdebug_level\fP arg:
973 .sp 1
974 .in +0.5i
975 actsyncd <pathetc in inn.conf>/actsync.cfg 2
976 .in -0.5i
977 .PP
978 The \fBdebug_level\fP causes
979 .IR actsyncd (8)
980 to run
981 .IR actsync (8)
982 with an \fB\-v debug_level\fP (overriding any \fB\-v\fP
983 flag on the \fBflags\fP line),
984 not make any changes to the
985 .I active
986 file, write a new active file to \fIstandard output\fP,
987 and write debug messages to \fIstandard error\fP.
988 .PP
989 If the \fBdebug_outfmt\fP arg is also given to
990 .IR actsyncd (8)
991 then the data written to \fIstandard output\fP will
992 be in \fB\-o debug_outfmt\fP instead of in \fB\-o a1\fP format.
993 The /bin/sh command
994 .sp 1
995 .in +0.5i
996 .nf
997 actsyncd <pathetc in inn.conf>/actsync.cfg 4 \\
998         >cmd.log 2>dbg.log
999 .fi
1000 .in -0.5i
1001 .PP
1002 will operate in debug mode,
1003 not change the
1004 .I active
1005 file, write
1006 .IR ctlinnd (8)
1007 style commands to \fBcmd.log\fP, and
1008 write debug statements to \fBdbg.log\fP.
1009 .PP
1010 To check only the major hierarchies against news.uu,net, use the following
1011 .B actsync.ign
1012 file:
1013 .PP
1014 .in +0.5i
1015 .nf
1016 # by default, ignore everything
1017 i *
1018
1019 # check the major groups
1020 c       comp.*
1021 c       gnu.*
1022 c       sci.*
1023 c       alt.*
1024 c       misc.*
1025 c       news.*
1026 c       rec.*
1027 c       soc.*
1028 c       talk.*
1029 .fi
1030 .in -0.5i
1031 .PP
1032 and the command:
1033 .PP
1034 .in +0.5i
1035 actsync \-i actsync.ign news.uu.net
1036 .in -0.5i
1037 .PP
1038 To determine the differences between your old active and
1039 your current default server:
1040 .PP
1041 .in +0.5i
1042 actsync <pathetc in inn.conf>/active.old \-
1043 .in -0.5i
1044 .PP
1045 To report but not fix any newsgroup problems with the current active file:
1046 .PP
1047 .in +0.5i
1048 actsync \- \-
1049 .in -0.5i
1050 .PP
1051 To detect any newsgroup errors on your local server, and
1052 to remove any
1053 .B *.bork.bork.bork
1054 style silly newsgroup names:
1055 .PP
1056 .in +0.5i
1057 actsync \-b 2 \- \-
1058 .in -0.5i
1059 .PP
1060 The active file produced by:
1061 .PP
1062 .in +0.5i
1063 actsync ...flags... \-o x erehwon.honey.edu
1064 .in -0.5i
1065 .PP
1066 or by:
1067 .PP
1068 .in +0.5i
1069 actsync ...flags... \-o c erehwon.honey.edu | sh
1070 .in -0.5i
1071 .PP
1072 is effectively the same as the active file produced by:
1073 .PP
1074 .nf
1075 .in +0.5i
1076 ctlinnd pause 'running actsync'
1077 rm -f active.new
1078 actsync ...flags... \-o a1 erehwon.honey.edu > active.new
1079 rm -f active.old
1080 ln active active.old
1081 mv active.new active
1082 ctlinnd reload active 'running actsync'
1083 ctlinnd go 'running actsync'
1084 .in -0.5i
1085 .fi
1086 .PP
1087 It should be noted that the final method above, pausing the server
1088 and simply replacing the
1089 .I active
1090 file, is faster.
1091 .PP
1092 .SH CAUTION
1093 Careless use of this tool may result in the unintended
1094 addition, change, or removal of newsgroups.
1095 You should avoid using the \fRx\fP output format until
1096 you are sure it will do what you want.
1097 .SH BUGS
1098 If a newsgroup appears multiple times,
1099 .IR actsync (8)
1100 will treat all copies as errors.
1101 However, if the group is marked for removal, only
1102 one rmgroup will be issued.
1103 .PP
1104 The timeout for
1105 .IR ctlinnd (8)
1106 commands is fixed at 30 seconds when
1107 running in ``\fRx\fP'' or ``\fRxi\fP'' output format.
1108 Perhaps the timeout value should be controlled via a command line option?
1109 .SH "SEE ALSO"
1110 .IR active (5),
1111 .br
1112 .IR simpleftp (1),
1113 .br
1114 .IR mod-active (8),
1115 .br
1116 .IR ctlinnd (8),
1117 .br
1118 .IR getlist (8),
1119 .br
1120 .IR inn.conf (5).
1121 .SH HISTORY
1122 Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
1123 Updated to support ftp fetching by David Lawrence <tale@isc.org>.