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 actsync permits one to synchronize, compare, or merge two active files.
18 With this utility one may add, change, or remove newsgroups on the
19 local news server to make it similar to the list of the newsgroups
20 found on another system or file. The synchronization need not be
21 exact. Local differences in newsgroup lists may be maintained and
22 preserved. Certain newsgroup errors may be detected and optionally
23 corrected.
24 There are several reasons to run actsync (or actsyncd) on a periodic
26 basis. Among the reasons are:
27 · A control message to add, change or remove a newsgroup may fail to
29 reach your site.
30 · Your control.ctl may be out of date or incomplete.
32 · News articles for a new newsgroup may arrive ahead (sometimes days
34 ahead) of the control message.
35 · Control messages may be forged, thus bypassing the restrictions found
37 in control.ctl unless you set up PGP authentication (and even then,
38 not all hierarchies use PGP authentication).
39 · Your active file may have been trashed.
41 If either host argument begins with "." or "/", it is assumed to be the
43 name of a file containing information in the active(5) format. The
44 getlist(1) utility may be used to obtain a copy of a remote system's
45 active file via its NNTP server, or an FTP client program can retrieve
46 such a file from an FTP archive (such as
47 <ftp://ftp.isc.org/pub/usenet/CONFIG/active>; see more about this
48 below). Newsgroup information from a file may be treated as if it was
49 obtained from a host. In this man page, the host arguments on the
50 command line are called hosts, even though they may be file names.
51 If a host argument does not begin with "." or "/", it is assumed to be
53 a hostname or Internet address. In this case, actsync will attempt to
54 use the NNTP protocol to obtain a copy of the specified system's active
55 file. If the host argument contains ":", the right side will be
56 considered the port to connect to on the remote system. If no port
57 number is specified, actsync will connect to port 119.
58 Regardless how the active file information is obtained, the actions of
60 actsync remain the same.
61 The first host specified is taken to be the local host, the one where
63 any changes would be made. The second host specified is the remote
64 host that is being synchronized with. If only one host is specified,
65 it is assumed to be the remote host to synchronize with, and the local
66 host is assumed to be the default local NNTP server as specified by the
67 NNTPSERVER environment variable or by the server value found in
68 inn.conf.
69 If either host is specified as "-", the default server will be used for
71 that host, determined as described above.
72 The newsgroup synchronization, by default, involves all newsgroups
74 found on both hosts. One may also synchronize a subset of newsgroups
75 by directing actsync to ignore certain newsgroups from both systems.
76 Only newsgroups with valid names will be synchronized. To be valid, a
77 newsgroup name must consist only of alphanumeric characters, ".", "+",
78 "-", and "_". One may not have two "." characters in a row. The first
79 character must be alphanumeric, as must any character following ".".
80 The name may not end in a "." character.
81 The actsyncd daemon provides a convenient interface to configure and
83 run actsync. If a host is not initially reachable, the daemon will
84 retry up to 9 additional times, waiting 6 minutes before each retry.
85 This daemon runs in the foreground, sending output to standard output
86 and standard error. It then uses mod-active(8) to update the active
87 file if there are commands for ctlinnd in its output.
88 The configuration filename for the daemon is given as a command line
90 argument, usually actsync.cfg in pathetc. The config file can contain
91 the following options:
92 host=<host>
94 ftppath=<path-to-active>
95 ignore_file=<ignore-file>
96 flags=<actsync-options>
97 The host=, ignore_file=, and flags= lines are mandatory. Each keyword
99 must start at the beginning of the line, and there may be no whitespace
100 before the "=" character. Blank lines are ignored, as are comment
101 lines that start with "#". Any other lines may produce undefined
102 results.
103 The <host> setting refers to the second (remote) host parameter to
105 actsync. If <path-to-active> is provided, <host> is accessed as an FTP
106 server, retrieving the file named. If the filename ends in ".gz" or
107 ".Z", it will be automatically uncompressed after retrieval.
108 <ignore-file> names the ignore file used by actsync (the -i option).
109 <actsync-options> contains any other flags that you wish to pass to
110 actsync.
111 Note that one should not include -i or -o options in the flags= line;
113 they are automatically taken care of by actsyncd.
114 One may produce a trial actsyncd run without changing anything on the
116 server by supplying the debug-level argument:
117 actsyncd <pathetc>/actsync.cfg 2
119 The debug-level causes actsyncd to run actsync with a -v debug-level
121 flag (overriding any -v flag on the flags= line), not make any changes
122 to the active file, write a new active file to standard output, and
123 write debug messages to standard error.
124 If the debug-format argument is also given to actsyncd, the data
126 written to standard output will be in -o debug-format instead of in "-o
127 a1" format.
128 INN comes with default values of "ftp.isc.org" for <host> and
130 "/pub/usenet/CONFIG/active.gz" for <path-to-active>. You can read
131 about the policies used for maintaining that active file at
132 <ftp://ftp.isc.org/pub/usenet/CONFIG/README>. Consider synchronizing
133 from this file on a daily basis by using cron.
134
136 actsync takes the following options.
137 In all of the following options, the hostid parameter takes one of the
139 following values:
140 0 neither server
142 1 local default server
143 2 remote server
144 12 both servers
145 21 both servers
146 In other words, 1 refers to the local host (the first host argument on
148 the actsync command line) and 2 refers to the remote host (the second
149 host argument, or the only one if only one is given).
150 -A actsync tries to authenticate before issuing the LIST command.
152 -b hostid
154 This flag causes actsync to ignore for synchronization purposes
155 newsgroups with "bork.bork.bork"-style names (newsgroups whose last
156 3 components are identical). For example, the following newsgroups
157 have bork-style names:
158 alt.helms.dork.dork.dork
160 alt.auto.accident.sue.sue.sue
161 alt.election.vote.vote.vote
162 The default is "-b 0"; no newsgroups are ignored because of bork-
164 style names.
165 -d hostid
167 This flag causes actsync to ignore newsgroups that have all numeric
168 path components. For example, the following newsgroups have
169 numeric path components:
170 alt.prime.chongo.23209
172 391581.times.2.to_the.216193.power.-1
173 99.bottles.of.treacle.on.the.wall
174 linfield.class.envio_bio.101.d
175 The newsgroups directory of a newsgroup with a all numeric
177 component could conflict with an article from another group if
178 stored using the tradspool storage method; see storage.conf(5).
179 For example, the directory for the first newsgroup listed above is
180 the same path as article number 23209 from the newsgroup:
181 alt.prime.chongo
183 The default is "-d 0"; all numeric newsgroups from both hosts will
185 be processed.
186 -g max
188 Ignore any newsgroup with more than max levels. For example, "-g
189 6" would ignore:
190 alt.feinstien.votes.to.trash.freedom.of.speech
192 alt.senator.exon.enemy.of.the.internet
193 alt.crypto.export.laws.dumb.dumb.dumb
194 but would not ignore:
196 alt.feinstien.acts.like.a.republican
198 alt.exon.amendment
199 alt.crypto.export.laws
200 If max is 0, then the max level feature is disabled.
202 By default, the max level feature is disabled.
204 -i ignore-file
206 The ignore-file, usually actsync.ign in pathetc, allows one to have
207 a fine degree of control over which newsgroups are ignored. It
208 contains a set of rules that specifies which newsgroups will be
209 checked and which will be ignored.
210 By default, these rules apply to both hosts. This can be modified
212 by using the -I flag.
213 Blank lines and text after a "#" are considered comments and are
215 ignored.
216 Rule lines consist of tokens separated by whitespace. Rule lines
218 may be one of two forms:
219 c <newsgroup> [<type> ...]
221 i <newsgroup> [<type> ...]
222 If the rule begins with a "c", the rule requests certain newsgroups
224 to be checked. If the rule begins with an "i", the rule requests
225 certain newsgroups to be ignored. The <newsgroup> field may be a
226 specific newsgroup, or a uwildmat(3) pattern.
227 If one or more <type>s are specified, then the rule applies to the
229 newsgroup only if it is of the specified type. Types refer to the
230 4th field of the active file; that is, a type may be one of:
231 y
233 n
234 m
235 j
236 x
237 =group.name
238 Unlike active files, the "group.name" in an alias type may be a
240 newsgroup name or a uwildmat(3) pattern. Also, "=" is equivalent
241 to "=*".
242 On each rule line, no pattern type may be repeated. For example,
244 one may not have more than one type that begins with "=", per line.
245 However, one may achieve an effect equivalent to using multiple "="
246 types by using multiple rule lines affecting the same newsgroup.
247 By default, all newsgroups are candidates to be checked. If no
249 ignore-file is specified, or if the ignore file contains no rule
250 lines, all newsgroups will be checked. If an ignore file is used,
251 each newsgroup in turn is checked against the ignore file. If
252 multiple lines match a given newsgroup, the last line in the ignore
253 file is used.
254 For example, consider the following ignore file lines:
256 i *.general
258 c *.general m
259 i nsa.general
260 The newsgroups ba.general and mod.general would be synchronized if
262 moderated and ignored if not moderated. The newsgroup nsa.general
263 would be ignored regardless of moderation status. All newsgroups
264 not matching *.general would be synchronized by default.
265 -I hostid
267 This flag restricts which hosts are affected by the ignore file.
268 This flag may be useful in conjunction with the -m flag. For
269 example:
270 actsync -i actsync.ign -I 2 -m host1 host2
272 will keep all newsgroups currently on host1. It will also only
274 compare host1 groups with non-ignored newsgroups from host2.
275 The default is "-I 12"; newsgroups from both hosts are ignored per
277 the file specified with -i.
278 -k By default, any newsgroup on the local host that has an invalid
280 name will be considered for removal. This causes actsync simply
281 ignore such newsgroups. This flag, used in combination with -m,
282 will prevent any newsgroup from being scheduled for removal.
283 -l hostid
285 This flag causes problem newsgroups of type "=" to be considered as
286 errors. Newsgroups of type "=" are newsgroups active entries that
287 have a fourth field that begins with "="; i.e., newsgroups that are
288 aliased to other newsgroups. A problem newsgroup is one for which
289 one of the following is true:
290 · Aliased to itself.
292 · In an alias chain that loops around to itself.
294 · In an alias chain longer than 16 groups.
296 · Aliased to a non-existant newsgroup.
298 · Aliased to a newsgroup that has an error of some kind.
300 However, a newsgroup that is equivalent to an ignored newsgroup is
302 not a problem.
303 The default is "-l 12": problem newsgroups from both hosts are
305 marked as errors.
306 -m Merge newsgroups instead of sync. By default, if a newsgroup
308 exists on the local host but not the remote, it will be scheduled
309 to be removed. This flag disables this process, permitting
310 newsgroups unique to the local host to be kept.
311 -n name
313 Depending on -o, the ctlinnd(8) command may be used to create
314 newsgroups as necessary. When this is done, the default creator
315 name used is "actsync". This flag changes the creator name to
316 name.
317 -o format
319 Determine the output or action format of this utility. format may
320 be one of:
321 a Output in active(5) format.
323 a1 Output in active(5) format and output non-error ignored groups
325 from the local host.
326 ak Output in active(5) format, but use the high and low (2nd and
328 3rd active fields) values from the remote host for any
329 newsgroup being created.
330 aK Output in active(5) format, but use the high and low (2nd and
332 3rd active fields) values from the remote host for all
333 newsgroups found on that host.
334 a1k Output in active(5) format, but use the high and low (2nd and
336 3rd active fields) values from the remote host for any
337 newsgroup being created and output non-error ignored groups
338 from the local host.
339 a1K Output in active(5) format, but use the high and low (2nd and
341 3rd active fields) values from the remote host for all
342 newsgroups found on that host and output non-error ignored
343 groups from the local host.
344 ak1 Same as "a1k".
346 aK1 Same as "a1K".
348 c Output as commands to ctlinnd.
350 x No output. Instead, directly run ctlinnd commands.
352 xi No output. Instead, directly run ctlinnd commands in an
354 interactive mode.
355 The "a", "a1", "ak", "aK", "a1k", "a1K", "ak1", and "aK1" style
357 formats allow one to format new active file instead of producing
358 ctlinnd commands. They use high and low values of 0000000000 and
359 0000000001 respectively for newsgroups that are created unless
360 otherwise specified. The "ak" and "aK" variants change the high
361 and low values (2nd and 3rd active fields). In the case of "ak",
362 newsgroups created take their high and low values from the remote
363 host. In the case of "aK", all newsgroups found on the remote host
364 take their high and low values from it.
365 The "c" format produces ctlinnd commands. No actions are taken
367 because actsync simply prints ctlinnd commands on standard output.
368 This output format is useful to let you see how the local host will
369 be affected by the sync (or merge) with the remote host.
370 The sync (or merge) may be accomplished directly by use of the "x"
372 or "xi" format. With this format, actsync uses the execl(2) system
373 call to directly execute ctlinnd commands. The output of such exec
374 calls may be seen if the verbosity level is at least 2.
375 The actsync utility will pause for 4 seconds before each command is
377 executed if "-o x" is selected. See the -z flag below for
378 discussion of this delay and how to customize it.
379 The "xi" format interactively prompts on standard output and reads
381 directives on standard input. One may pick and choose changes
382 using this format.
383 Care should be taken when producing active(5) formatted output.
385 One should check to be sure that actsync exited with a zero status
386 prior to using such output. Also one should realize that such
387 output will not contain lines ignored due to -i even if "-p 100" is
388 used.
389 By default, "-o c" is assumed.
391 -p min-unchanged
393 By default, the actsync utility has safeguards against performing
394 massive changes. If fewer than min-unchanged percent of the non-
395 ignored lines from the local host remain unchanged, no actions
396 (output, execution, etc.) are performed and actsync exits with a
397 non-zero exit status. The min-unchanged value may be a floating
398 point value such as 66.667.
399 A change is a local newsgroup line that was removed, added,
401 changed, or found to be in error. Changing the 2nd or 3rd active
402 fields via "-o ak" or "-o aK" are not considered changes by -p.
403 To force actsync to accept any amount of change, use the "-p 0"
405 option. To force actsync to reject any changes, use the "-p 100"
406 option.
407 Care should be taken when producing active(5) formatted output.
409 One should check to be sure that actsync exited with a zero status
410 prior to using such output. Also one should realize that such
411 output will not contain lines ignored due to -i even if "-p 100" is
412 used.
413 By default, 96% of the lines not ignored in the first host argument
415 on the actsync command line must be unchanged. That is, by
416 default, "-p 96" is assumed.
417 -q hostid
419 By default, all newsgroup errors are reported on standard error.
420 This flag quiets errors from the specified hostid.
421 -s size
423 If size is greater than 0, then ignore newsgroups with names longer
424 than size and ignore newsgroups aliased (by following "=" chains)
425 to names longer than size. Length checking is performed on both
426 the local and remote hosts.
427 By default, size is 0 and thus no length checking is performed.
429 -t hostid
431 Ignore improper newsgroups consisting of only a top component from
432 the specified hostid. The following newsgroups are considered
433 proper newsgroups despite top only names and therefore are exempt
434 from this flag:
435 control
437 general
438 junk
439 test
440 to
441 For example, the following newsgroup names are improper because
443 they only contain a top level component:
444 dole_for_pres
446 dos
447 microsoft
448 windows95
449 The default is "-t 2"; that is, all improper top-level-only
451 newsgroups from the remote host are ignored.
452 -T This flag causes newsgroups on the remote host in new hierarchies
454 to be ignored. Normally a newsgroup which only exists on the
455 remote host, chongo.was.here for example, is created on the local
456 host. However, if this flag is given and the local host does not
457 have any other newsgroups in the same hierarchy (chongo.* in this
458 case), the newsgroup in question will be ignored and will not be
459 created on the local host.
460 -v verbosity
462 By default, actsync is not verbose. This flag controls the
463 verbosity level as follows:
464 0 No debug or status reports (default).
466 1 Print summary, but only if work was needed or done.
468 2 Print actions, exec output, and summary, but only if work was
470 needed or done.
471 3 Print actions, exec output, and summary.
473 4 Full debug output.
475 -w seconds
477 If "-o x" or "-o xi" is selected, ctlinnd will wait seconds seconds
478 before timing out. The default value is "-w 30".
479 -z seconds
481 If "-o x" is selected, actsync will pause for seconds seconds
482 before each command is executed. This helps prevent innd from
483 being busied-out if a large number of ctlinnd commands are needed.
484 One can entirely disable this sleeping by using "-z 0".
485 By default, actsync will pause for 4 seconds before each command is
487 executed if "-o x" is selected.
488
490 Determine the difference (but don't change anything) between your
491 newsgroup set and uunet's set:
492 actsync news.uu.net
494 Same as above, with full debug and progress reports:
496 actsync -v 4 news.uu.net
498 Force a site to have the same newsgroups as some other site:
500 actsync -o x master
502 This may be useful to sync a slave site to its master, or to sync
504 internal site to a gateway.
505 Compare your site with uunet, disregarding local groups and certain
507 local differences with uunet. Produce a report if any differences were
508 encountered:
509 actsync -v 2 -i actsync.ign news.uu.net
511 where actsync.ign contains:
513 # Don't compare to.* groups as they will differ.
515 #
516 i to.*
517 # These are our local groups that nobody else
519 # (should) carry. So ignore them for the sake
520 # of the compare.
521 #
522 i nsa.*
523 # These groups are local favorites, so keep them
525 # even if uunet does not carry them.
526 #
527 i ca.dump.bob.dorman
528 i ca.keep.bob.dorman
529 i alt.tv.dinosaurs.barney.die.die.die
530 i alt.tv.dinosaurs.barney.love.love.love
531 i alt.sounds.* =alt.binaries.sounds.*
532 To interactively sync against news.uu.net, using the same ignore file:
534 actsync -o xi -v 2 -i actsync.ign news.uu.net
536 Based on newsgroups that you decided to keep, one could make changes to
538 the actsync.ign file:
539 # Don't compare to.* groups as they will differ.
541 #
542 i to.*
543 # These are our local groups that nobody else
545 # (should) carry. So ignore them for the sake
546 # of the compare.
547 #
548 i nsa.*
549 # These groups are local favorites, so keep them
551 # even if uunet does not carry them.
552 #
553 i ca.dump.bob.dorman
554 i alt.tv.dinosaurs.barney.die.die.die
555 i alt.sounds.* =alt.binaries.sounds.*
556 # Don't sync test groups, except for ones that are
558 # moderated or that are under the gnu hierarchy.
559 #
560 i *.test
561 c *.test m # check moderated test groups
562 c gnu.*.test
563 c gnu.test # just in case it ever exists
564 Automatic processing may be set up by using the following actsync.cfg
566 file:
567 # Host to sync off of (host2).
569 host=news.uu.net
570 # Location of the ignore file.
572 ignore_file=<pathetc in inn.conf>/actsync.ign
573 # Where news articles are kept.
575 spool=<patharticles in inn.conf>
576 # actsync(8) flags
578 #
579 # Automatic execs, report if something was done,
580 # otherwise don't say anything, don't report
581 # uunet active file problems, just ignore
582 # the affected entries.
583 flags=-o x -v 2 -q 2
584 and then by running actsyncd with the path to the config file:
586 actsyncd <pathetc>/actsync.cfg
588 The command
590 actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log
592 will operate in debug mode, not change the active file, write ctlinnd
594 style commands to cmd.log, and write debug statements to dbg.log.
595 To check only the major hierarchies against news.uu,net, use the
597 following actsync.ign file:
598 # By default, ignore everything.
600 #
601 i *
602 # Check the major groups.
604 #
605 c alt.*
606 c comp.*
607 c gnu.*
608 c humanities.*
609 c misc.*
610 c news.*
611 c rec.*
612 c sci.*
613 c soc.*
614 c talk.*
615 and the command:
617 actsync -i actsync.ign news.uu.net
619 To determine the differences between your old active and your current
621 default server:
622 actsync <pathetc>/active.old -
624 To report but not fix any newsgroup problems with the current active
626 file:
627 actsync - -
629 To detect any newsgroup errors on your local server, and to remove any
631 *.bork.bork.bork-style silly newsgroup names:
632 actsync -b 2 - -
634 The active file produced by:
636 actsync <flags> -o x erehwon.honey.edu
638 is effectively the same as the active file produced by:
640 cd <pathdb>
642 ctlinnd pause 'running actsync'
643 rm -f active.new
644 actsync <flags> -o a1 erehwon.honey.edu > active.new
645 rm -f active.old
646 ln active active.old
647 mv active.new active
648 ctlinnd reload active 'running actsync'
649 ctlinnd go 'running actsync'
650 It should be noted that the final method above, pausing the server and
652 simply replacing the active file, may be faster if you are making lots
653 of changes.
654
656 pathbin/actsync
657 The C program itself used to synchronize, compare, or merge two
658 active files.
659 pathbin/actsyncd
661 The Shell daemon which provides a convenient interface to configure
662 and run actsync.
663 pathetc/actsync.cfg
665 The configuration file which specifies the settings to use.
666 pathetc/actsync.ign
668 The ignore file which contains a set of synchronization rules that
669 specifies which newsgroups will be checked and which will be
670 ignored.
671
673 Careless use of this tool may result in the unintended addition,
674 change, or removal of newsgroups. You should avoid using the "x"
675 output format until you are sure it will do what you want.
676
678 If a newsgroup appears multiple times, actsync will treat all copies as
679 errors. However, if the group is marked for removal, only one rmgroup
680 will be issued.
681
683 Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
684 Updated to support FTP fetching by David Lawrence <tale@isc.org>.
685 Converted to POD by Russ Allbery <rra@stanford.edu>.
686 $Id: actsync.pod 7941 2008-08-02 17:10:27Z iulius $
688 By: Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).
690 Copyright (c) Landon Curt Noll, 1993. All rights reserved.
692 Permission to use and modify is hereby granted so long as this notice
694 remains. Use at your own risk. No warranty is implied.
695
697 active(5), ctlinnd(8), getlist(8), inn.conf(5), mod-active(8),
698 simpleftp(1).
699INN 2.5.2 2010-08-11 ACTSYNC(8)