ACTSYNC (8)

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=<config$_PATH_SPOOL>
           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.

You can find a summary and links related to this topic
as part of the Mib Software Usenet RKT.