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 ftp.isc.org available in both
47 FTP and HTTPS <https://ftp.isc.org/pub/usenet/CONFIG/active>; see more
48 about this below). Newsgroup information from a file may be treated as
49 if it was obtained from a host. In this man page, the host arguments
50 on the command line are called hosts, even though they may be file
51 names.
52 If a host argument does not begin with "." or "/", it is assumed to be
54 a hostname or Internet address. In this case, actsync will attempt to
55 use the NNTP protocol to obtain a copy of the specified system's active
56 file. If the host argument contains ":", the right side will be
57 considered the port to connect to on the remote system. If no port
58 number is specified, actsync will connect to port 119.
59 Regardless how the active file information is obtained, the actions of
61 actsync remain the same.
62 The first host specified is taken to be the local host, the one where
64 any changes would be made. The second host specified is the remote
65 host that is being synchronized with. If only one host is specified,
66 it is assumed to be the remote host to synchronize with, and the local
67 host is assumed to be the default local NNTP server as specified by the
68 NNTPSERVER environment variable or by the server value found in
69 inn.conf.
70 If either host is specified as "-", the default server will be used for
72 that host, determined as described above.
73 The newsgroup synchronization, by default, involves all newsgroups
75 found on both hosts. One may also synchronize a subset of newsgroups
76 by directing actsync to ignore certain newsgroups from both systems.
77 Only newsgroups with valid names will be synchronized. To be valid, a
78 newsgroup name must consist only of alphanumeric characters, ".", "+",
79 "-", and "_". One may not have two "." characters in a row. The first
80 character must be alphanumeric, as must any character following ".".
81 The name may not end in a "." character.
82 The actsyncd daemon provides a convenient interface to configure and
84 run actsync. If a host is not initially reachable, the daemon will
85 retry up to 9 additional times, waiting 6 minutes before each retry.
86 This daemon runs in the foreground, sending output to standard output
87 and standard error. It then uses mod-active(8) to update the active
88 file if there are commands for ctlinnd in its output.
89 The configuration filename for the daemon is given as a command line
91 argument, usually actsync.cfg in pathetc. The config file can contain
92 the following options:
93 host=<host>
95 ftppath=<path-to-active>
96 ignore_file=<ignore-file>
97 flags=<actsync-options>
98 The host=, ignore_file=, and flags= lines are mandatory. Each keyword
100 must start at the beginning of the line, and there may be no whitespace
101 before the "=" character. Blank lines are ignored, as are comment
102 lines that start with "#". Any other lines may produce undefined
103 results.
104 The <host> setting refers to the second (remote) host parameter to
106 actsync. If <path-to-active> is provided, <host> is accessed as an FTP
107 server, retrieving the file named. If the filename ends in ".gz" or
108 ".Z", it will be automatically uncompressed after retrieval.
109 <ignore-file> names the ignore file used by actsync (the -i option).
110 <actsync-options> contains any other flags that you wish to pass to
111 actsync.
112 Note that one should not include -i or -o options in the flags= line;
114 they are automatically taken care of by actsyncd.
115 One may produce a trial actsyncd run without changing anything on the
117 server by supplying the debug-level argument:
118 actsyncd <pathetc>/actsync.cfg 2
120 The debug-level causes actsyncd to run actsync with a -v debug-level
122 flag (overriding any -v flag on the flags= line), not make any changes
123 to the active file, write a new active file to standard output, and
124 write debug messages to standard error.
125 If the debug-format argument is also given to actsyncd, the data
127 written to standard output will be in -o debug-format instead of in "-o
128 a1" format.
129 INN comes with default values of "ftp.isc.org" for <host> and
131 "/pub/usenet/CONFIG/active.gz" for <path-to-active>. You can read
132 about the policies used for maintaining that active file at
133 <https://ftp.isc.org/pub/usenet/CONFIG/README>. Consider synchronizing
134 from this file on a daily basis by using cron.
135
137 actsync takes the following options.
138 In all of the following options, the hostid parameter takes one of the
140 following values:
141 0 neither server
143 1 local default server
144 2 remote server
145 12 both servers
146 21 both servers
147 In other words, 1 refers to the local host (the first host argument on
149 the actsync command line) and 2 refers to the remote host (the second
150 host argument, or the only one if only one is given).
151 -A actsync tries to authenticate before issuing the LIST command.
153 -b hostid
155 This flag causes actsync to ignore for synchronization purposes
156 newsgroups with "bork.bork.bork"-style names (newsgroups whose last
157 3 components are identical). For example, the following newsgroups
158 have bork-style names:
159 alt.helms.dork.dork.dork
161 alt.auto.accident.sue.sue.sue
162 alt.election.vote.vote.vote
163 The default is "-b 0"; no newsgroups are ignored because of bork-
165 style names.
166 -d hostid
168 This flag causes actsync to ignore newsgroups that have all numeric
169 path components. For example, the following newsgroups have
170 numeric path components:
171 alt.prime.chongo.23209
173 391581.times.2.to_the.216193.power.-1
174 99.bottles.of.treacle.on.the.wall
175 linfield.class.envio_bio.101.d
176 The newsgroups directory of a newsgroup with a all numeric
178 component could conflict with an article from another group if
179 stored using the tradspool storage method; see storage.conf(5).
180 For example, the directory for the first newsgroup listed above is
181 the same path as article number 23209 from the newsgroup:
182 alt.prime.chongo
184 The default is "-d 0"; all numeric newsgroups from both hosts will
186 be processed.
187 -g max
189 Ignore any newsgroup with more than max levels. For example, "-g
190 6" would ignore:
191 alt.feinstien.votes.to.trash.freedom.of.speech
193 alt.senator.exon.enemy.of.the.internet
194 alt.crypto.export.laws.dumb.dumb.dumb
195 but would not ignore:
197 alt.feinstien.acts.like.a.republican
199 alt.exon.amendment
200 alt.crypto.export.laws
201 If max is 0, then the max level feature is disabled.
203 By default, the max level feature is disabled.
205 -i ignore-file
207 The ignore-file, usually actsync.ign in pathetc, allows one to have
208 a fine degree of control over which newsgroups are ignored. It
209 contains a set of rules that specifies which newsgroups will be
210 checked and which will be ignored.
211 By default, these rules apply to both hosts. This can be modified
213 by using the -I flag.
214 Blank lines and text after a "#" are considered comments and are
216 ignored.
217 Rule lines consist of tokens separated by whitespace. Rule lines
219 may be one of two forms:
220 c <newsgroup> [<type> ...]
222 i <newsgroup> [<type> ...]
223 If the rule begins with a "c", the rule requests certain newsgroups
225 to be checked. If the rule begins with an "i", the rule requests
226 certain newsgroups to be ignored. The <newsgroup> field may be a
227 specific newsgroup, or a uwildmat(3) pattern.
228 If one or more <type>s are specified, then the rule applies to the
230 newsgroup only if it is of the specified type. Types refer to the
231 4th field of the active file; that is, a type may be one of:
232 y
234 n
235 m
236 j
237 x
238 =group.name
239 Unlike active files, the "group.name" in an alias type may be a
241 newsgroup name or a uwildmat(3) pattern. Also, "=" is equivalent
242 to "=*".
243 On each rule line, no pattern type may be repeated. For example,
245 one may not have more than one type that begins with "=", per line.
246 However, one may achieve an effect equivalent to using multiple "="
247 types by using multiple rule lines affecting the same newsgroup.
248 By default, all newsgroups are candidates to be checked. If no
250 ignore-file is specified, or if the ignore file contains no rule
251 lines, all newsgroups will be checked. If an ignore file is used,
252 each newsgroup in turn is checked against the ignore file. If
253 multiple lines match a given newsgroup, the last line in the ignore
254 file is used.
255 For example, consider the following ignore file lines:
257 i *.general
259 c *.general m
260 i nsa.general
261 The newsgroups ba.general and mod.general would be synchronized if
263 moderated and ignored if not moderated. The newsgroup nsa.general
264 would be ignored regardless of moderation status. All newsgroups
265 not matching *.general would be synchronized by default.
266 -I hostid
268 This flag restricts which hosts are affected by the ignore file.
269 This flag may be useful in conjunction with the -m flag. For
270 example:
271 actsync -i actsync.ign -I 2 -m host1 host2
273 will keep all newsgroups currently on host1. It will also only
275 compare host1 groups with non-ignored newsgroups from host2.
276 The default is "-I 12"; newsgroups from both hosts are ignored per
278 the file specified with -i.
279 -k By default, any newsgroup on the local host that has an invalid
281 name will be considered for removal. This causes actsync simply
282 ignore such newsgroups. This flag, used in combination with -m,
283 will prevent any newsgroup from being scheduled for removal.
284 -l hostid
286 This flag causes problem newsgroups of type "=" to be considered as
287 errors. Newsgroups of type "=" are newsgroups active entries that
288 have a fourth field that begins with "="; i.e., newsgroups that are
289 aliased to other newsgroups. A problem newsgroup is one for which
290 one of the following is true:
291 · Aliased to itself.
293 · In an alias chain that loops around to itself.
295 · In an alias chain longer than 16 groups.
297 · Aliased to a non-existant newsgroup.
299 · Aliased to a newsgroup that has an error of some kind.
301 However, a newsgroup that is equivalent to an ignored newsgroup is
303 not a problem.
304 The default is "-l 12": problem newsgroups from both hosts are
306 marked as errors.
307 -m Merge newsgroups instead of sync. By default, if a newsgroup
309 exists on the local host but not the remote, it will be scheduled
310 to be removed. This flag disables this process, permitting
311 newsgroups unique to the local host to be kept.
312 -n name
314 Depending on -o, the ctlinnd(8) command may be used to create
315 newsgroups as necessary. When this is done, the default creator
316 name used is "actsync". This flag changes the creator name to
317 name.
318 -o format
320 Determine the output or action format of this utility. format may
321 be one of:
322 a Output in active(5) format.
324 a1 Output in active(5) format and output non-error ignored groups
326 from the local host.
327 ak Output in active(5) format, but use the high and low (2nd and
329 3rd active fields) values from the remote host for any
330 newsgroup being created.
331 aK Output in active(5) format, but use the high and low (2nd and
333 3rd active fields) values from the remote host for all
334 newsgroups found on that host.
335 a1k Output in active(5) format, but use the high and low (2nd and
337 3rd active fields) values from the remote host for any
338 newsgroup being created and output non-error ignored groups
339 from the local host.
340 a1K Output in active(5) format, but use the high and low (2nd and
342 3rd active fields) values from the remote host for all
343 newsgroups found on that host and output non-error ignored
344 groups from the local host.
345 ak1 Same as "a1k".
347 aK1 Same as "a1K".
349 c Output as commands to ctlinnd.
351 x No output. Instead, directly run ctlinnd commands.
353 xi No output. Instead, directly run ctlinnd commands in an
355 interactive mode.
356 The "a", "a1", "ak", "aK", "a1k", "a1K", "ak1", and "aK1" style
358 formats allow one to format new active file instead of producing
359 ctlinnd commands. They use high and low values of 0000000000 and
360 0000000001 respectively for newsgroups that are created unless
361 otherwise specified. The "ak" and "aK" variants change the high
362 and low values (2nd and 3rd active fields). In the case of "ak",
363 newsgroups created take their high and low values from the remote
364 host. In the case of "aK", all newsgroups found on the remote host
365 take their high and low values from it.
366 The "c" format produces ctlinnd commands. No actions are taken
368 because actsync simply prints ctlinnd commands on standard output.
369 This output format is useful to let you see how the local host will
370 be affected by the sync (or merge) with the remote host.
371 The sync (or merge) may be accomplished directly by use of the "x"
373 or "xi" format. With this format, actsync uses the execl(2) system
374 call to directly execute ctlinnd commands. The output of such exec
375 calls may be seen if the verbosity level is at least 2.
376 The actsync utility will pause for 4 seconds before each command is
378 executed if "-o x" is selected. See the -z flag below for
379 discussion of this delay and how to customize it.
380 The "xi" format interactively prompts on standard output and reads
382 directives on standard input. One may pick and choose changes
383 using this format.
384 Care should be taken when producing active(5) formatted output.
386 One should check to be sure that actsync exited with a zero status
387 prior to using such output. Also one should realize that such
388 output will not contain lines ignored due to -i even if "-p 100" is
389 used.
390 By default, "-o c" is assumed.
392 -p min-unchanged
394 By default, the actsync utility has safeguards against performing
395 massive changes. If fewer than min-unchanged percent of the non-
396 ignored lines from the local host remain unchanged, no actions
397 (output, execution, etc.) are performed and actsync exits with a
398 non-zero exit status. The min-unchanged value may be a floating
399 point value such as 66.667.
400 A change is a local newsgroup line that was removed, added,
402 changed, or found to be in error. Changing the 2nd or 3rd active
403 fields via "-o ak" or "-o aK" are not considered changes by -p.
404 To force actsync to accept any amount of change, use the "-p 0"
406 option. To force actsync to reject any changes, use the "-p 100"
407 option.
408 Care should be taken when producing active(5) formatted output.
410 One should check to be sure that actsync exited with a zero status
411 prior to using such output. Also one should realize that such
412 output will not contain lines ignored due to -i even if "-p 100" is
413 used.
414 By default, 96% of the lines not ignored in the first host argument
416 on the actsync command line must be unchanged. That is, by
417 default, "-p 96" is assumed.
418 -q hostid
420 By default, all newsgroup errors are reported on standard error.
421 This flag quiets errors from the specified hostid.
422 -s size
424 If size is greater than 0, then ignore newsgroups with names longer
425 than size and ignore newsgroups aliased (by following "=" chains)
426 to names longer than size. Length checking is performed on both
427 the local and remote hosts.
428 By default, size is 0 and thus no length checking is performed.
430 -t hostid
432 Ignore improper newsgroups consisting of only a top component from
433 the specified hostid. The following newsgroups are considered
434 proper newsgroups despite top only names and therefore are exempt
435 from this flag:
436 control
438 general
439 junk
440 test
441 to
442 For example, the following newsgroup names are improper because
444 they only contain a top level component:
445 dole_for_pres
447 dos
448 microsoft
449 windows95
450 The default is "-t 2"; that is, all improper top-level-only
452 newsgroups from the remote host are ignored.
453 -T This flag causes newsgroups on the remote host in new hierarchies
455 to be ignored. Normally a newsgroup which only exists on the
456 remote host, chongo.was.here for example, is created on the local
457 host. However, if this flag is given and the local host does not
458 have any other newsgroups in the same hierarchy (chongo.* in this
459 case), the newsgroup in question will be ignored and will not be
460 created on the local host.
461 -v verbosity
463 By default, actsync is not verbose. This flag controls the
464 verbosity level as follows:
465 0 No debug or status reports (default).
467 1 Print summary, but only if work was needed or done.
469 2 Print actions, exec output, and summary, but only if work was
471 needed or done.
472 3 Print actions, exec output, and summary.
474 4 Full debug output.
476 -w seconds
478 If "-o x" or "-o xi" is selected, ctlinnd will wait seconds seconds
479 before timing out. The default value is "-w 30".
480 -z seconds
482 If "-o x" is selected, actsync will pause for seconds seconds
483 before each command is executed. This helps prevent innd from
484 being busied-out if a large number of ctlinnd commands are needed.
485 One can entirely disable this sleeping by using "-z 0".
486 By default, actsync will pause for 4 seconds before each command is
488 executed if "-o x" is selected.
489
491 Determine the difference (but don't change anything) between your
492 newsgroup set and uunet's set:
493 actsync news.uu.net
495 Same as above, with full debug and progress reports:
497 actsync -v 4 news.uu.net
499 Force a site to have the same newsgroups as some other site:
501 actsync -o x master
503 This may be useful to sync a slave site to its master, or to sync
505 internal site to a gateway.
506 Compare your site with uunet, disregarding local groups and certain
508 local differences with uunet. Produce a report if any differences were
509 encountered:
510 actsync -v 2 -i actsync.ign news.uu.net
512 where actsync.ign contains:
514 # Don't compare to.* groups as they will differ.
516 #
517 i to.*
518 # These are our local groups that nobody else
520 # (should) carry. So ignore them for the sake
521 # of the compare.
522 #
523 i nsa.*
524 # These groups are local favorites, so keep them
526 # even if uunet does not carry them.
527 #
528 i ca.dump.bob.dorman
529 i ca.keep.bob.dorman
530 i alt.tv.dinosaurs.barney.die.die.die
531 i alt.tv.dinosaurs.barney.love.love.love
532 i alt.sounds.* =alt.binaries.sounds.*
533 To interactively sync against news.uu.net, using the same ignore file:
535 actsync -o xi -v 2 -i actsync.ign news.uu.net
537 Based on newsgroups that you decided to keep, one could make changes to
539 the actsync.ign file:
540 # Don't compare to.* groups as they will differ.
542 #
543 i to.*
544 # These are our local groups that nobody else
546 # (should) carry. So ignore them for the sake
547 # of the compare.
548 #
549 i nsa.*
550 # These groups are local favorites, so keep them
552 # even if uunet does not carry them.
553 #
554 i ca.dump.bob.dorman
555 i alt.tv.dinosaurs.barney.die.die.die
556 i alt.sounds.* =alt.binaries.sounds.*
557 # Don't sync test groups, except for ones that are
559 # moderated or that are under the gnu hierarchy.
560 #
561 i *.test
562 c *.test m # check moderated test groups
563 c gnu.*.test
564 c gnu.test # just in case it ever exists
565 Automatic processing may be set up by using the following actsync.cfg
567 file:
568 # Host to sync off of (host2).
570 host=news.uu.net
571 # Location of the ignore file.
573 ignore_file=<pathetc in inn.conf>/actsync.ign
574 # Where news articles are kept.
576 spool=<patharticles in inn.conf>
577 # actsync(8) flags
579 #
580 # Automatic execs, report if something was done,
581 # otherwise don't say anything, don't report
582 # uunet active file problems, just ignore
583 # the affected entries.
584 flags=-o x -v 2 -q 2
585 and then by running actsyncd with the path to the config file:
587 actsyncd <pathetc>/actsync.cfg
589 The command
591 actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log
593 will operate in debug mode, not change the active file, write ctlinnd
595 style commands to cmd.log, and write debug statements to dbg.log.
596 To check only the major hierarchies against news.uu,net, use the
598 following actsync.ign file:
599 # By default, ignore everything.
601 #
602 i *
603 # Check the major groups.
605 #
606 c alt.*
607 c comp.*
608 c gnu.*
609 c humanities.*
610 c misc.*
611 c news.*
612 c rec.*
613 c sci.*
614 c soc.*
615 c talk.*
616 and the command:
618 actsync -i actsync.ign news.uu.net
620 To determine the differences between your old active and your current
622 default server:
623 actsync <pathetc>/active.old -
625 To report but not fix any newsgroup problems with the current active
627 file:
628 actsync - -
630 To detect any newsgroup errors on your local server, and to remove any
632 *.bork.bork.bork-style silly newsgroup names:
633 actsync -b 2 - -
635 The active file produced by:
637 actsync <flags> -o x erehwon.honey.edu
639 is effectively the same as the active file produced by:
641 cd <pathdb>
643 ctlinnd pause 'running actsync'
644 rm -f active.new
645 actsync <flags> -o a1 erehwon.honey.edu > active.new
646 rm -f active.old
647 ln active active.old
648 mv active.new active
649 ctlinnd reload active 'running actsync'
650 ctlinnd go 'running actsync'
651 It should be noted that the final method above, pausing the server and
653 simply replacing the active file, may be faster if you are making lots
654 of changes.
655
657 pathbin/actsync
658 The C program itself used to synchronize, compare, or merge two
659 active files.
660 pathbin/actsyncd
662 The Shell daemon which provides a convenient interface to configure
663 and run actsync.
664 pathetc/actsync.cfg
666 The configuration file which specifies the settings to use.
667 pathetc/actsync.ign
669 The ignore file which contains a set of synchronization rules that
670 specifies which newsgroups will be checked and which will be
671 ignored.
672
674 Careless use of this tool may result in the unintended addition,
675 change, or removal of newsgroups. You should avoid using the "x"
676 output format until you are sure it will do what you want.
677
679 If a newsgroup appears multiple times, actsync will treat all copies as
680 errors. However, if the group is marked for removal, only one rmgroup
681 will be issued.
682
684 Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
685 Updated to support FTP fetching by David Lawrence <tale@isc.org>.
686 Converted to POD by Russ Allbery <eagle@eyrie.org>.
687 $Id: actsync.pod 10097 2016-11-04 22:19:07Z iulius $
689 By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).
691 Copyright (c) Landon Curt Noll, 1993. All rights reserved.
693 Permission to use and modify is hereby granted so long as this notice
695 remains. Use at your own risk. No warranty is implied.
696
698 active(5), ctlinnd(8), getlist(8), inn.conf(5), mod-active(8),
699 simpleftp(1).
700INN 2.6.3 2016-11-06 ACTSYNC(8)