1ACTSYNC(8) System Manager's Manual ACTSYNC(8)
2
6 actsync, actsyncd - synchronize newsgroups
7
9 actsync [-A] [-b hostid] [-d hostid] [-g max]
10 [-i ignore_file] [-I hostid] [-k] [-l hostid] [-m]
11 [-n name] [-o fmt] [-p min_%_unchg] [-q hostid]
12 [-s size] [-t hostid] [-T] [-v verbosity]
13 [-z sec] [host1] host2
14 actsyncd [-x] actsync.cfg [debug_level [debug_outfmt] ]
16
18 Actsync(8) permits one to synchronize, compare, or merge two active
19 files. With this utility one may add, change, or remove newsgroups on
20 the local news server to make it similar to the list the newsgroups
21 found on another system or file. The synchronization need not be
22 exact. Local differences in newsgroup lists may be maintained and pre‐
23 served. Certain newsgroup errors may be detected and optionally cor‐
24 rected.
25 There are several reasons to run actsync(8) (or actsyncd(8)), on a
27 periodic basis. Among the reasons are:
28 A control message to add, change or remove a newsgroup may fail to
30 reach your site.
31 Your control.ctl may be out of date or incomplete.
33 News articles for a new newsgroup can arrive ahead (sometimes days
35 ahead) of the control message.
36 Control messages may be forged, thus bypassing the restrictions
38 found in control.ctl .
39 Your active file may have been trashed.
41 If host1 or host2 begins with a ``.'' or ``/'', then it is assumed to
44 be a name of a file containing information in the active(5) format.
45 The getlist(1) utility may be used to obtain copy a remote system's
46 active file via its NNTP server, or an FTP client program can retrieve
47 such a file from an FTP archive (such as
48 ftp://ftp.isc.org/pub/usenet/CONFIG/active; see more about this below).
49 Newsgroup information from a file may be treated as if it was obtained
50 from a host. In this man page host1 and host2 are called hosts, even
51 though they may be file names.
52 If a host argument does not begin with ``.'' or ``/'', is assumed to
54 be a hostname or Internet address. In this case, actsync(8) will
55 attempt to use the NNTP protocol to obtain a copy of the the specified
56 system's active file. If the host argument contains a ``:'' , the
57 right side will be considerd the port to connect to on the remote sys‐
58 tem. If no port number is specified, actsync(8) will connect to port
59 119.
60 Regardless how the active file information is obtained, the actions of
62 actsync(8) remain the same.
63 If only one host is specified, it is assumed to be host2; if host1 is
65 not specified, it assumed to be the default local NNTP server as speci‐
66 fied by the NNTPSERVER environment variable, or by the server value
67 found in inn.conf.
68 The newsgroup synchronization, by default, involves all newsgroups
70 found on both hosts. One may also synchronize a subset of newsgroups
71 by directing actsync(8) to ignore certain newsgroups from both systems.
72 Only newsgroups with valid names will be synchronized. To be valid, a
73 newsgroup name must consist only of alphanumeric characters, ``.'',
74 ``+'', ``-'', and ``_''. One may not have two ``.''s in a row. The
75 first character must be alphanumeric, as must any character following a
76 ``.''. The name may not end in a ``.'' character.
77 The actsyncd(8) daemon provides a convenient interface to configure and
79 run actsync(8). If a host is not initially reachable, the daemon will
80 retry up to 9 additional times, waiting 6 minutes before each retry.
81 This daemon runs in the foreground, sending output to standard output
82 and standard error.
83 If the -x flag is given to actsyncd(8), then a ctlinnd xexec will be
85 used instead of a ctlinnd reload to load the newly modified active
86 file.
87 The configuration filename for the daemon is given as a commandline
89 argument, usually <pathetc in inn.conf>/actsync.cfg The config file can
90 contain the following options:
91 host=host2
93 ftppath=/remote/path/to/active/file
94 spool=<normally patharticles in inn.conf>
95 ignore_file=ignore_file
96 flags=[22mactsyncd(8) options
97 The host, ignore_file, and flags lines are mandatory.
99 The keyword must start at the beginning of the line, and there may be
101 no whitespace before the ``='' character. Blank lines are ignored.
102 Comment lines start with ``#'' and are ignored. Any other lines may
103 produce undefined results.
104 The host config file line refers to the host2 parameter to actsync(8).
106 The ftppath directive causes the machine named in the host line to
107 accessed as an ftp server, retrieving the file named. If the filename
108 ends in .gz or .Z, then it will automatically be uncompressed after
109 retrieval. The spool config file lines determines where the top of the
110 news spool tree is to be found. The ignore_file config file line names
111 the ignore file to be used by actsync(8). The flags config file line
112 contains any flags that you wish to pass to actsync(8).
113 Note that the -i ignore_file option and the -o format option should not
115 be given in the flags= line because they are automatically taken care
116 of by actsyncd(8).
117 INN is shipped with default values of ftp.isc.org for host and
119 /pub/usenet/CONFIG/active for ftppath. You can read about the policies
120 used for maintaining that active file at
121 ftp://ftp.isc.org/pub/usenet/CONFIG/README. Consider sychronizing from
122 this file on a daily basis by using cron(8).
123
125 The options to actsync(8) are as follows:
126 -A [22mactsync(8) tries to authenticate before issuing LIST command.
128 -b hostid
130 This flag causes actsync(8) to ignore newsgroups with
131 ``bork.bork.bork'' style names. That is, newsgroups whose last
132 3 components are identical. For example, the following news‐
133 groups have bork style names:
134 alt.helms.dork.dork.dork
136 alt.auto.accident.sue.sue.sue
137 alt.election.vote.vote.vote
138 The value hostid determines on which hosts this action is per‐
140 formed:
141 0 neither host
143 1 local default server
144 2 remove server
145 12 both servers
146 21 both servers
147 The default is -b 0; no newsgroups are ignored because of bork-
149 style names.
150 -d hostid
152 This flag causes actsync(8) to ignore newsgroups that have all
153 numeric path components. The hostid value is interpreted the
154 same as in -b. For example, the following newsgroups have
155 numeric path components:
156 alt.prime.chongo.23209
158 391581.times.2.to_the.216193.power.-1
159 99.bottles.of.treacle.on.the.wall
160 linfield.class.envio_bio.101.d
161 The newsgroups directory of a newsgroups with a all numeric com‐
163 ponent could conflict with an article from another group if
164 stored using the ``tradspool'' storage method; see stor‐
165 age.conf(5). For example, the directory for the first newsgroup
166 listed above is the same path as article number 23209 from the
167 newsgroup:
168 alt.prime.chongo
170 The default is -d 0; all numeric newsgroups from both hosts will
172 be processed.
173 -g max Ignore any newsgroup with more than max levels. For example, -g
175 6 would ignore:
176 alt.feinstien.votes.to.trash.freedom.of.speech
178 alt.senator.exon.enemy.of.the.internet
179 alt.crypto.export.laws.dumb.dumb.dumb
180 but would not ignore:
182 alt.feinstien.acts.like.a.republican
184 alt.exon.amendment
185 alt.crypto.export.laws
186 If max is 0, then the max level feature is disabled.
188 By default, the max level feature is disabled.
190 -i ignore_file
192 The ignore_file , usually <pathetc in inn.conf>/actsync.ign ,
193 allows one to have a fine degree of control over which news‐
194 groups are ignored. It contains a set of rules that specifies
195 which newsgroups will be checked and which will be ignored.
196 By default, these rules apply to both hosts. This can be modi‐
198 fied by using the -I hostid flag.
199 By default, all newsgroups are checked. If no ignore_file if
201 specified, or if the ignore file contains no rule lines, all
202 newsgroups will be checked.
203 Blank lines and text after a ``#'' are considered comments and
205 are ignored.
206 Rule lines consist of tokens separated by whitespace. Rule
208 lines may be one of two forms:
209 c newsgroup [type ...]
211 i newsgroup [type ...]
212 If the rule begins with a c then the rule requests certain news‐
214 groups to be checked. If the rule begins with an i then the
215 rule requests certain newsgroups to be ignored. The newsgroup
216 field may be a specific newsgroup, or a uwildmat(3) pattern.
217 If one or more types are specified, then the rule applies to the
219 newsgroup only if is of the specified type. Types refer to the
220 4th field of the active file; that is, a type may be one of:
221 y
223 n
224 m
225 j
226 x
227 =group.name
228 Unlike active files, the group.name in an alias type may be a
230 newsgroup name or a uwildmat(3) pattern. Also, ``='' is equiva‐
231 lent to ``=*''.
232 On each rule line, no pattern type may not be repeated. For
234 example, one may not have more than one type that begins with
235 ``='', per line. However, one may achieve an effect equivalent
236 to using multiple ``='' types by using multiple rule lines
237 affecting the same newsgroup.
238 By default, all newsgroups are candidates to be checked. If an
240 ignore file is used, each newsgroup in turn is checked against
241 the ignore file. If multiple lines match a given newsgroup, the
242 last line in the ignore file is used.
243 For example, consider the following ignore file lines:
245 i *.general
247 c *.general m
248 i nsa.general
249 The newsgroups ba.general and mod.general would be synchronized
251 if moderated and ignored if not moderated. The newsgroup
252 nsa.general would be ignored regardless of moderation status.
253 All newsgroups not matching *.general would be synchronized by
254 default.
255 -I hostid
257 This flag restricts which hosts are affected by the ignore file.
258 The hostid value is interpreted the same as in -b described
259 above.
260 This flag may be useful in conjunction with the -m merge flag.
262 For example:
263 actsync -i actsync.ign -I 2 -m host1 host2
265 will keep all newsgroups currently on host1 . It will also will
267 only compare host1 groups with non-ignored newsgroups from host2
268 .
269 The default is -I 12, newsgroups from both hosts to be ignored
271 per the -i actsync.ign file.
272 -k By default, any newsgroup on host1 that is in error will be con‐
274 sidered for removal. This causes actsync(8) simply ignore such
275 newsgroups. This flag, used in combination with -m , will pre‐
276 vent any newsgroup from being scheduled for removal.
277 -l hostid
279 This flag causes ``problem newsgroups'' of type ``='' from host1
280 or host2 to be considered as errors. The hostid value is inter‐
281 preted the same as in -b. Newsgroups of type ``='' are news‐
282 groups active entries that have 4th field that begins with
283 ``='', i.e. newsgroups that are equivalent to other newsgroups.
284 A ``problem'' newsgroup is one which is:
285 * equivalent to itself
287 * in an equivalence chain that loops around
288 to itself
289 * in an equivalence chain longer than 16 groups
290 * equivalent to a non-existant newsgroup
291 * equivalent to a newsgroup that has an error
292 of some kind
293 However, a newsgroup that is equivalent to an ignored newsgroup
295 is not a problem.
296 By default, problem newsgroups from both hosts are marked as
298 errors.
299 -m Merge newsgroups instead of sync. By default, if a newsgroup
301 exists on host1 but not host2, it will be scheduled to be
302 removed. This flag disables this process, permitting newsgroups
303 unique to host1 to be kept.
304 -n name
306 The ctlinnd(8) command is used to create newsgroups as neces‐
307 sary. By default, the creator name used is actsync. This flag
308 changes the creator name to name.
309 -o fmt
311 Determine the output / action format of this utility. The fmt
312 may one of:
313 a output in active(5) format
315 a1 output in active(5) format,
316 and output host1 non-error ignored groups
317 ak output in active(5) format, but use host2
318 hi & low (2nd & 3rd active fields) values
319 for any newsgroup being created
320 aK output in active(5) format, but use host2
321 hi & low (2nd & 3rd active fields) values
322 for all newsgroups found in host2
323 a1k output in active(5) format, but use host2
324 hi & low (2nd & 3rd active fields) values
325 for any newsgroup being created,
326 and output host1 non-error ignored groups
327 a1K output in active(5) format, but use host2
328 hi & low (2nd & 3rd active fields) values
329 for all newsgroups found in host2,
330 and output host1 non-error ignored groups
331 ak1 same as a1k
332 aK1 same as a1K
333 c output in ctlinnd(8) format
334 x no output, directly exec ctlinnd(8) commands
335 xi no output, directly exec ctlinnd(8) commands,
336 in an interactive mode
337 The a, a1, ak, aK, a1k, a1K, ak1 and aK1 style formats allow one
339 to form a new active file instead of producing ctlinnd(8) com‐
340 mands. They use hi & low values of 0000000000 and 0000000001
341 respectively for newsgroups that are created. The ak and aK
342 variants change the the hi & low (2nd & 3rd active fields). In
343 the case of ak, newsgroups created take their hi & low values
344 from host2. In the case of aK, all newsgroups found on host2
345 take their hi & low values from host2.
346 The c format produces ctlinnd(8) commands. No actions are taken
348 because actsync(8) simply prints ctlinnd(8) commands on standard
349 output. The sync (or merge) with host2 may be accomplished by
350 piping this output into sh(1). A paranoid person might prefer
351 to use x or xi in case a newsgroup name or type contains bogus
352 characters that might be interpreted by sh(1). Even so, this
353 output format is useful to let you see how host1 will be
354 affected by the sync (or merge) with host2.
355 The sync (or merge) may be accomplished directly by use of the x
357 format. With this format, actsync(8) uses the execl(2) system
358 call to directly execute ctlinnd(8) commands. Because of the
359 exec, there is no risk of bogus newsgroups containing bogus
360 characters causing a shell to do bogus (or dangerous) things.
361 The output of such exec calls may be seen if the verbosity level
362 is at least 2.
363 The actsync(8) utility will pause for 4 seconds before each com‐
365 mand is executed if -o x is selected. See the -z sec flag below
366 for discussion of this delay and how to customize it.
367 The xi format interactively prompts on standard output and reads
369 directives on standard input. One may pick and choose changes
370 using this format.
371 Care should be taken when producing active(5) formatted output.
373 One should check to be sure that actsync(8) exited with a zero
374 status prior to using such output. Also one should realize that
375 such output will not contain lines ignored due to -i ignore_file
376 even if -p 100 is used.
377 By default, -o c is assumed.
379 -p min_%_unchg
381 By default, the actsync(8) utility has safeguards against per‐
382 forming massive changes. If fewer than min_%_unchg percent of
383 the non-ignored lines from host1 remain unchanged, no actions
384 (output, execution, etc.) are performed and actsync(8) exits
385 with a non-zero exit status. The min_%_unchg may be a floating
386 point value such as 66.667.
387 A change is considered a host1 line that was removed, added,
389 changed, or found to be in error. Changing the 2nd or 3rd
390 active fields via -oak or -o aK are not considered changes by
391 -p.
392 To force actsync(8) to accept any amount of change, use the -p 0
394 option. To force actsync(8) to reject any changes, use the -p
395 100 option.
396 Care should be taken when producing active(5)-formatted output;
398 be sure to check that actsync(8) exited with a zero status prior
399 to using such output. Also one should realize that such output
400 will not contain lines ignored by the -i ignore_file process
401 even if -p 100 is used.
402 By default, 96% of the lines not ignored in host1 must be
404 unchanged. That is, by default, -p 96 is assumed.
405 -q hostid
407 By default, all newsgroup errors are reported on standard error.
408 This flag quiets errors from host1 or host2. The hostid value
409 is interpreted the same as in -b.
410 -s size
412 If size > 0, then ignore newsgroups with names longer than size,
413 and ignore newsgroups equivalent (by following ``='' chains) to
414 names longer than size. Length checking is performed on both
415 the local and remote hosts.
416 By default, size is 0 and thus no length checking is performed.
418 -t hostid
420 Ignore improper newsgroups consisting of only a top component
421 from host1 or host2. The hostid value is interpreted the same
422 as in -b. The following newsgroups are considered proper news‐
423 groups despite top only names and therefore are exempt from this
424 flag:
425 control
427 general
428 junk
429 test
430 to
431 For example, the following newsgroup names are improper because
433 they only contain a top level component:
434 dole_for_pres
436 dos
437 microsoft
438 windows95
439 The default is -t 2, that is, all improper top-level-only news‐
441 groups from the remote are ignored.
442 -T This flag causes host2 newsgroups from new hierarchies to be
444 ignored. Normally a newsgroup which only exists on host2 , for
445 example chongo.was.here , will be created for host1. However,
446 if this flag is given and host1 does not have any other news‐
447 groups in the same hierarchy, e.g. ``chongo.*'', then the news‐
448 group in question will be ignored and will not be created on
449 host1.
450 -v verbosity
452 By default, actsync(8) is not verbose. This flag controls the
453 verbosity level as follows:
454 0 no debug or status reports (default)
456 1 print summary,
457 but only if work was needed or done
458 2 print actions, exec output, and summary,
459 but only if work was needed or done
460 3 print actions, exec output, and summary
461 4 full debug output
462 -z sec If -o x is selected, actsync(8) will pause for sec seconds
464 before each command is executed. This helps prevent innd(8)
465 from being busied-out if a large number of ctlinnd(8) commands
466 are needed. One can entirely disable this sleeping by using -z
467 0.
468 By default, actsync(8) will pause for 4 seconds before each com‐
470 mand is executed if -o x is selected.
471
473 Determine the difference (but don't change anything) between your news‐
474 group set and uunet's set:
475 actsync news.uu.net
477 Same as above, with full debug and progress reports:
479 actsync -v 4 news.uu.net
481 Force a site to have the same newsgroups some other site:
483 actsync -o x master
485 This may be useful to sync a slave site to its master, or to sync
487 internal site to a gateway.
488 Compare your site with uunet, disregarding local groups and certain
490 local differences with uunet. Produce a report if any differences were
491 encountered:
492 actsync -v 2 -i actsync.ign news.uu.net
494 where actsync.ign contains:
496 # Don't compare to.* groups as they will differ.
498 #
499 i to.*
500 # These are our local groups that nobody else
502 # (should) carry. So ignore them for the sake
503 # of the compare.
504 #
505 i nsa.*
506 # These groups are local favorites, so keep them
508 # even if uunet does not carry them.
509 #
510 i ca.dump.bob.dorman
511 i ca.keep.bob.dorman
512 i alt.tv.dinosaurs.barney.die.die.die
513 i alt.tv.dinosaurs.barney.love.love.love
514 i alt.sounds.* =alt.binaries.sounds.*
515 To interactively sync against news.uu.net, using the same ignore file:
517 actsync -o xi -v 2 -i actsync.ign news.uu.net
519 Based on newsgroups that you decided to keep, one could make changes to
521 the actsync.ign file:
522 # Don't compare to.* groups as they will differ.
524 #
525 i to.*
526 # These are our local groups that nobody else
528 # (should) carry. So ignore them for the sake
529 # of the compare.
530 #
531 i nsa.*
532 # These groups are local favorites, so keep them
534 # even if uunet does not carry them.
535 #
536 i ca.dump.bob.dorman
537 i alt.tv.dinosaurs.barney.die.die.die
538 i alt.sounds.* =alt.binaries.sounds.*
539 # Don't sync test groups, except for ones that are
541 # moderated or that are under the gnu hierarchy.
542 i *.test
543 c *.test m # check moderated test groups
544 c gnu.*.test
545 c gnu.test # just in case it ever exists
546 Automatic processing may be setup by using the following actsync.cfg
548 file:
549 # host to sync off of (host2)
551 host=news.uu.net
552 # location of the ignore file
554 ignore_file=<pathetc in inn.conf>/actsync.ign
555 # where news articles are kept
557 spool=<patharticles in inn.conf>
558 # actsync(8) flags
560 #
561 # Automatic execs, report if something was done,
562 # otherwise don't say anything, don't report
563 # uunet active file problems, just ignore
564 # the affected entries.
565 flags=-o x -v 2 -q 2
566 and then by running actsyncd(8) with the path to the config file:
568 actsyncd <pathetc in inn.conf>/actsync.cfg
570 One may produce a trial actsyncd(8) run without changing anything on
572 the server by supplying the debug_level arg:
573 actsyncd <pathetc in inn.conf>/actsync.cfg 2
575 The debug_level causes actsyncd(8) to run actsync(8) with an -v
577 debug_level (overriding any -v flag on the flags line), not make any
578 changes to the active file, write a new active file to standard output,
579 and write debug messages to standard error.
580 If the debug_outfmt arg is also given to actsyncd(8) then the data
582 written to standard output will be in -o debug_outfmt instead of in -o
583 a1 format. The /bin/sh command
584 actsyncd <pathetc in inn.conf>/actsync.cfg 4 \
586 >cmd.log 2>dbg.log
587 will operate in debug mode, not change the active file, write
589 ctlinnd(8) style commands to cmd.log, and write debug statements to
590 dbg.log.
591 To check only the major hierarchies against news.uu,net, use the fol‐
593 lowing actsync.ign file:
594 # by default, ignore everything
596 i *
597 # check the major groups
599 c comp.*
600 c gnu.*
601 c sci.*
602 c alt.*
603 c misc.*
604 c news.*
605 c rec.*
606 c soc.*
607 c talk.*
608 and the command:
610 actsync -i actsync.ign news.uu.net
612 To determine the differences between your old active and your current
614 default server:
615 actsync <pathetc in inn.conf>/active.old -
617 To report but not fix any newsgroup problems with the current active
619 file:
620 actsync - -
622 To detect any newsgroup errors on your local server, and to remove any
624 *.bork.bork.bork style silly newsgroup names:
625 actsync -b 2 - -
627 The active file produced by:
629 actsync ...flags... -o x erehwon.honey.edu
631 or by:
633 actsync ...flags... -o c erehwon.honey.edu | sh
635 is effectively the same as the active file produced by:
637 ctlinnd pause 'running actsync'
639 rm -f active.new
640 actsync ...flags... -o a1 erehwon.honey.edu > active.new
641 rm -f active.old
642 ln active active.old
643 mv active.new active
644 ctlinnd reload active 'running actsync'
645 ctlinnd go 'running actsync'
646 It should be noted that the final method above, pausing the server and
648 simply replacing the active file, is faster.
649
651 Careless use of this tool may result in the unintended addition,
652 change, or removal of newsgroups. You should avoid using the x output
653 format until you are sure it will do what you want.
654
656 If a newsgroup appears multiple times, actsync(8) will treat all copies
657 as errors. However, if the group is marked for removal, only one
658 rmgroup will be issued.
659 The timeout for ctlinnd(8) commands is fixed at 30 seconds when running
661 in ``x'' or ``xi'' output format. Perhaps the timeout value should be
662 controlled via a command line option?
663
665 active(5),
666 simpleftp(1),
667 mod-active(8),
668 ctlinnd(8),
669 getlist(8),
670 inn.conf(5).
671
673 Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
674 Updated to support ftp fetching by David Lawrence <tale@isc.org>.
675 ACTSYNC(8)