home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / com / utils / trn / doc / mthreads.man next >
Encoding:
Text File  |  1992-08-08  |  11.7 KB  |  330 lines
  1.                 
  2.  
  3. MTHREADS(8)           MAINTENANCE COMMANDS            MTHREADS(8)
  4.  
  5.  
  6.  
  7. NAME
  8.      mthreads - threaded database manager for trn
  9.  
  10. SYNOPSIS
  11.      mthreads [-d[MM]] [-e[HHMM]] [-acDfknstvz] [hierarchy_list]
  12.  
  13. DESCRIPTION
  14.      Mthreads manages the thread  files  that  are  used  by  the
  15.      trn(1)  newsreader.  "Thread files" are used to store infor-
  16.      mation about the news articles and how they are all  related
  17.      to one another.
  18.  
  19.      Mthreads should be run periodically  to  update  the  thread
  20.      database  as new news arrives.  It can be run in single-pass
  21.      mode (out of cron), in daemon mode, or in a  combination  of
  22.      the  two.   A  site that gets its news feed during the night
  23.      may just want to run mthreads once a day  (trn  will  handle
  24.      any  local  postings  that show up between passes).  If more
  25.      processing is needed, either run mthreads more often or  run
  26.      it  in daemon mode.  In daemon mode, a background process is
  27.      forked off that wakes up every 10 minutes  (by  default)  to
  28.      check  if  the  active  file  has  been  updated.   When the
  29.      mthreads daemon is sleeping between passes, it  is  possible
  30.      to run an mthreads single pass.  This is often useful if you
  31.      wish to run an enhanced expire pass more  than  once  a  day
  32.      (see the -c and -e options).
  33.  
  34. INSTALLATION
  35.      Mthreads in installed in the RNLIB directory  chosen  during
  36.      configuration.   When  it is run for the first time, it will
  37.      automatically create a file  called  active2  in  the  MTLIB
  38.      directory.   This  file  is essentially a copy of the active
  39.      file that keeps the newsgroup totals from the  last  run  in
  40.      one place.  It is also used to choose which groups are to be
  41.      processed into  thread  files.   All  groups  start  out  as
  42.      "unthreaded" unless they are turned on with a command like:
  43.  
  44.           mthreads all
  45.  
  46.      which would create thread file  for  all  the  groups.   For
  47.      testing purposes it is a good idea to start out small with a
  48.      command like:
  49.  
  50.           mthreads news
  51.  
  52.      which would thread only the news hierarchy.  Thread process-
  53.      ing  can be turned on or off for individual groups or entire
  54.      hierarchies by specifying the groups in a syntax very  simi-
  55.      lar  to  that used in the sys file.  For example, to turn on
  56.      all of soc and talk except for talk.politics,  and  to  turn
  57.      off news.lists, use the following command once:
  58.  
  59.  
  60.  
  61.  
  62. Sun Release 4.1        Last change: LOCAL                       1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. MTHREADS(8)           MAINTENANCE COMMANDS            MTHREADS(8)
  70.  
  71.  
  72.  
  73.           mthreads soc,talk,!talk.politics,!news.lists
  74.  
  75.      If mthreads  complains  that  another  mthreads  process  is
  76.      already  running,  you  can  use the -c option to tell it to
  77.      continue trying to lock instead of giving up.
  78.  
  79.      Once all the desired groups are  turned  on,  the  hierarchy
  80.      list  should  be  omitted  to  allow mthreads to process all
  81.      enabled groups.  It can be  used,  however,  in  conjunction
  82.      with  the -a option to customize which new groups get turned
  83.      on as they are created.
  84.  
  85. LOGGING
  86.      As mthreads executes,  some  status  information  (including
  87.      error  messages)  is  placed in the file mt.log in the MTLIB
  88.      directory, unless you chose to use SYSLOG.  This  file  will
  89.      grow  without bounds, and should be scanned periodically for
  90.      errors, and trimmed in size when it grows  too  large.   See
  91.      the shell script mt.check for an mt.log maintainer that will
  92.      send mail if it finds database errors.
  93.  
  94. OPTIONS
  95.      -a   is used to automatically turn on thread processing  for
  96.           new  news groups as they are created.  When this option
  97.           is specified, the hierarchy list is used to limit which
  98.           new  groups get enabled (omitting the hierarchy list is
  99.           the same as specifying "all").  The default without  -a
  100.           is to leave new groups unthreaded.
  101.  
  102.      -c   will continue trying to lock the mthreads database  for
  103.           a single pass instead of giving up.  This is useful for
  104.           running special commands out of cron while an  mthreads
  105.           daemon is active.
  106.  
  107.      -D   specifies debug  processing.   Any  errors  encountered
  108.           reading a thread file will rename the offending file to
  109.           "bad.read".  Any errors detected while generating a new
  110.           thread  file  will  rename the file to "bad.write".  If
  111.           more than one 'D' is specified, each  group's  name  is
  112.           output into the log file before it is processed.
  113.  
  114.      -d   is used to specify  the  daemon  mode,  where  mthreads
  115.           forks  a background task that periodically wakes up and
  116.           checks for an  updated  active  file.   The  number  of
  117.           minutes  to  wait after the completion of the last pass
  118.           can be specified after the  '-d'  option  (e.g.  -d20),
  119.           otherwise it will default to 10 minutes.
  120.  
  121.      -e   tells mthreads to run an enhanced expiration  check  on
  122.           the database.  Without this option, only articles below
  123.           the minimum field in the active file are expired.  With
  124.           this  option,  mthreads  will periodically list all the
  125.  
  126.  
  127.  
  128. Sun Release 4.1        Last change: LOCAL                       2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. MTHREADS(8)           MAINTENANCE COMMANDS            MTHREADS(8)
  136.  
  137.  
  138.  
  139.           article numbers to see which ones actually  exist.   In
  140.           single-pass  mode  the  -e  option  always  affects the
  141.           current pass -- use it at lease once a day after expire
  142.           has  run.  In daemon mode, the -e option will cause one
  143.           pass a day to be the enhanced expire pass.  By default,
  144.           this  is  the  first time mthreads wakes up after 12:30
  145.           am.  If a different time is desired, it can  be  speci-
  146.           fied in the form HHMM (e.g. -e2359).
  147.  
  148.      -f   is used to force mthreads to open each and every thread
  149.           file  to  see which ones really need to be updated, not
  150.           just the ones that differ in  the  active/active2  com-
  151.           parison.   It  will  also  remove any extraneous thread
  152.           files from unthreaded groups (which should  only  occur
  153.           if  you manually change the active2 file).  This option
  154.           should only be used when manipulating the thread  files
  155.           in unorthodox ways.
  156.  
  157.      -k   can be used to terminate the currently running mthreads
  158.           daemon,  just as if it had received a terminate signal.
  159.           When this option is specified,  no  other  activity  is
  160.           performed.
  161.  
  162.      -n   tells mthreads that  no  actual  processing  of  thread
  163.           files  is  to  be  performed.  This can be used to just
  164.           adjust which groups are enabled, without actually doing
  165.           any of the processing right away.
  166.  
  167.      -s<usec>
  168.           tells mthreads to sleep for <usec> microseconds  before
  169.           processing  each  article.  This is useful if your NNTP
  170.           server cannot handle mthreads running  at  full  speed.
  171.           Using  -s  by itself will sleep for an entire second to
  172.           be compatible with older versions of mthreads.
  173.  
  174.      -t   is used to make mthreads update the  active.times  file
  175.           (as  specified during configuration) with new directory
  176.           names as they are encountered.  Don't use  this  option
  177.           if your news software maintains this file for you (as C
  178.           news does).
  179.  
  180.      -v   selects additional levels of verbosity in the log file.
  181.           The  default  (without -v) is to log mthread's startup,
  182.           the totals for each pass, and  major  database  errors.
  183.           Add  one -v to get extra reference line problems logged
  184.           into the file.  Add a second and a third for even  more
  185.           (useless?)  information.   A fourth will cause mthreads
  186.           to output each group's name into the log file before it
  187.           is processed.
  188.  
  189.      -z   tells mthreads to 'zap' any thread file it believes  to
  190.           be corrupt.  This will allow the file to be regenerated
  191.  
  192.  
  193.  
  194. Sun Release 4.1        Last change: LOCAL                       3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201. MTHREADS(8)           MAINTENANCE COMMANDS            MTHREADS(8)
  202.  
  203.  
  204.  
  205.           from scratch on the next pass.
  206.  
  207.      hierarchy_list
  208.           The hierarchy list is used to turn thread processing on
  209.           or  off  for the listed groups while limiting itself to
  210.           updating only the listed groups.  If specified with the
  211.           -a option, however, it only limits which new groups get
  212.           enabled.  The groups are specified  in  a  manner  very
  213.           similar  to  the  news  software's  sys  file:   "news"
  214.           matches all groups in news; "!news" excludes all groups
  215.           in news; "comp.all.ibm.pc,!comp.all.ibm.pc.all" matches
  216.           both comp.sys.ibm.pc and comp.binaries.ibm.pc, but  not
  217.           comp.binaries.ibm.pc.d.
  218.  
  219. OUTPUT
  220.      When mthreads is run in  single-pass  mode  it  generates  a
  221.      stream  a  status characters on stdout that present a visual
  222.      display of what is happening.  If single-pass mode  is  used
  223.      for  regular  processing,  this  output can be redirected to
  224.      /dev/null.
  225.  
  226.      The output definitions:
  227.           '.' = group's entry is up to date
  228.           ':' = group processed -- no change
  229.           '#' = group processed
  230.           '-' = group processed -- is now empty
  231.           'x' = group excluded in active
  232.           'X' = group excluded in active2
  233.           '*' = unable to access a group
  234.           '!' = write failed (bad news)
  235.           'e' = informational error
  236.           'E' = database-affecting error
  237.  
  238. CONFIGURATION
  239.      During the configuration of trn, a  choice  was  made  about
  240.      where  to place the thread data files.  They either exist as
  241.      a .thread file in each group's spool directory, or they  are
  242.      each  a  group.th  file  in a one-off directory structure on
  243.      another drive.  See the THREAD_DIR definition in config.h to
  244.      review or change this definition.
  245.  
  246. REBUILDING
  247.      If the thread files are ever removed, also remove  the  file
  248.      db.init  in  the  THREAD_DIR.   This file contains the byte-
  249.      order of the machine that generated the database, and  needs
  250.      to  be  removed to truly start from scratch.  An easy way to
  251.      get mthreads to remove all the files except for  db.init  is
  252.      to specify the command:
  253.  
  254.           mthreads !all
  255.  
  256.  
  257.  
  258.  
  259.  
  260. Sun Release 4.1        Last change: LOCAL                       4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267. MTHREADS(8)           MAINTENANCE COMMANDS            MTHREADS(8)
  268.  
  269.  
  270.  
  271.      This also turns off thread processing for all groups.
  272.  
  273. ERROR HANDLING
  274.      If the active2 file is removed  or  corrupted,  it  will  be
  275.      automatically  rebuilt  in  the  normal course of operation.
  276.      The record of which groups should be threaded will be  lost,
  277.      however.   Missing/corrupted  thread files are automatically
  278.      re-built.
  279.  
  280. EXAMPLES
  281.      Recommended commands to run on a regular basis are:
  282.  
  283.           mthreads -dave0630
  284.  
  285.      to start up an mthreads daemon in verbose logging mode  that
  286.      automatically  threads  new  groups and performs an extended
  287.      expire at 6:30 am, or:
  288.  
  289.           mthreads -e >/dev/null
  290.  
  291.      to run an mthreads single-pass  with  extended  expire  that
  292.      leaves new groups unthreaded.
  293.  
  294. FILES
  295.      /usr/lib/news/active
  296.      $MTLIB/active2
  297.      $MTLIB/mt.log
  298.      $THREAD_DIR/db.init
  299.      $MTLIB/LOCKmthreads
  300.      Lots of thread data files.
  301.  
  302. AUTHOR
  303.      Wayne Davison <davison@borland.com>
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326. Sun Release 4.1        Last change: LOCAL                       5
  327.  
  328.  
  329.  
  330.