1ACTSYNC(8) InterNetNews Documentation ACTSYNC(8)
2
3
4
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
14 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
25 There are several reasons to run actsync (or actsyncd) on a periodic
26 basis. Among the reasons are:
27
28 · A control message to add, change or remove a newsgroup may fail to
29 reach your site.
30
31 · Your control.ctl may be out of date or incomplete.
32
33 · News articles for a new newsgroup may arrive ahead (sometimes days
34 ahead) of the control message.
35
36 · 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
40 · Your active file may have been trashed.
41
42 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
53 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
60 Regardless how the active file information is obtained, the actions of
61 actsync remain the same.
62
63 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
71 If either host is specified as "-", the default server will be used for
72 that host, determined as described above.
73
74 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
83 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
90 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
94 host=<host>
95 ftppath=<path-to-active>
96 ignore_file=<ignore-file>
97 flags=<actsync-options>
98
99 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
105 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
113 Note that one should not include -i or -o options in the flags= line;
114 they are automatically taken care of by actsyncd.
115
116 One may produce a trial actsyncd run without changing anything on the
117 server by supplying the debug-level argument:
118
119 actsyncd <pathetc>/actsync.cfg 2
120
121 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
126 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
130 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
139 In all of the following options, the hostid parameter takes one of the
140 following values:
141
142 0 neither server
143 1 local default server
144 2 remote server
145 12 both servers
146 21 both servers
147
148 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
152 -A actsync tries to authenticate before issuing the LIST command.
153
154 -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
160 alt.helms.dork.dork.dork
161 alt.auto.accident.sue.sue.sue
162 alt.election.vote.vote.vote
163
164 The default is "-b 0"; no newsgroups are ignored because of bork-
165 style names.
166
167 -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
172 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
177 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
183 alt.prime.chongo
184
185 The default is "-d 0"; all numeric newsgroups from both hosts will
186 be processed.
187
188 -g max
189 Ignore any newsgroup with more than max levels. For example, "-g
190 6" would ignore:
191
192 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
196 but would not ignore:
197
198 alt.feinstien.acts.like.a.republican
199 alt.exon.amendment
200 alt.crypto.export.laws
201
202 If max is 0, then the max level feature is disabled.
203
204 By default, the max level feature is disabled.
205
206 -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
212 By default, these rules apply to both hosts. This can be modified
213 by using the -I flag.
214
215 Blank lines and text after a "#" are considered comments and are
216 ignored.
217
218 Rule lines consist of tokens separated by whitespace. Rule lines
219 may be one of two forms:
220
221 c <newsgroup> [<type> ...]
222 i <newsgroup> [<type> ...]
223
224 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
229 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
233 y
234 n
235 m
236 j
237 x
238 =group.name
239
240 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
244 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
249 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
256 For example, consider the following ignore file lines:
257
258 i *.general
259 c *.general m
260 i nsa.general
261
262 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
267 -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
272 actsync -i actsync.ign -I 2 -m host1 host2
273
274 will keep all newsgroups currently on host1. It will also only
275 compare host1 groups with non-ignored newsgroups from host2.
276
277 The default is "-I 12"; newsgroups from both hosts are ignored per
278 the file specified with -i.
279
280 -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
285 -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
292 · Aliased to itself.
293
294 · In an alias chain that loops around to itself.
295
296 · In an alias chain longer than 16 groups.
297
298 · Aliased to a non-existant newsgroup.
299
300 · Aliased to a newsgroup that has an error of some kind.
301
302 However, a newsgroup that is equivalent to an ignored newsgroup is
303 not a problem.
304
305 The default is "-l 12": problem newsgroups from both hosts are
306 marked as errors.
307
308 -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
313 -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
319 -o format
320 Determine the output or action format of this utility. format may
321 be one of:
322
323 a Output in active(5) format.
324
325 a1 Output in active(5) format and output non-error ignored groups
326 from the local host.
327
328 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
332 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
336 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
341 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
346 ak1 Same as "a1k".
347
348 aK1 Same as "a1K".
349
350 c Output as commands to ctlinnd.
351
352 x No output. Instead, directly run ctlinnd commands.
353
354 xi No output. Instead, directly run ctlinnd commands in an
355 interactive mode.
356
357 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
367 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
372 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
377 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
381 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
385 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
391 By default, "-o c" is assumed.
392
393 -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
401 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
405 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
409 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
415 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
419 -q hostid
420 By default, all newsgroup errors are reported on standard error.
421 This flag quiets errors from the specified hostid.
422
423 -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
429 By default, size is 0 and thus no length checking is performed.
430
431 -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
437 control
438 general
439 junk
440 test
441 to
442
443 For example, the following newsgroup names are improper because
444 they only contain a top level component:
445
446 dole_for_pres
447 dos
448 microsoft
449 windows95
450
451 The default is "-t 2"; that is, all improper top-level-only
452 newsgroups from the remote host are ignored.
453
454 -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
462 -v verbosity
463 By default, actsync is not verbose. This flag controls the
464 verbosity level as follows:
465
466 0 No debug or status reports (default).
467
468 1 Print summary, but only if work was needed or done.
469
470 2 Print actions, exec output, and summary, but only if work was
471 needed or done.
472
473 3 Print actions, exec output, and summary.
474
475 4 Full debug output.
476
477 -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
481 -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
487 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
494 actsync news.uu.net
495
496 Same as above, with full debug and progress reports:
497
498 actsync -v 4 news.uu.net
499
500 Force a site to have the same newsgroups as some other site:
501
502 actsync -o x master
503
504 This may be useful to sync a slave site to its master, or to sync
505 internal site to a gateway.
506
507 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
511 actsync -v 2 -i actsync.ign news.uu.net
512
513 where actsync.ign contains:
514
515 # Don't compare to.* groups as they will differ.
516 #
517 i to.*
518
519 # 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
525 # 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
534 To interactively sync against news.uu.net, using the same ignore file:
535
536 actsync -o xi -v 2 -i actsync.ign news.uu.net
537
538 Based on newsgroups that you decided to keep, one could make changes to
539 the actsync.ign file:
540
541 # Don't compare to.* groups as they will differ.
542 #
543 i to.*
544
545 # 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
551 # 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
558 # 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
566 Automatic processing may be set up by using the following actsync.cfg
567 file:
568
569 # Host to sync off of (host2).
570 host=news.uu.net
571
572 # Location of the ignore file.
573 ignore_file=<pathetc in inn.conf>/actsync.ign
574
575 # Where news articles are kept.
576 spool=<patharticles in inn.conf>
577
578 # 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
586 and then by running actsyncd with the path to the config file:
587
588 actsyncd <pathetc>/actsync.cfg
589
590 The command
591
592 actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log
593
594 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
597 To check only the major hierarchies against news.uu,net, use the
598 following actsync.ign file:
599
600 # By default, ignore everything.
601 #
602 i *
603
604 # 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
617 and the command:
618
619 actsync -i actsync.ign news.uu.net
620
621 To determine the differences between your old active and your current
622 default server:
623
624 actsync <pathetc>/active.old -
625
626 To report but not fix any newsgroup problems with the current active
627 file:
628
629 actsync - -
630
631 To detect any newsgroup errors on your local server, and to remove any
632 *.bork.bork.bork-style silly newsgroup names:
633
634 actsync -b 2 - -
635
636 The active file produced by:
637
638 actsync <flags> -o x erehwon.honey.edu
639
640 is effectively the same as the active file produced by:
641
642 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
652 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
661 pathbin/actsyncd
662 The Shell daemon which provides a convenient interface to configure
663 and run actsync.
664
665 pathetc/actsync.cfg
666 The configuration file which specifies the settings to use.
667
668 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
688 $Id: actsync.pod 10097 2016-11-04 22:19:07Z iulius $
689
690 By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).
691
692 Copyright (c) Landon Curt Noll, 1993. All rights reserved.
693
694 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).
700
701
702
703INN 2.6.3 2016-11-06 ACTSYNC(8)