1ACTSYNC(8)                InterNetNews Documentation                ACTSYNC(8)
2
3
4

NAME

6       actsync, actsyncd - Synchronize newsgroups
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

EXAMPLES

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

FILES

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

CAUTION

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

BUGS

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

HISTORY

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

SEE ALSO

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)
Impressum