Provided by: inn_1.7.2q-40build2_amd64 bug

NAME

       actsync, actsyncd - synchronize newsgroups

SYNOPSIS

       actsync [-b hostid] [-d hostid] [-g max] [-i ignore_file]
               [-I hostid] [-k] [-l hostid] [-m] [-n name]
               [-o fmt] [-p min_%_unchg] [-q hostid] [-s size]
               [-s spool_dir] [-t hostid] [-T] [-v verbose_lvl]
               [-z sec] [host1] host2

       actsyncd [-x] actsync.cfg [debug_level [debug_outfmt] ]

DESCRIPTION

       Actsync(8)  permits  one  to synchronize, compare or merge two active(5) files.  With this
       utility one may add, change or remove newsgroups on the  local  news  server  to  make  it
       similar  to  the list 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(8) (or actsyncd(8)), on a periodic basis.  Among
       the reasons are:

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

            Your control.ctl(5) is out of date or incomplete.

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

            Control   messages   may   be  forged,  thus  bypassing  the  restrictions  found  in
            control.ctl(5).

            Your active(5) file may have been trashed.

       If either host1 or host2 begin with a ``.''  or ``/'', then they assumed to be a name of a
       file  containing  information in the active(5) format.  The getlist(1) utility may be used
       to obtain copy a remote system's active file.  Newsgroup information from a  file  may  be
       treated  as  if  it was obtained from a host.  In this man page host1 and host2 are called
       hosts, even though they may be file names.

       If a host argument does not begin with ``.''  or ``/'', is assumed to  be  a  hostname  or
       Internet  address.   In  this  case,  actsync(8)  will attempt to use the NNTP protocol to
       obtain a copy of the the specified system's active file.

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

       If  only one host is specified, it is assumed to be host2.  If host1, is not specified, it
       assumed to be the default local NNTP server as specified  by  the  NNTPSERVER  environment
       variable, or by the server value found in inn.conf(5).

       The  newsgroup  synchronization  by  default, involves all newsgroups found on both hosts.
       One may also synchronize on a subset of  newsgroups  by  directing  actsync(8)  to  ignore
       certain newsgroups from both systems.

       The  actsyncd(8)  daemon  provides a convenient interface to configure and run actsync(8).
       If a host is not initially reachable, the daemon will thrice  retry  3  times,  waiting  5
       minutes  before each set of 3 retries.  This daemon runs in the foreground, sending output
       to standard output and standard error.

       If the -x flag is given to actsyncd(8), then a ctlinndxexec will  be  used  instead  of  a
       ctlinndreload to load the newly modified active file.

       The  configuration  filename  for  the  daemon  is given in the actsync.cfg argument.  The
       actsync.cfg file is required to have 4 lines:

            host=host2
            spool=/var/spool/news
            ignore_file=ignore_file
            flags=actsyncd (8) options

       The keyword must start at the beginning of the line, and there may be no whitespace before
       the ``='' character.  Blank lines are ignored.  Comments start with ``#'' and are ignored.
       All other lines may produce undefined results.

       The host config file line refers to the host2 value to sync off of.  The spool config file
       lines  determines  where  top  the news spool tree is to be found.  The ignore_file config
       file line names the ignore file to be used by actsync(8).   The  flags  config  file  line
       refers to all flags that you wish to pass to actsync(8).

       Note  that  the  -i  ignore_file  option, the -o format option and the -S spool_dir option
       should not be given in the flags= line because they are automatically  taken  care  of  by
       actsyncd(8).

OPTIONS

       The options to actsync(8) are as follows:

       -b hostid
              This  flag  causes  actsync(8)  to  ignore newsgroups with ``bork.bork.bork'' style
              names.  That is, 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 value hostid determines on which hosts this action is performed:

                   0    neither host
                   1    local default server
                   2    remove server
                   12   both servers
                   21   both servers

              The default is -b 0, no bork newsgroups are ignored.

       -d hostid
              This  flag  causes  actsync(8)  to  ignore  newsgroups  that  have all numeric path
              components.  The hostid value is interpreted the same as in -b.  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  newsgroups  with  a  all numeric component could
              conflict with an article from another group.  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.admendment
                   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 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
              hostid flag.

              By  default, all newsgroups are checked.  If no ignore_file if specified, or if the
              ignore file contains no rule lines, all newsgroups will be checked.

              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  then  the rule requests certain newsgroups to be
              checked.  If the rule begins with an i then the rule requests certain newsgroups to
              be  ignored.   The  newsgroup  field  may  be a specific newsgroup, or a wildmat(3)
              pattern.

              If one or more types are specified, then the rule applies to the newsgroup only  if
              is  of  the specified type.  Types refer to the 4th field of the active(5) file.  A
              type may be one of:

                   y
                   n
                   m
                   j
                   x
                   =group.name

              Unlike active files, the group.name  may  be  a  newsgroup  name  or  a  wildmat(3)
              pattern.  Also, ``='' is equivalent to ``=*''.

              For given rule line may, one may not repeat a given pattern type.  For example, one
              may not have more than one type that begins with ``='', per line.  However, one may
              achieve  the  effect  of  multiple ``='' types by using multiple rule lines for the
              same group.

              By default, all newsgroups are candidates to 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 newsgroup: ba.general would be ignored if it was not moderated.  The newsgroup:
              mod.general would be checked if it was moderated.  The newsgroup: nsa.general would
              be ignored even if it was moderated.

       -I hostid
              This flag restricts which hosts, the ignore file  applies.   The  hostid  value  is
              interpreted the same as in -b.

              This flag may be useful in conjustion with the -m merge flag.  For example:

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

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

              The default is -I 12, newsgroups from both hosts to be ignored per the  -I   hostid
              flag.

       -k     By default, any newsgroup on host1 that is in error will be considered for removal.
              This causes actsync(8) simply ignore such newsgroups.  This  flag,  in  combination
              with -m will prevent any newsgroup from being scheduled for removal.

       -l hostid
              Flag  problem  newsgroups  of type ``='' from host1 or host2 as errors.  The hostid
              value is interpreted the same as in -b.  Newsgroups of type  ``=''  are  newsgroups
              active  entries that have 4th field that begins with ``=''.  I.e., a newsgroup that
              is equivalent to another newsgroup.

              A newsgroup that is equivalent to itself, or that is in a  equivalence  chain  that
              loops around to itself is a problem.  A newsgroup that is in a chain that is longer
              than 16 is a problem group.  A newsgroup  that  is  equivalent  to  a  non-existent
              newsgroup  is a problem.  A newsgroup that is equivalent to a newsgroup that is has
              a error of some kind a problem.  However, a newsgroup  that  is  equivalent  to  an
              ignored newsgroup is not a problem.

              By default, problem newsgroups from both hosts are marked as errors.

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

       -n  name
              Newsgroups  that  are created, are created via the ctlinnd(8) command.  By default,
              the creator name used is actsync.  This flag changes the creator name to name.

       -o  fmt
              Determine the output / action format of this utility.  The fmt may one of:

                   a    output in active(5) format,
                   a1   output in active(5) format,
                            and output host1 non-error ignored groups
                   ak   output in active(5) format, but use host2
                            hi & low (2nd & 3rd active fields) values
                            for any newsgroup being created
                   aK   output in active(5) format, but use host2
                            hi & low (2nd & 3rd active fields) values
                            for all newsgroups found in host2
                   a1k  output in active(5) format, but use host2
                            hi & low (2nd & 3rd active fields) values
                            for any newsgroup being created,
                        and output host1 non-error ignored groups
                   a1K  output in active(5) format, but use host2
                            hi & low (2nd & 3rd active fields) values
                            for all newsgroups found in host2,
                        and output host1 non-error ignored groups
                   ak1  same as a1k
                   aK1  same as a1K
                   c    output in ctlinnd(8) format
                   x    no output, directly exec ctlinnd(8) commands
                   xi   no output, directly exec ctlinnd(8) commands,
                            in an interactive mode

              The a, a1, ak, aK, a1k, a1K, ak1 and aK1 style formats allow  one  to  form  a  new
              active  file instead of producing ctlinnd(8) commands.  They use hi & low values of
              0000000000 and 0000000001 respectively for newsgroups that are created.  The ak and
              aK  variants change the the hi & low (2nd & 3rd active fields).  In the case of ak,
              newsgroups created take their hi & low values from host2.  In the case of  aK,  all
              newsgroups found on host2 take their hi & low values from host2.

              The c format produces ctlinnd(8) commands.  No actions are taken because actsync(8)
              simply prints ctlinnd(8) commands on standard output.  The sync (or  merge  if  -m)
              with host2 may be accomplished by piping this output into sh(1).  A paranoid person
              might prefer to use x or xi in  case  a  newsgroup  name  or  type  contains  bogus
              characters  that  might  be  interpreted  by sh(1).  Even so, this output format is
              useful to let you see how host1 may be synced (or merge) with host2.

              The sync (or merge if -m) may be accomplished directly by use of the x.  With  this
              format,  actsync(8)  uses  the execl(2) system call to directly executes ctlinnd(8)
              commands.  Because of the exec, there is no risk  of  bogus  newsgroups  containing
              bogus  characters causing a shell to do bogus (or dangerous) things.  The output of
              such execs may be seen of the verbosity level is at least 2.

              The actsync(8) utility will pause for 4 seconds before each command is executed  if
              -o x is selected.  See the -z sec flag below.

              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(8) exited with a zero status prior to using such output.
              Also one should realize that such output will not contain lines ignored by  the  -i
              ignore_file process even if -p 100 is used.

              By default, -o c is assumed.

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

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

              To  force actsync(8) to accept any amount of change, use the -p 0 option.  To force
              actsync(8) 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(8) exited with a zero status prior to using such output.
              Also one should realize that such output will not contain lines ignored by  the  -i
              ignore_file process even if -p 100 is used.

              By  default,  96% of the lines not ignored in host1 must be unchanged.  That is, by
              default, -p 90 is assumed.

       -q hostid
              By default, all newsgroup errors are reported on standard errors.  This flag quiets
              errors from host1 or host2.  The hostid value is interpreted the same as in -b.

       -s size
              If  size>0,  then  ignore  newsgroups  with  names  longer  than  size,  and ignore
              newsgroups equivalenced to names longer than size.  Length checking is  perform  on
              both the local and remote hosts.

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

       -S spool_dir
              For each new newsgroup (i.e., selected groups found on host2 that were not found on
              host), the newsgroup directory under spool_dir will be examined.  If this newsgroup
              directory  exists, then the hi & low (2nd & 3rd active fields) values of the active
              entry will be changed to reflect the range articles found.

              This flag is only useful with -o a, -o a1, -o ak, -o aK, -o alk, -o alK, -o ak1  or
              -o  aK1.   The  -S  spool_dir  will override any hi & low (2nd & 3rd active fields)
              values that would normally have been used.  This is  an  important  and  very  much
              recommended  option as it will prevent article number collisions on newsgroups that
              have been removed previous but still have unexpired articles in them.

       -t hostid
              Ignore improper newsgroups with only a top component  from  host1  or  host2.   The
              hostid  value  is  interpreted  the  same  as  in -b.  The following newsgroups are
              considered proper newsgroups for top only names:

                   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
                   windoes95

              By  default,  all  improper  top level only newsgroups from the remote ( -t 2 ) are
              ignored.

       -T     This flag causes host2 newsgroups from new hierarchies to be ignored.  Normally  if
              only  host2  has  the  newsgroup chongo.was.here then it will be created for host1.
              However if host1 does not have any 'chongo.*' newsgroups and this  flag  is  given,
              then chongo.was.here will be ignored and will not be created on host1.

       -v verbose_lvl
              No  default,  actsync(8) is not verbose.  This flag controls the verbosity level as
              follows:

                   0    no debug or status reports (default)
                   1    print summary,
                            if work was needed or done
                   2    print actions, exec output & summary,
                            if work was needed or done
                   3    print actions, exec output & summary
                   4    full debug output

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

              By default, actsync(8) 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 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 setup by using the following actsync.cfg file:

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

            # location of the ignore file
            ignore_file=/usr/local/news/actsync.ign

            # where nwes articles are kept
            spool=/var/spool/news

            # 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 effect entries.
            flags=-o x -v 2 -q 2

       and then by running:

            actsyncd /usr/local/news/actsync.cfg

       One  may  produce  a  trial  actsyncd(8)  run  without  changing anything on the server by
       supplying the debug_level arg:

            actsyncd /usr/local/news/actsync.cfg 2

       The debug_level causes actsyncd(8) to run actsync(8) with an  -v  debug_level  (overriding
       any  -v  flag  on  the  flags line), prevents any changes from being made to the active(5)
       file, writes a new active file to standard output and writes debug  messages  to  standard
       error.

       If  the  debug_outfmt  arg  is also given to actsyncd(8) then the data written to standard
       output will be in -o fBdebug_outfmt instead of in -o a1  format.   The  following  /bin/sh
       command:

            actsyncd /usr/local/news/actsync.cfg 4 c >cmd 2>dbg

       Will operate in debug mode, not change the active(5) file, write ctlinnd(8) style commands
       to cmd and write debug statements to dbg.

       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    comp.*
            c    gnu.*
            c    sci.*
            c    alt.*
            c    misc.*
            c    news.*
            c    rec.*
            c    soc.*
            c    talk.*

       and running:

            actsync -i actsync.ign news.uu.net

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

            actsync /usr/local/news/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

       or by:

            actsync ... flags ... -o c erehwon.honey.edu | sh

       is effectively the same as the active file produced by:

            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 above 'pause', 'actsync', 'reload' and 'go' method is  faster.
       However,  in order to avoid article number collisions on newsgroups that have been removed
       previous but still have unexpired articles in them, it is very much recommended  that  the
       -S spool_dir be used with any of the -oa* flags.  Thus, a much better and safer version of
       the above would be:

            ctlinnd pause 'running actsync'
            rm -f active.new
            actsync ... flags ... -o a1 -S /var/spool/news 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'

       The above process is similar to what actsyncd(8) does by default.

CAUTION

       Careless use of this tool may result in the addition change or removal of newsgroups  that
       you  don't want.  You should avoid using the x output format until you are sure it will do
       what you want.

       A number of innd(8) servers will corrupt the  active  file  when  lots  of  newgroups  and
       rmgroups  are  performed.   This  is  not a actsync(8) bug, it is a server bug.  Using the
       pause, actsync, reload and go method noted  above  is  much  more  likely  to  avoid  this
       problem.

BUGS

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

       The timeout for ctlinnd(8) commands is fixed at 30 seconds when running in ``x'' or ``xi''
       output format.  Perhaps the timeout value should be controlled via a command line option?

SEE ALSO

       active(5),
       ctlinnd(8),
       getlist(8)

HISTORY

       Written by Landon Curt Noll <chongo@toad.com> for InterNetNews.

                                                                                       ACTSYNC(8)