1 .\" By: Landon Curt Noll chongo@toad.com (chongo was here /\../\)
3 .\" Copyright (c) Landon Curt Noll, 1993.
4 .\" All rights reserved.
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.
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
14 actsync, actsyncd \- synchronize newsgroups
17 [\fB\-A\fP] [\fB\-b\fP\fI hostid\fP] [\fB\-d\fP\fI hostid\fP] [\fB\-g\fP\fI max\fP]
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]
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]
23 [\fB\-s\fP\fI size\fP] [\fB\-t\fP\fI hostid\fP] [\fB\-T\fP] [\fB\-v\fP\fI verbosity\fP]
25 [\fB\-z\fP\fI sec\fP] [\fIhost1\fP] \fIhost2\fP
28 [\fB\-x\fP] \fIactsync.cfg\fP [\fIdebug_level\fP [\fIdebug_outfmt\fP] ]
31 permits one to synchronize, compare, or merge two
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.
41 There are several reasons to run
46 Among the reasons are:
49 A control message to add, change or remove a newsgroup
50 may fail to reach your site.
54 may be out of date or incomplete.
56 News articles for a new newsgroup can arrive ahead (sometimes days ahead)
57 of the control message.
59 Control messages may be forged, thus bypassing the restrictions
65 file may have been trashed.
77 then it is assumed to be a name of a file containing information in the
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.
92 are called hosts, even though they may be file names.
94 If a host argument does not begin with
99 hostname or Internet address.
102 will attempt to use the
104 protocol to obtain a copy of the the specified system's active file.
105 If the host argument contains a
107 the right side will be considerd the port to connect to on the remote system.
108 If no port number is specified,
110 will connect to port 119.
112 Regardless how the active file information is obtained,
117 If only one host is specified, it is assumed to be
121 is not specified, it assumed to be the default local
122 NNTP server as specified by the
124 environment variable, or by the
129 The newsgroup synchronization, by default, involves all newsgroups
131 One may also synchronize a subset of newsgroups by directing
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.
142 daemon provides a convenient interface to configure and run
144 If a host is not initially reachable,
145 the daemon will retry up to 9 additional times, waiting 6 minutes before
147 This daemon runs in the foreground, sending output to standard output
150 If the \fB\-x\fP flag is given to
154 will be used instead of a
156 to load the newly modified active file.
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:
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
173 The \fBhost\fP, \fBignore_file\fP, and \fBflags\fP lines are mandatory.
175 The keyword must start at the beginning of the line, and there
176 may be no whitespace before the
179 Blank lines are ignored.
180 Comment lines start with
183 Any other lines may produce undefined results.
185 The \fBhost\fP config file line refers to the \fIhost2\fP parameter to
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
196 The \fBflags\fP config file line contains any flags that you wish to pass to
199 Note that the \fB\-i ignore_file\fP option
200 and the \fB-o format\fP option
202 in the \fBflags=\fP line because they are automatically taken care of by
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
219 tries to authenticate before issuing LIST command.
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:
230 alt.helms.dork.dork.dork
231 alt.auto.accident.sue.sue.sue
232 alt.election.vote.vote.vote
238 determines on which hosts this action is performed:
243 1 local default server
252 no newsgroups are ignored because of bork-style names.
257 to ignore newsgroups that have all numeric path components.
260 value is interpreted the same as in
262 For example, the following newsgroups have numeric path components:
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
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:
288 all numeric newsgroups from both hosts will be processed.
291 Ignore any newsgroup with more than
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
305 but would not ignore:
309 alt.feinstien.acts.like.a.republican
311 alt.crypto.export.laws
317 is 0, then the max level feature is disabled.
320 the max level feature is disabled.
322 .BI \-i " ignore_file"
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.
331 By default, these rules apply to both hosts.
332 This can be modified by using the
336 By default, all newsgroups are checked.
339 if specified, or if the ignore file contains no rule lines,
340 all newsgroups will be checked.
342 Blank lines and text after a
344 are considered comments and are ignored.
346 Rule lines consist of tokens separated by whitespace.
347 Rule lines may be one of two forms:
351 \fBc newsgroup [type ...]\fP
352 \fBi newsgroup [type ...]\fP
356 If the rule begins with a
358 then the rule requests certain newsgroups to be checked.
359 If the rule begins with an
361 then the rule requests certain newsgroups to be ignored.
364 field may be a specific newsgroup, or a
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
374 file; that is, a type may be one of:
387 Unlike active files, the
389 in an alias type may be a newsgroup name or a
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
401 However, one may achieve an effect equivalent to using multiple
403 types by using multiple rule lines affecting the same newsgroup.
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.
411 For example, consider the following ignore file lines:
425 would be synchronized if moderated and ignored if not moderated.
428 would be ignored regardless of moderation status.
429 All newsgroups not matching
431 would be synchronized by default.
434 This flag restricts which hosts are affected by the ignore file.
437 value is interpreted the same as in
441 This flag may be useful in conjunction with the
447 actsync \-i actsync.ign \-I 2 \-m
452 will keep all newsgroups currently on
454 It will also will only compare
456 groups with non-ignored newsgroups from
461 newsgroups from both hosts to be ignored per the
462 .I \-i " actsync.ign"
466 By default, any newsgroup on
468 that is in error will be considered for removal.
471 simply ignore such newsgroups.
472 This flag, used in combination with
474 will prevent any newsgroup from being scheduled for removal.
477 This flag causes ``problem newsgroups'' of type
483 to be considered as errors.
486 value is interpreted the same as in
490 are newsgroups active entries that have 4th field
493 i.e. newsgroups that are equivalent to other newsgroups. A ``problem''
494 newsgroup is one which is:
498 * equivalent to itself
499 * in an equivalence chain that loops around
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
508 However, a newsgroup that is equivalent to an ignored newsgroup is
511 By default, problem newsgroups from both hosts are
515 Merge newsgroups instead of sync.
516 By default, if a newsgroup exists on
520 it will be scheduled to be removed.
521 This flag disables this process, permitting newsgroups unique to
528 command is used to create newsgroups as necessary.
529 By default, the creator name used is
531 This flag changes the creator name to
535 Determine the output / action format of this utility.
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
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
573 They use hi & low values of
577 respectively for newsgroups that are created.
578 The \fBak\fP and \fBaK\fP variants change the the hi & low (2nd & 3rd
580 In the case of \fBak\fP, newsgroups created take their hi & low values from
582 In the case of \fBaK\fP, all newsgroups found on host2 take their
586 The \fBc\fP format produces
589 No actions are taken because
593 commands on standard output.
594 The sync (or merge) with
596 may be accomplished by piping this output into
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
602 Even so, this output format is useful to let you see how
604 will be affected by the sync (or merge) with
607 The sync (or merge) may be accomplished directly
608 by use of the \fBx\fP format.
613 system call to directly execute
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
625 utility will pause for
627 seconds before each command is executed if
632 flag below for discussion of this delay and how to customize it.
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.
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
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"
654 .BI \-p " min_%_unchg"
657 utility has safeguards against performing massive changes.
660 percent of the non-ignored lines from
662 remain unchanged, no actions (output, execution, etc.)
665 exits with a non-zero exit status.
668 may be a floating point value such as
671 A change is considered a
673 line that was removed, added, changed, or found to be in error.
674 Changing the 2nd or 3rd active fields via
678 are not considered changes by
683 to accept any amount of change, use the
688 to reject any changes, use the
692 Care should be taken when producing
693 \fIactive\fP\fR(5)\fP\fR-formatted output\fP;
694 be sure to check that
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"
704 By default, 96% of the lines not ignored in host1 must
711 By default, all newsgroup errors are reported on standard error.
712 This flag quiets errors from
718 value is interpreted the same as in
724 then ignore newsgroups with names longer than
726 and ignore newsgroups equivalent (by following
728 chains) to names longer than
730 Length checking is performed on both the local and remote hosts.
734 is 0 and thus no length checking is performed.
737 Ignore improper newsgroups consisting of only a top component
744 value is interpreted the same as in
746 The following newsgroups are considered proper newsgroups
747 despite top only names and therefore are exempt from this flag:
759 For example, the following newsgroup names are improper because they
760 only contain a top level component:
773 that is, all improper top-level-only newsgroups from the remote
779 newsgroups from new hierarchies to be ignored.
780 Normally a newsgroup which only exists on
786 However, if this flag is given and
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
797 This flag controls the verbosity level as follows:
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
817 seconds before each command is executed.
820 from being busied-out if a large number of
823 One can entirely disable this sleeping by using
830 seconds before each command is executed if
835 Determine the difference (but don't change anything) between your
836 newsgroup set and uunet's set:
842 Same as above, with full debug and progress reports:
845 actsync \-v 4 news.uu.net
848 Force a site to have the same newsgroups some other site:
854 This may be useful to sync a slave site to its master, or
855 to sync internal site to a gateway.
857 Compare your site with uunet, disregarding local groups and
858 certain local differences with uunet.
860 any differences were encountered:
863 actsync \-v 2 \-i actsync.ign news.uu.net
872 # Don't compare to.* groups as they will differ.
876 # These are our local groups that nobody else
877 # (should) carry. So ignore them for the sake
882 # These groups are local favorites, so keep them
883 # even if uunet does not carry them.
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.*
894 To interactively sync against news.uu.net, using the same
898 actsync \-o xi \-v 2 \-i actsync.ign news.uu.net
901 Based on newsgroups that you decided to keep, one could
908 # Don't compare to.* groups as they will differ.
912 # These are our local groups that nobody else
913 # (should) carry. So ignore them for the sake
918 # These groups are local favorites, so keep them
919 # even if uunet does not carry them.
922 i alt.tv.dinosaurs.barney.die.die.die
923 i alt.sounds.* =alt.binaries.sounds.*
925 # Don't sync test groups, except for ones that are
926 # moderated or that are under the gnu hierarchy.
928 c *.test m # check moderated test groups
930 c gnu.test # just in case it ever exists
935 Automatic processing may be setup by using the following
941 # host to sync off of (host2)
944 # location of the ignore file
945 ignore_file=<pathetc in inn.conf>/actsync.ign
947 # where news articles are kept
948 spool=<patharticles in inn.conf>
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
962 with the path to the config
966 actsyncd <pathetc in inn.conf>/actsync.cfg
969 One may produce a trial
971 run without changing anything
972 on the server by supplying the \fBdebug_level\fP arg:
975 actsyncd <pathetc in inn.conf>/actsync.cfg 2
978 The \fBdebug_level\fP causes
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
986 file, write a new active file to \fIstandard output\fP,
987 and write debug messages to \fIstandard error\fP.
989 If the \fBdebug_outfmt\fP arg is also given to
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.
997 actsyncd <pathetc in inn.conf>/actsync.cfg 4 \\
1002 will operate in debug mode,
1007 style commands to \fBcmd.log\fP, and
1008 write debug statements to \fBdbg.log\fP.
1010 To check only the major hierarchies against news.uu,net, use the following
1016 # by default, ignore everything
1019 # check the major groups
1035 actsync \-i actsync.ign news.uu.net
1038 To determine the differences between your old active and
1039 your current default server:
1042 actsync <pathetc in inn.conf>/active.old \-
1045 To report but not fix any newsgroup problems with the current active file:
1051 To detect any newsgroup errors on your local server, and
1054 style silly newsgroup names:
1060 The active file produced by:
1063 actsync ...flags... \-o x erehwon.honey.edu
1069 actsync ...flags... \-o c erehwon.honey.edu | sh
1072 is effectively the same as the active file produced by:
1076 ctlinnd pause 'running actsync'
1078 actsync ...flags... \-o a1 erehwon.honey.edu > active.new
1080 ln active active.old
1081 mv active.new active
1082 ctlinnd reload active 'running actsync'
1083 ctlinnd go 'running actsync'
1087 It should be noted that the final method above, pausing the server
1088 and simply replacing the
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.
1098 If a newsgroup appears multiple times,
1100 will treat all copies as errors.
1101 However, if the group is marked for removal, only
1102 one rmgroup will be issued.
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?
1122 Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
1123 Updated to support ftp fetching by David Lawrence <tale@isc.org>.
~ian / innduct.git / blob