1ACTSYNC(8) InterNetNews Documentation ACTSYNC(8)
2
6 actsync, actsyncd - Synchronize newsgroups
7
9 actsync [-AkmT] [-b hostid] [-d hostid] [-g max] [-i ignore-file] [-I
10 hostid] [-l hostid] [-n name] [-o format] [-p min-unchanged] [-q
11 hostid] [-s size] [-t hostid] [-v verbosity] [-w seconds] [-z seconds]
12 [host] host
13 actsyncd config [debug-level [debug-format]]
15
17 These programs permit keeping the list of newsgroups your news server
18 carry synchronized with an external source.
19 For instance, you can decide to carry the same newsgroups as another
21 news server or as the ones listed in a file from an external FTP site,
22 and therefore synchronizing with the chosen source on a daily basis by
23 running actsyncd in a cron job.
24 If you only want a subset of newsgroups from that source, it can be
26 parameterized in the actsync.ign configuration file in the pathetc
27 directory.
28 INN comes with a default configuration for fetching the list of
30 newsgroups from "ftp.isc.org". You can read about the policies used
31 for maintaining that active file at
32 <https://ftp.isc.org/pub/usenet/CONFIG/README>. Just make sure
33 actsync.cfg (the configuration file) and actsync.ign (the
34 synchronization rules) suit your needs, and run:
35 actsyncd <pathetc>/actsync.cfg
37 You'll find more detailed examples of use below in this man page.
39
41 actsync permits one to synchronize, compare, or merge two active files.
42 With this utility one may add, change, or remove newsgroups on the
43 local news server to make it similar to the list of the newsgroups
44 found on another system or file. The synchronization need not be
45 exact. Local differences in newsgroup lists may be maintained and
46 preserved. Certain newsgroup errors may be detected and optionally
47 corrected.
48 There are several reasons to run actsync (or actsyncd) on a periodic
50 basis. Among the reasons are:
51 • A control message to add, change or remove a newsgroup may fail to
53 reach your site.
54 • Your control.ctl may be out of date or incomplete.
56 • News articles for a new newsgroup may arrive ahead (sometimes days
58 ahead) of the control message.
59 • Control messages may be forged, thus bypassing the restrictions found
61 in control.ctl unless you set up PGP authentication (and even then,
62 not all hierarchies use PGP authentication).
63 • Your active file may have been trashed.
65 If either host argument begins with "." or "/", it is assumed to be the
67 name of a file containing information in the active(5) format. The
68 getlist(1) utility may be used to obtain a copy of a remote system's
69 active file via its NNTP server, or an FTP client program can retrieve
70 such a file from an FTP archive (such as ftp.isc.org available in both
71 FTP and HTTPS <https://ftp.isc.org/pub/usenet/CONFIG/active>; see more
72 about this below). Newsgroup information from a file may be treated as
73 if it was obtained from a host. In this man page, the host arguments
74 on the command line are called hosts, even though they may be file
75 names.
76 If a host argument does not begin with "." or "/", it is assumed to be
78 a hostname or Internet address. In this case, actsync will attempt to
79 use the NNTP protocol to obtain a copy of the specified system's active
80 file. If the host argument contains ":", the right side will be
81 considered the port to connect to on the remote system. If no port
82 number is specified, actsync will connect to port 119.
83 Regardless how the active file information is obtained, the actions of
85 actsync remain the same.
86 The first host specified is taken to be the local host, the one where
88 any changes would be made. The second host specified is the remote
89 host that is being synchronized with. If only one host is specified,
90 it is assumed to be the remote host to synchronize with, and the local
91 host is assumed to be the default local NNTP server as specified by the
92 NNTPSERVER environment variable or by the server value found in
93 inn.conf.
94 If either host is specified as "-", the default server will be used for
96 that host, determined as described above.
97 The newsgroup synchronization, by default, involves all newsgroups
99 found on both hosts. One may also synchronize a subset of newsgroups
100 by directing actsync to ignore certain newsgroups from both systems.
101 Only newsgroups with valid names will be synchronized. To be valid, a
102 newsgroup name must consist only of alphanumeric characters, ".", "+",
103 "-", and "_". One may not have two "." characters in a row. The first
104 character must be alphanumeric, as must any character following ".".
105 The name may not end in a "." character.
106 The actsyncd daemon provides a convenient interface to configure and
108 run actsync. If a host is not initially reachable, the daemon will
109 retry up to 9 additional times, waiting 6 minutes before each retry.
110 This daemon runs in the foreground, sending output to standard output
111 and standard error. It then uses mod-active(8) to update the active
112 file if there are commands for ctlinnd in its output.
113 The configuration filename for the daemon is given as a command line
115 argument, usually actsync.cfg in pathetc. The config file can contain
116 the following options:
117 host=<host>
119 ftppath=<path-to-active>
120 ignore_file=<ignore-file>
121 flags=<actsync-options>
122 The "host=", "ignore_file=", and "flags=" lines are mandatory. Each
124 keyword must start at the beginning of the line, and there may be no
125 whitespace before the "=" character. Blank lines are ignored, as are
126 comment lines that start with "#". Any other lines may produce
127 undefined results.
128 The <host> setting refers to the second (remote) host parameter to
130 actsync. If <path-to-active> is provided, <host> is accessed as an FTP
131 server, retrieving the file named. If the filename ends in ".gz" or
132 ".Z", it will be automatically uncompressed after retrieval.
133 <ignore-file> names the ignore file used by actsync (the -i option).
134 <actsync-options> contains any other flags that you wish to pass to
135 actsync.
136 Note that one should not include -i or -o options in the "flags=" line;
138 they are automatically taken care of by actsyncd.
139 One may produce a trial actsyncd run without changing anything on the
141 server by supplying the debug-level argument:
142 actsyncd <pathetc>/actsync.cfg 2
144 The debug-level causes actsyncd to run actsync with a -v debug-level
146 flag (overriding any -v flag on the "flags=" line), not make any
147 changes to the active file, write a new active file to standard output,
148 and write debug messages to standard error. Note that using debug-
149 level is only supported when synchronizing with another news server,
150 not with FTP.
151 If the debug-format argument is also given to actsyncd, the data
153 written to standard output will be in -o debug-format instead of in "-o
154 a1" format.
155 INN comes with default values of "ftp.isc.org" for <host> and
157 "/pub/usenet/CONFIG/active.gz" for <path-to-active>. You can read
158 about the policies used for maintaining that active file at
159 <https://ftp.isc.org/pub/usenet/CONFIG/README>. Consider synchronizing
160 from this file on a daily basis by using a cron job.
161
163 actsync takes the following options.
164 In all of the following options, the hostid parameter takes one of the
166 following values:
167 0 neither server
169 1 local default server
170 2 remote server
171 12 both servers
172 21 both servers
173 In other words, 1 refers to the local host (the first host argument on
175 the actsync command line) and 2 refers to the remote host (the second
176 host argument, or the only one if only one is given).
177 -A actsync tries to authenticate using the username and password
179 information in passwd.nntp(5) before issuing the LIST command.
180 -b hostid
182 This flag causes actsync to ignore for synchronization purposes
183 newsgroups with "bork.bork.bork"-style names (newsgroups whose last
184 3 components are identical). For example, the following newsgroups
185 have bork-style names:
186 alt.helms.dork.dork.dork
188 alt.auto.accident.sue.sue.sue
189 alt.election.vote.vote.vote
190 The default is "-b 0"; no newsgroups are ignored because of bork-
192 style names.
193 -d hostid
195 This flag causes actsync to ignore newsgroups that have all numeric
196 path components. For example, the following newsgroups have
197 numeric path components:
198 alt.prime.chongo.23209
200 391581.times.2.to_the.216193.power.-1
201 99.bottles.of.treacle.on.the.wall
202 linfield.class.envio_bio.101.d
203 The newsgroups directory of a newsgroup with a all numeric
205 component could conflict with an article from another group if
206 stored using the tradspool storage method; see storage.conf(5).
207 For example, the directory for the first newsgroup listed above is
208 the same path as article number 23209 from the newsgroup:
209 alt.prime.chongo
211 The default is "-d 0"; all numeric newsgroups from both hosts will
213 be processed.
214 -g max
216 Ignore any newsgroup with more than max levels. For example, "-g
217 6" would ignore:
218 alt.feinstien.votes.to.trash.freedom.of.speech
220 alt.senator.exon.enemy.of.the.internet
221 alt.crypto.export.laws.dumb.dumb.dumb
222 but would not ignore:
224 alt.feinstien.acts.like.a.republican
226 alt.exon.amendment
227 alt.crypto.export.laws
228 If max is 0, then the max level feature is disabled.
230 By default, the max level feature is disabled.
232 -i ignore-file
234 The ignore-file, usually actsync.ign in pathetc, allows one to have
235 a fine degree of control over which newsgroups are ignored. It
236 contains a set of rules that specifies which newsgroups will be
237 checked and which will be ignored.
238 By default, these rules apply to both hosts. This can be modified
240 by using the -I flag.
241 Blank lines and text after a "#" are considered comments and are
243 ignored.
244 Rule lines consist of tokens separated by whitespace. Rule lines
246 may be one of two forms:
247 c <newsgroup> [<type> ...]
249 i <newsgroup> [<type> ...]
250 If the rule begins with a "c", the rule requests certain newsgroups
252 to be checked. If the rule begins with an "i", the rule requests
253 certain newsgroups to be ignored. The <newsgroup> field may be a
254 specific newsgroup, or a uwildmat pattern.
255 If one or more <type>s are specified, then the rule applies to the
257 newsgroup only if it is of the specified type. Types refer to the
258 4th field of the active file; that is, a type may be one of:
259 y
261 n
262 m
263 j
264 x
265 =group.name
266 Unlike active files, the "group.name" in an alias type may be a
268 newsgroup name or a uwildmat pattern. Also, "=" is equivalent to
269 "=*".
270 On each rule line, no pattern type may be repeated. For example,
272 one may not have more than one type that begins with "=", per line.
273 However, one may achieve an effect equivalent to using multiple "="
274 types by using multiple rule lines affecting the same newsgroup.
275 By default, all newsgroups are candidates to be checked. If no
277 ignore-file is specified, or if the ignore file contains no rule
278 lines, all newsgroups will be checked. If an ignore file is used,
279 each newsgroup in turn is checked against the ignore file. If
280 multiple lines match a given newsgroup, the last line in the ignore
281 file is used.
282 For example, consider the following ignore file lines:
284 i *.general
286 c *.general m
287 i nsa.general
288 The newsgroups ba.general and mod.general would be synchronized if
290 moderated and ignored if not moderated. The newsgroup nsa.general
291 would be ignored regardless of moderation status. All newsgroups
292 not matching *.general would be synchronized by default.
293 -I hostid
295 This flag restricts which hosts are affected by the ignore file.
296 This flag may be useful in conjunction with the -m flag. For
297 example:
298 actsync -i actsync.ign -I 2 -m host1 host2
300 will keep all newsgroups currently on host1. It will also only
302 compare host1 groups with non-ignored newsgroups from host2.
303 The default is "-I 12"; newsgroups from both hosts are ignored per
305 the file specified with -i.
306 -k By default, any newsgroup on the local host that has an invalid
308 name will be considered for removal. This causes actsync simply
309 ignore such newsgroups. This flag, used in combination with -m,
310 will prevent any newsgroup from being scheduled for removal.
311 -l hostid
313 This flag causes problem newsgroups of type "=" to be considered as
314 errors. Newsgroups of type "=" are newsgroups active entries that
315 have a fourth field that begins with "="; i.e., newsgroups that are
316 aliased to other newsgroups. A problem newsgroup is one for which
317 one of the following is true:
318 • Aliased to itself.
320 • In an alias chain that loops around to itself.
322 • In an alias chain longer than 16 groups.
324 • Aliased to a non-existent newsgroup.
326 • Aliased to a newsgroup that has an error of some kind.
328 However, a newsgroup that is equivalent to an ignored newsgroup is
330 not a problem.
331 The default is "-l 12": problem newsgroups from both hosts are
333 marked as errors.
334 -m Merge newsgroups instead of sync. By default, if a newsgroup
336 exists on the local host but not the remote, it will be scheduled
337 to be removed. This flag disables this process, permitting
338 newsgroups unique to the local host to be kept.
339 -n name
341 Depending on -o, the ctlinnd(8) command may be used to create
342 newsgroups as necessary. When this is done, the default creator
343 name used is "actsync". This flag changes the creator name to
344 name.
345 -o format
347 Determine the output or action format of this utility. format may
348 be one of:
349 a Output in active(5) format.
351 a1 Output in active(5) format and output non-error ignored groups
353 from the local host.
354 ak Output in active(5) format, but use the high and low (2nd and
356 3rd active fields) values from the remote host for any
357 newsgroup being created.
358 aK Output in active(5) format, but use the high and low (2nd and
360 3rd active fields) values from the remote host for all
361 newsgroups found on that host.
362 a1k Output in active(5) format, but use the high and low (2nd and
364 3rd active fields) values from the remote host for any
365 newsgroup being created and output non-error ignored groups
366 from the local host.
367 a1K Output in active(5) format, but use the high and low (2nd and
369 3rd active fields) values from the remote host for all
370 newsgroups found on that host and output non-error ignored
371 groups from the local host.
372 ak1 Same as "a1k".
374 aK1 Same as "a1K".
376 c Output as commands to ctlinnd.
378 x No output. Instead, directly run ctlinnd commands.
380 xi No output. Instead, directly run ctlinnd commands in an
382 interactive mode.
383 The "a", "a1", "ak", "aK", "a1k", "a1K", "ak1", and "aK1" style
385 formats allow one to format new active file instead of producing
386 ctlinnd commands. They use high and low values of 0000000000 and
387 0000000001 respectively for newsgroups that are created unless
388 otherwise specified. The "ak" and "aK" variants change the high
389 and low values (2nd and 3rd active fields). In the case of "ak",
390 newsgroups created take their high and low values from the remote
391 host. In the case of "aK", all newsgroups found on the remote host
392 take their high and low values from it.
393 The "c" format produces ctlinnd commands. No actions are taken
395 because actsync simply prints ctlinnd commands on standard output.
396 This output format is useful to let you see how the local host will
397 be affected by the sync (or merge) with the remote host.
398 The sync (or merge) may be accomplished directly by use of the "x"
400 or "xi" format. With this format, actsync uses the execl(2) system
401 call to directly execute ctlinnd commands. The output of such exec
402 calls may be seen if the verbosity level is at least 2.
403 The actsync utility will pause for 4 seconds before each command is
405 executed if "-o x" is selected. See the -z flag below for
406 discussion of this delay and how to customize it.
407 The "xi" format interactively prompts on standard output and reads
409 directives on standard input. One may pick and choose changes
410 using this format.
411 Care should be taken when producing active(5) formatted output.
413 One should check to be sure that actsync exited with a zero status
414 prior to using such output. Also one should realize that such
415 output will not contain lines ignored due to -i even if "-p 100" is
416 used.
417 By default, "-o c" is assumed.
419 -p min-unchanged
421 By default, the actsync utility has safeguards against performing
422 massive changes. If fewer than min-unchanged percent of the non-
423 ignored lines from the local host remain unchanged, no actions
424 (output, execution, etc.) are performed and actsync exits with a
425 non-zero exit status. The min-unchanged value may be a floating
426 point value such as 66.667.
427 A change is a local newsgroup line that was removed, added,
429 changed, or found to be in error. Changing the 2nd or 3rd active
430 fields via "-o ak" or "-o aK" are not considered changes by -p.
431 To force actsync to accept any amount of change, use the "-p 0"
433 option. To force actsync to reject any changes, use the "-p 100"
434 option.
435 Care should be taken when producing active(5) formatted output.
437 One should check to be sure that actsync exited with a zero status
438 prior to using such output. Also one should realize that such
439 output will not contain lines ignored due to -i even if "-p 100" is
440 used.
441 By default, 96% of the lines not ignored in the first host argument
443 on the actsync command line must be unchanged. That is, by
444 default, "-p 96" is assumed.
445 -q hostid
447 By default, all newsgroup errors are reported on standard error.
448 This flag quiets errors from the specified hostid.
449 -s size
451 If size is greater than 0, then ignore newsgroups with names longer
452 than size and ignore newsgroups aliased (by following "=" chains)
453 to names longer than size. Length checking is performed on both
454 the local and remote hosts.
455 By default, size is 0 and thus no length checking is performed.
457 -t hostid
459 Ignore improper newsgroups consisting of only a top component from
460 the specified hostid. The following newsgroups are considered
461 proper newsgroups despite top only names and therefore are exempt
462 from this flag:
463 control
465 general
466 junk
467 test
468 to
469 For example, the following newsgroup names are improper because
471 they only contain a top level component:
472 dole_for_pres
474 dos
475 microsoft
476 windows95
477 The default is "-t 2"; that is, all improper top-level-only
479 newsgroups from the remote host are ignored.
480 -T This flag causes newsgroups on the remote host in new hierarchies
482 to be ignored. Normally a newsgroup which only exists on the
483 remote host, chongo.was.here for example, is created on the local
484 host. However, if this flag is given and the local host does not
485 have any other newsgroups in the same hierarchy (chongo.* in this
486 case), the newsgroup in question will be ignored and will not be
487 created on the local host.
488 -v verbosity
490 By default, actsync is not verbose. This flag controls the
491 verbosity level as follows:
492 0 No debug or status reports (default).
494 1 Print summary, but only if work was needed or done.
496 2 Print actions, exec output, and summary, but only if work was
498 needed or done.
499 3 Print actions, exec output, and summary.
501 4 Full debug output.
503 -w seconds
505 If "-o x" or "-o xi" is selected, ctlinnd will wait seconds seconds
506 before timing out. The default value is "-w 30".
507 -z seconds
509 If "-o x" is selected, actsync will pause for seconds seconds
510 before each command is executed. This helps prevent innd from
511 being busied-out if a large number of ctlinnd commands are needed.
512 One can entirely disable this sleeping by using "-z 0".
513 By default, actsync will pause for 4 seconds before each command is
515 executed if "-o x" is selected.
516
518 Determine the difference (but don't change anything) between your
519 newsgroup set and the one of another news server:
520 actsync news.server.com
522 Same as above, with full debug and progress reports:
524 actsync -v 4 news.server.com
526 Force a site to have the same newsgroups as some other site:
528 actsync -o x master
530 This may be useful to sync a slave site to its master, or to sync
532 internal site to a gateway.
533 Compare your site with news.server.com, disregarding local groups and
535 certain local differences with it. Produce a report if any differences
536 were encountered:
537 actsync -v 2 -i actsync.ign news.server.com
539 where actsync.ign contains:
541 # Don't compare to.* groups as they will differ.
543 #
544 i to.*
545 # These are our local groups that nobody else
547 # (should) carry. So ignore them for the sake
548 # of the compare.
549 #
550 i nsa.*
551 # These groups are local favorites, so keep them
553 # even if news.server.com does not carry them.
554 #
555 i ca.dump.bob.dorman
556 i ca.keep.bob.dorman
557 i alt.tv.dinosaurs.barney.die.die.die
558 i alt.tv.dinosaurs.barney.love.love.love
559 i alt.sounds.* =alt.binaries.sounds.*
560 To interactively sync against news.server.com, using the same ignore
562 file:
563 actsync -o xi -v 2 -i actsync.ign news.server.com
565 Based on newsgroups that you decided to keep, one could make changes to
567 the actsync.ign file:
568 # Don't compare to.* groups as they will differ.
570 #
571 i to.*
572 # These are our local groups that nobody else
574 # (should) carry. So ignore them for the sake
575 # of the compare.
576 #
577 i nsa.*
578 # These groups are local favorites, so keep them
580 # even if news.server.com does not carry them.
581 #
582 i ca.dump.bob.dorman
583 i alt.tv.dinosaurs.barney.die.die.die
584 i alt.sounds.* =alt.binaries.sounds.*
585 # Don't sync test groups, except for ones that are
587 # moderated or that are under the gnu hierarchy.
588 #
589 i *.test
590 c *.test m # check moderated test groups
591 c gnu.*.test
592 c gnu.test # just in case it ever exists
593 Automatic processing may be set up by using the following actsync.cfg
595 file:
596 # Host to sync off of (host2).
598 host=news.server.com
599 # Location of the ignore file.
601 ignore_file=<pathetc in inn.conf>/actsync.ign
602 # Where news articles are kept.
604 spool=<patharticles in inn.conf>
605 # actsync(8) flags
607 #
608 # Automatic execs, report if something was done,
609 # otherwise don't say anything, don't report
610 # news.server.com active file problems, just ignore
611 # the affected entries.
612 flags=-o x -v 2 -q 2
613 and then by running actsyncd with the path to the config file:
615 actsyncd <pathetc>/actsync.cfg
617 The command
619 actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log
621 will operate in debug mode, not change the active file, write ctlinnd
623 style commands to cmd.log, and write debug statements to dbg.log.
624 (Note that using debug-level is only supported when synchronizing with
625 another news server, not with FTP.)
626 To check only the major hierarchies against news.server.com, use the
628 following actsync.ign file:
629 # By default, ignore everything.
631 #
632 i *
633 # Check the major groups.
635 #
636 c alt.*
637 c comp.*
638 c gnu.*
639 c humanities.*
640 c misc.*
641 c news.*
642 c rec.*
643 c sci.*
644 c soc.*
645 c talk.*
646 and the command:
648 actsync -i actsync.ign news.server.com
650 To determine the differences between your old active and your current
652 default server:
653 actsync <pathetc>/active.old -
655 To report but not fix any newsgroup problems with the current active
657 file:
658 actsync - -
660 To detect any newsgroup errors on your local server, and to remove any
662 *.bork.bork.bork-style silly newsgroup names:
663 actsync -b 2 - -
665 The active file produced by:
667 actsync <flags> -o x erehwon.honey.edu
669 is effectively the same as the active file produced by:
671 cd <pathdb>
673 ctlinnd pause 'running actsync'
674 rm -f active.new
675 actsync <flags> -o a1 erehwon.honey.edu > active.new
676 rm -f active.old
677 ln active active.old
678 mv active.new active
679 ctlinnd reload active 'running actsync'
680 ctlinnd go 'running actsync'
681 It should be noted that the final method above, pausing the server and
683 simply replacing the active file, may be faster if you are making lots
684 of changes.
685
687 pathbin/actsync
688 The C program itself used to synchronize, compare, or merge two
689 active files.
690 pathbin/actsyncd
692 The Shell daemon which provides a convenient interface to configure
693 and run actsync.
694 pathetc/actsync.cfg
696 The configuration file which specifies the settings to use.
697 pathetc/actsync.ign
699 The ignore file which contains a set of synchronization rules that
700 specifies which newsgroups will be checked and which will be
701 ignored.
702
704 Careless use of this tool may result in the unintended addition,
705 change, or removal of newsgroups. You should avoid using the "x"
706 output format until you are sure it will do what you want.
707
709 If a newsgroup appears multiple times, actsync will treat all copies as
710 errors. However, if the group is marked for removal, only one rmgroup
711 will be issued.
712
714 Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
715 Updated to support FTP fetching by David Lawrence <tale@isc.org>.
716 Converted to POD by Russ Allbery <eagle@eyrie.org>.
717 By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).
719 Copyright (c) Landon Curt Noll, 1993. All rights reserved.
721 Permission to use and modify is hereby granted so long as this notice
723 remains. Use at your own risk. No warranty is implied.
724
726 active(5), ctlinnd(8), getlist(1), inn.conf(5), libinn_uwildmat(3),
727 mod-active(8), passwd.nntp(5), simpleftp(1).
728INN 2.7.1 2023-03-07 ACTSYNC(8)