ACTSYNC(8)



ACTSYNC(8)                InterNetNews Documentation                ACTSYNC(8)

NAME
       actsync, actsyncd - Synchronize newsgroups

SYNOPSIS
       actsync [-AkmT] [-b hostid] [-d hostid] [-g max] [-i ignore-file] [-I
       hostid] [-l hostid] [-n name] [-o format] [-p min-unchanged] [-q
       hostid] [-s size] [-t hostid] [-v verbosity] [-w seconds] [-z seconds]
       [host] host

       actsyncd config [debug-level [debug-format]]

DESCRIPTION
       actsync permits one to synchronize, compare, or merge two active files.
       With this utility one may add, change, or remove newsgroups on the
       local news server to make it similar to the list of the newsgroups
       found on another system or file.  The synchronization need not be
       exact.  Local differences in newsgroup lists may be maintained and
       preserved.  Certain newsgroup errors may be detected and optionally
       corrected.

       There are several reasons to run actsync (or actsyncd) on a periodic
       basis.  Among the reasons are:

       o A control message to add, change or remove a newsgroup may fail to
         reach your site.

       o Your control.ctl may be out of date or incomplete.

       o News articles for a new newsgroup may arrive ahead (sometimes days
         ahead) of the control message.

       o Control messages may be forged, thus bypassing the restrictions found
         in control.ctl unless you set up PGP authentication (and even then,
         not all hierarchies use PGP authentication).

       o Your active file may have been trashed.

       If either host argument begins with "." or "/", it is assumed to be the
       name of a file containing information in the active(5) format.  The
       getlist(1) utility may be used to obtain a copy of a remote system's
       active file via its NNTP server, or an FTP client program can retrieve
       such a file from an FTP archive (such as ftp.isc.org available in both
       FTP and HTTPS <https://ftp.isc.org/pub/usenet/CONFIG/active>; see more
       about this below).  Newsgroup information from a file may be treated as
       if it was obtained from a host.  In this man page, the host arguments
       on the command line are called hosts, even though they may be file
       names.

       If a host argument does not begin with "." or "/", it is assumed to be
       a hostname or Internet address.  In this case, actsync will attempt to
       use the NNTP protocol to obtain a copy of the specified system's active
       file.  If the host argument contains ":", the right side will be
       considered the port to connect to on the remote system.  If no port
       number is specified, actsync will connect to port 119.

       Regardless how the active file information is obtained, the actions of
       actsync remain the same.

       The first host specified is taken to be the local host, the one where
       any changes would be made.  The second host specified is the remote
       host that is being synchronized with.  If only one host is specified,
       it is assumed to be the remote host to synchronize with, and the local
       host is assumed to be the default local NNTP server as specified by the
       NNTPSERVER environment variable or by the server value found in
       inn.conf.

       If either host is specified as "-", the default server will be used for
       that host, determined as described above.

       The newsgroup synchronization, by default, involves all newsgroups
       found on both hosts.  One may also synchronize a subset of newsgroups
       by directing actsync to ignore certain newsgroups from both systems.
       Only newsgroups with valid names will be synchronized.  To be valid, a
       newsgroup name must consist only of alphanumeric characters, ".", "+",
       "-", and "_".  One may not have two "." characters in a row.  The first
       character must be alphanumeric, as must any character following ".".
       The name may not end in a "." character.

       The actsyncd daemon provides a convenient interface to configure and
       run actsync.  If a host is not initially reachable, the daemon will
       retry up to 9 additional times, waiting 6 minutes before each retry.
       This daemon runs in the foreground, sending output to standard output
       and standard error.  It then uses mod-active(8) to update the active
       file if there are commands for ctlinnd in its output.

       The configuration filename for the daemon is given as a command line
       argument, usually actsync.cfg in pathetc.  The config file can contain
       the following options:

           host=<host>
           ftppath=<path-to-active>
           ignore_file=<ignore-file>
           flags=<actsync-options>

       The host=, ignore_file=, and flags= lines are mandatory.  Each keyword
       must start at the beginning of the line, and there may be no whitespace
       before the "=" character.  Blank lines are ignored, as are comment
       lines that start with "#".  Any other lines may produce undefined
       results.

       The <host> setting refers to the second (remote) host parameter to
       actsync.  If <path-to-active> is provided, <host> is accessed as an FTP
       server, retrieving the file named.  If the filename ends in ".gz" or
       ".Z", it will be automatically uncompressed after retrieval.
       <ignore-file> names the ignore file used by actsync (the -i option).
       <actsync-options> contains any other flags that you wish to pass to
       actsync.

       Note that one should not include -i or -o options in the flags= line;
       they are automatically taken care of by actsyncd.

       One may produce a trial actsyncd run without changing anything on the
       server by supplying the debug-level argument:

           actsyncd <pathetc>/actsync.cfg 2

       The debug-level causes actsyncd to run actsync with a -v debug-level
       flag (overriding any -v flag on the flags= line), not make any changes
       to the active file, write a new active file to standard output, and
       write debug messages to standard error.

       If the debug-format argument is also given to actsyncd, the data
       written to standard output will be in -o debug-format instead of in "-o
       a1" format.

       INN comes with default values of "ftp.isc.org" for <host> and
       "/pub/usenet/CONFIG/active.gz" for <path-to-active>.  You can read
       about the policies used for maintaining that active file at
       <https://ftp.isc.org/pub/usenet/CONFIG/README>.  Consider synchronizing
       from this file on a daily basis by using cron.

OPTIONS
       actsync takes the following options.

       In all of the following options, the hostid parameter takes one of the
       following values:

           0    neither server
           1    local default server
           2    remote server
           12   both servers
           21   both servers

       In other words, 1 refers to the local host (the first host argument on
       the actsync command line) and 2 refers to the remote host (the second
       host argument, or the only one if only one is given).

       -A  actsync tries to authenticate before issuing the LIST command.

       -b hostid
           This flag causes actsync to ignore for synchronization purposes
           newsgroups with "bork.bork.bork"-style names (newsgroups whose last
           3 components are identical).  For example, the following newsgroups
           have bork-style names:

               alt.helms.dork.dork.dork
               alt.auto.accident.sue.sue.sue
               alt.election.vote.vote.vote

           The default is "-b 0"; no newsgroups are ignored because of bork-
           style names.

       -d hostid
           This flag causes actsync to ignore newsgroups that have all numeric
           path components.  For example, the following newsgroups have
           numeric path components:

               alt.prime.chongo.23209
               391581.times.2.to_the.216193.power.-1
               99.bottles.of.treacle.on.the.wall
               linfield.class.envio_bio.101.d

           The newsgroups directory of a newsgroup with a all numeric
           component could conflict with an article from another group if
           stored using the tradspool storage method; see storage.conf(5).
           For example, the directory for the first newsgroup listed above is
           the same path as article number 23209 from the newsgroup:

               alt.prime.chongo

           The default is "-d 0"; all numeric newsgroups from both hosts will
           be processed.

       -g max
           Ignore any newsgroup with more than max levels.  For example, "-g
           6" would ignore:

               alt.feinstien.votes.to.trash.freedom.of.speech
               alt.senator.exon.enemy.of.the.internet
               alt.crypto.export.laws.dumb.dumb.dumb

           but would not ignore:

               alt.feinstien.acts.like.a.republican
               alt.exon.amendment
               alt.crypto.export.laws

           If max is 0, then the max level feature is disabled.

           By default, the max level feature is disabled.

       -i ignore-file
           The ignore-file, usually actsync.ign in pathetc, allows one to have
           a fine degree of control over which newsgroups are ignored.  It
           contains a set of rules that specifies which newsgroups will be
           checked and which will be ignored.

           By default, these rules apply to both hosts.  This can be modified
           by using the -I flag.

           Blank lines and text after a "#" are considered comments and are
           ignored.

           Rule lines consist of tokens separated by whitespace.  Rule lines
           may be one of two forms:

               c <newsgroup> [<type> ...]
               i <newsgroup> [<type> ...]

           If the rule begins with a "c", the rule requests certain newsgroups
           to be checked.  If the rule begins with an "i", the rule requests
           certain newsgroups to be ignored.  The <newsgroup> field may be a
           specific newsgroup, or a uwildmat(3) pattern.

           If one or more <type>s are specified, then the rule applies to the
           newsgroup only if it is of the specified type.  Types refer to the
           4th field of the active file; that is, a type may be one of:

               y
               n
               m
               j
               x
               =group.name

           Unlike active files, the "group.name" in an alias type may be a
           newsgroup name or a uwildmat(3) pattern.  Also, "=" is equivalent
           to "=*".

           On each rule line, no pattern type may be repeated.  For example,
           one may not have more than one type that begins with "=", per line.
           However, one may achieve an effect equivalent to using multiple "="
           types by using multiple rule lines affecting the same newsgroup.

           By default, all newsgroups are candidates to be checked.  If no
           ignore-file is specified, or if the ignore file contains no rule
           lines, all newsgroups will be checked.  If an ignore file is used,
           each newsgroup in turn is checked against the ignore file.  If
           multiple lines match a given newsgroup, the last line in the ignore
           file is used.

           For example, consider the following ignore file lines:

               i *.general
               c *.general m
               i nsa.general

           The newsgroups ba.general and mod.general would be synchronized if
           moderated and ignored if not moderated.  The newsgroup nsa.general
           would be ignored regardless of moderation status.  All newsgroups
           not matching *.general would be synchronized by default.

       -I hostid
           This flag restricts which hosts are affected by the ignore file.
           This flag may be useful in conjunction with the -m flag.  For
           example:

               actsync -i actsync.ign -I 2 -m host1 host2

           will keep all newsgroups currently on host1.  It will also only
           compare host1 groups with non-ignored newsgroups from host2.

           The default is "-I 12"; newsgroups from both hosts are ignored per
           the file specified with -i.

       -k  By default, any newsgroup on the local host that has an invalid
           name will be considered for removal.  This causes actsync simply
           ignore such newsgroups.  This flag, used in combination with -m,
           will prevent any newsgroup from being scheduled for removal.

       -l hostid
           This flag causes problem newsgroups of type "=" to be considered as
           errors.  Newsgroups of type "=" are newsgroups active entries that
           have a fourth field that begins with "="; i.e., newsgroups that are
           aliased to other newsgroups.  A problem newsgroup is one for which
           one of the following is true:

           o Aliased to itself.

           o In an alias chain that loops around to itself.

           o In an alias chain longer than 16 groups.

           o Aliased to a non-existant newsgroup.

           o Aliased to a newsgroup that has an error of some kind.

           However, a newsgroup that is equivalent to an ignored newsgroup is
           not a problem.

           The default is "-l 12":  problem newsgroups from both hosts are
           marked as errors.

       -m  Merge newsgroups instead of sync.  By default, if a newsgroup
           exists on the local host but not the remote, it will be scheduled
           to be removed.  This flag disables this process, permitting
           newsgroups unique to the local host to be kept.

       -n name
           Depending on -o, the ctlinnd(8) command may be used to create
           newsgroups as necessary.  When this is done, the default creator
           name used is "actsync".  This flag changes the creator name to
           name.

       -o format
           Determine the output or action format of this utility.  format may
           be one of:

           a   Output in active(5) format.

           a1  Output in active(5) format and output non-error ignored groups
               from the local host.

           ak  Output in active(5) format, but use the high and low (2nd and
               3rd active fields) values from the remote host for any
               newsgroup being created.

           aK  Output in active(5) format, but use the high and low (2nd and
               3rd active fields) values from the remote host for all
               newsgroups found on that host.

           a1k Output in active(5) format, but use the high and low (2nd and
               3rd active fields) values from the remote host for any
               newsgroup being created and output non-error ignored groups
               from the local host.

           a1K Output in active(5) format, but use the high and low (2nd and
               3rd active fields) values from the remote host for all
               newsgroups found on that host and output non-error ignored
               groups from the local host.

           ak1 Same as "a1k".

           aK1 Same as "a1K".

           c   Output as commands to ctlinnd.

           x   No output.  Instead, directly run ctlinnd commands.

           xi  No output.  Instead, directly run ctlinnd commands in an
               interactive mode.

           The "a", "a1", "ak", "aK", "a1k", "a1K", "ak1", and "aK1" style
           formats allow one to format new active file instead of producing
           ctlinnd commands.  They use high and low values of 0000000000 and
           0000000001 respectively for newsgroups that are created unless
           otherwise specified.  The "ak" and "aK" variants change the high
           and low values (2nd and 3rd active fields).  In the case of "ak",
           newsgroups created take their high and low values from the remote
           host.  In the case of "aK", all newsgroups found on the remote host
           take their high and low values from it.

           The "c" format produces ctlinnd commands.  No actions are taken
           because actsync simply prints ctlinnd commands on standard output.
           This output format is useful to let you see how the local host will
           be affected by the sync (or merge) with the remote host.

           The sync (or merge) may be accomplished directly by use of the "x"
           or "xi" format.  With this format, actsync uses the execl(2) system
           call to directly execute ctlinnd commands.  The output of such exec
           calls may be seen if the verbosity level is at least 2.

           The actsync utility will pause for 4 seconds before each command is
           executed if "-o x" is selected.  See the -z flag below for
           discussion of this delay and how to customize it.

           The "xi" format interactively prompts on standard output and reads
           directives on standard input.  One may pick and choose changes
           using this format.

           Care should be taken when producing active(5) formatted output.
           One should check to be sure that actsync exited with a zero status
           prior to using such output.  Also one should realize that such
           output will not contain lines ignored due to -i even if "-p 100" is
           used.

           By default, "-o c" is assumed.

       -p min-unchanged
           By default, the actsync utility has safeguards against performing
           massive changes.  If fewer than min-unchanged percent of the non-
           ignored lines from the local host remain unchanged, no actions
           (output, execution, etc.) are performed and actsync exits with a
           non-zero exit status.  The min-unchanged value may be a floating
           point value such as 66.667.

           A change is a local newsgroup line that was removed, added,
           changed, or found to be in error.  Changing the 2nd or 3rd active
           fields via "-o ak" or "-o aK" are not considered changes by -p.

           To force actsync to accept any amount of change, use the "-p 0"
           option.  To force actsync to reject any changes, use the "-p 100"
           option.

           Care should be taken when producing active(5) formatted output.
           One should check to be sure that actsync exited with a zero status
           prior to using such output.  Also one should realize that such
           output will not contain lines ignored due to -i even if "-p 100" is
           used.

           By default, 96% of the lines not ignored in the first host argument
           on the actsync command line must be unchanged.  That is, by
           default, "-p 96" is assumed.

       -q hostid
           By default, all newsgroup errors are reported on standard error.
           This flag quiets errors from the specified hostid.

       -s size
           If size is greater than 0, then ignore newsgroups with names longer
           than size and ignore newsgroups aliased (by following "=" chains)
           to names longer than size.  Length checking is performed on both
           the local and remote hosts.

           By default, size is 0 and thus no length checking is performed.

       -t hostid
           Ignore improper newsgroups consisting of only a top component from
           the specified hostid.  The following newsgroups are considered
           proper newsgroups despite top only names and therefore are exempt
           from this flag:

               control
               general
               junk
               test
               to

           For example, the following newsgroup names are improper because
           they only contain a top level component:

               dole_for_pres
               dos
               microsoft
               windows95

           The default is "-t 2"; that is, all improper top-level-only
           newsgroups from the remote host are ignored.

       -T  This flag causes newsgroups on the remote host in new hierarchies
           to be ignored.  Normally a newsgroup which only exists on the
           remote host, chongo.was.here for example, is created on the local
           host.  However, if this flag is given and the local host does not
           have any other newsgroups in the same hierarchy (chongo.* in this
           case), the newsgroup in question will be ignored and will not be
           created on the local host.

       -v verbosity
           By default, actsync is not verbose.  This flag controls the
           verbosity level as follows:

           0 No debug or status reports (default).

           1 Print summary, but only if work was needed or done.

           2 Print actions, exec output, and summary, but only if work was
             needed or done.

           3 Print actions, exec output, and summary.

           4 Full debug output.

       -w seconds
           If "-o x" or "-o xi" is selected, ctlinnd will wait seconds seconds
           before timing out.  The default value is "-w 30".

       -z seconds
           If "-o x" is selected, actsync will pause for seconds seconds
           before each command is executed.  This helps prevent innd from
           being busied-out if a large number of ctlinnd commands are needed.
           One can entirely disable this sleeping by using "-z 0".

           By default, actsync will pause for 4 seconds before each command is
           executed if "-o x" is selected.

EXAMPLES
       Determine the difference (but don't change anything) between your
       newsgroup set and uunet's set:

           actsync news.uu.net

       Same as above, with full debug and progress reports:

           actsync -v 4 news.uu.net

       Force a site to have the same newsgroups as some other site:

           actsync -o x master

       This may be useful to sync a slave site to its master, or to sync
       internal site to a gateway.

       Compare your site with uunet, disregarding local groups and certain
       local differences with uunet.  Produce a report if any differences were
       encountered:

           actsync -v 2 -i actsync.ign news.uu.net

       where actsync.ign contains:

           # Don't compare to.* groups as they will differ.
           #
           i       to.*

           # These are our local groups that nobody else
           # (should) carry.  So ignore them for the sake
           # of the compare.
           #
           i       nsa.*

           # These groups are local favorites, so keep them
           # even if uunet does not carry them.
           #
           i       ca.dump.bob.dorman
           i       ca.keep.bob.dorman
           i       alt.tv.dinosaurs.barney.die.die.die
           i       alt.tv.dinosaurs.barney.love.love.love
           i       alt.sounds.*    =alt.binaries.sounds.*

       To interactively sync against news.uu.net, using the same ignore file:

           actsync -o xi -v 2 -i actsync.ign news.uu.net

       Based on newsgroups that you decided to keep, one could make changes to
       the actsync.ign file:

           # Don't compare to.* groups as they will differ.
           #
           i       to.*

           # These are our local groups that nobody else
           # (should) carry.  So ignore them for the sake
           # of the compare.
           #
           i       nsa.*

           # These groups are local favorites, so keep them
           # even if uunet does not carry them.
           #
           i       ca.dump.bob.dorman
           i       alt.tv.dinosaurs.barney.die.die.die
           i       alt.sounds.*    =alt.binaries.sounds.*

           # Don't sync test groups, except for ones that are
           # moderated or that are under the gnu hierarchy.
           #
           i       *.test
           c       *.test m        # check moderated test groups
           c       gnu.*.test
           c       gnu.test        # just in case it ever exists

       Automatic processing may be set up by using the following actsync.cfg
       file:

           # Host to sync off of (host2).
           host=news.uu.net

           # Location of the ignore file.
           ignore_file=<pathetc in inn.conf>/actsync.ign

           # Where news articles are kept.
           spool=<patharticles in inn.conf>

           # actsync(8) flags
           #
           # Automatic execs, report if something was done,
           # otherwise don't say anything, don't report
           # uunet active file problems, just ignore
           # the affected entries.
           flags=-o x -v 2 -q 2

       and then by running actsyncd with the path to the config file:

           actsyncd <pathetc>/actsync.cfg

       The command

           actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log

       will operate in debug mode, not change the active file, write ctlinnd
       style commands to cmd.log, and write debug statements to dbg.log.

       To check only the major hierarchies against news.uu,net, use the
       following actsync.ign file:

           # By default, ignore everything.
           #
           i       *

           # Check the major groups.
           #
           c       alt.*
           c       comp.*
           c       gnu.*
           c       humanities.*
           c       misc.*
           c       news.*
           c       rec.*
           c       sci.*
           c       soc.*
           c       talk.*

       and the command:

           actsync -i actsync.ign news.uu.net

       To determine the differences between your old active and your current
       default server:

           actsync <pathetc>/active.old -

       To report but not fix any newsgroup problems with the current active
       file:

           actsync - -

       To detect any newsgroup errors on your local server, and to remove any
       *.bork.bork.bork-style silly newsgroup names:

           actsync -b 2 - -

       The active file produced by:

           actsync <flags> -o x erehwon.honey.edu

       is effectively the same as the active file produced by:

           cd <pathdb>
           ctlinnd pause 'running actsync'
           rm -f active.new
           actsync <flags> -o a1 erehwon.honey.edu > active.new
           rm -f active.old
           ln active active.old
           mv active.new active
           ctlinnd reload active 'running actsync'
           ctlinnd go 'running actsync'

       It should be noted that the final method above, pausing the server and
       simply replacing the active file, may be faster if you are making lots
       of changes.

FILES
       pathbin/actsync
           The C program itself used to synchronize, compare, or merge two
           active files.

       pathbin/actsyncd
           The Shell daemon which provides a convenient interface to configure
           and run actsync.

       pathetc/actsync.cfg
           The configuration file which specifies the settings to use.

       pathetc/actsync.ign
           The ignore file which contains a set of synchronization rules that
           specifies which newsgroups will be checked and which will be
           ignored.

CAUTION
       Careless use of this tool may result in the unintended addition,
       change, or removal of newsgroups.  You should avoid using the "x"
       output format until you are sure it will do what you want.

BUGS
       If a newsgroup appears multiple times, actsync will treat all copies as
       errors.  However, if the group is marked for removal, only one rmgroup
       will be issued.

HISTORY
       Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.
       Updated to support FTP fetching by David Lawrence <tale@isc.org>.
       Converted to POD by Russ Allbery <eagle@eyrie.org>.

       $Id: actsync.pod 10097 2016-11-04 22:19:07Z iulius $

       By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).

       Copyright (c) Landon Curt Noll, 1993.  All rights reserved.

       Permission to use and modify is hereby granted so long as this notice
       remains.  Use at your own risk.  No warranty is implied.

SEE ALSO
       active(5), ctlinnd(8), getlist(8), inn.conf(5), mod-active(8),
       simpleftp(1).

INN 2.6.4                         2016-11-05                        ACTSYNC(8)

Man(1) output converted with man2html
list of all man pages