

EXPIRE(8)                  Unix Programmer's Manual                  EXPIRE(8)


NAME
     expire, doexpire - expire old news
     mkhistory - rebuild news history file
     upact - update news active file
     recovact - partially recover news active file

SYNOPSIS
     /usr/lib/newsbin/expire/expire [ -a archdir ] [ -p ] [ -s ] [ -F c ] [ -c
     ]  [  -n  nnnnn  ]  [  -t  ]  [ -l ] [ -v ] [ -d ] [ -r ] [ -g ] [ -h ] [
     controlfile ]
     /usr/lib/newsbin/expire/doexpire expireoptions
     /usr/lib/newsbin/expire/mkhistory
     /usr/lib/newsbin/expire/upact
     /usr/lib/newsbin/expire/recovact

DESCRIPTION
     Expire expires old news, removing it from  the  current-news  directories
     and (if asked to) archiving it elsewhere.  It updates news's history file
     to match.  Expire should normally be  run  nightly,  typically  by  using
     doexpire (see below).

     Expire's operations are controlled by a control file (which can be  named
     or  supplied  on  standard  input),  which is not optional----there is no
     default behavior.  Each line of the control file (except for empty  lines
     and  lines  starting with `#', which are ignored) should have four white-
     space-separated fields, as follows.

     The first field is one  or  more  newsgroups,  separated  by  commas  (no
     spaces!);  partial  specifications  are acceptable (e.g. `comp' specifies
     all groups with that prefix).

     The second field is one letter, `m', `u', or  `x',  specifying  that  the
     line  applies only to moderated groups, only to unmoderated groups, or to
     both, respectively.

     The third field specifies the expiry period in days.   The  most  general
     form  is  three numbers separated by dashes.  The units are days, decimal
     fractions are permitted, and ``never''  is  shorthand  for  an  extremely
     large  number.   The  first  number gives the retention period:  how long
     must pass after an article's arrival before it is a candidate for expiry.
     The  third  number  gives  the  purge  period:   how long must pass after
     arrival before the article will be expired unconditionally.   The  middle
     number  gives  the expiry period:  how long after an article's arrival it
     is expired by default.  An explicit  expiry  date  in  the  article  will
     override  the  expiry  period  but  not the retention period or the purge
     period.  If the field contains only two numbers with  a  dash  separating
     them,  the  retention period defaults to 0.  If the field contains only a
     number, the retention period defaults to 0 and the purge period  defaults
     to `never'.  (But see below.)  The retention period must be less than the
     purge period, and the expiry period must lie between them.

     The fourth field is an archiving directory, or `@' which  indicates  that
     the  default  archiving  directory  (see -a) should be used, or `-' which
     suppresses archiving.  An explicit archiving directory (not `@') prefixed
     with  `='  means  that  articles  should  be archived into that directory
     itself; normally they go into subdirectories under it by newsgroup  name,


C News                              15 Jan 1991                              1



EXPIRE(8)                  Unix Programmer's Manual                  EXPIRE(8)


     as  in  the  current-news  directory  tree.   (E.g.,   article   123   of
     comp.pc.drivel  being archived into archive directory /exp would normally
     become /exp/comp/pc/drivel/123, but if the archiving directory was  given
     as `=/exp' rather than `/exp', it would become /exp/123.)  Expire creates
     subdirectories under an archiving directory automatically, but  will  not
     create  the  archiving  directory  itself.  Archiving directories must be
     given as full pathnames.

     The first line of the control file which applies to a  given  article  is
     used  to  control  its  expiry.  It is an error for no line to apply; the
     last line should be something like `all\ x\ 7\ -' to ensure that at least
     one  line  is always applicable.  Cross-posted articles are treated as if
     they were independently posted to each group.

     The retention and purge defaults can be overridden by including a  bounds
     line, one with the special first field /bounds/.  The retention and purge
     defaults for following lines will be  those  of  the  bounds  line.   The
     defaults  ``stretch''  as  necessary  to  ensure that the purge period is
     never less than the expiry period  and  the  retention  period  is  never
     greater  than  the  expiry period.  The other fields of a bounds line are
     ignored but must be present.

     Entries in the history file can be retained after article expiry, to stop
     a  late-arriving  copy  of the article from being taken as a new article.
     To arrange this, include a line with the special first  field  /expired/;
     this   line   then  controls  the  expiry  of  history  lines  after  the
     corresponding articles expire.  Dates are  still  measured  from  article
     arrival,  not  expiry.   The  other fields of such a line are ignored but
     must be present.   It  is  strongly  recommended  that  such  a  line  be
     included, and that it specify as long a time as practical.

     Command-line options are:

     -a dir    dir is the default archiving directory; if no default is given,
               the  control  file  may  not  contain any `@' archive-directory
               fields.

     -p        print an `index' line for each archived article, containing its
               pathname, message ID, date received, and `Subject:' line.

     -s        space is tight;  optimize  error  recovery  to  minimize  space
               consumed rather than to leave as much evidence as possible.

     -F c      the subfield separator character in the middle history field is
               c rather than the normal `~'.

     -c        check the format and consistency of the control  file  and  the
               active file, but do not do any expiring.

     -n nnnnn  set expire's idea of the time to nnnnn (for testing).

     -t        print (on standard error) a  shell-script-like  description  of
               what  would  be  done,  but  don't  do  it.   In the absence of
               archiving, all output lines  will  be  of  the  form  ``remove\
               name'',  where  name is a pathname relative to /usr/spool/news.
               If an article is to be archived, this will be preceded (on  the


C News                              15 Jan 1991                              2



EXPIRE(8)                  Unix Programmer's Manual                  EXPIRE(8)


               same line) by ``copy\ name\ dir\ ;\ '', where  name  is  as  in
               remove  and  dir  is  an archiving directory (including any `='
               prefix) as specified by the control file or the -a option.

     -l        consider first filename in a history line to be the  leader  of
               its  line,  to  be  expired only after all others have expired.
               (Meant for use  on  obnoxious  systems  like  VMS  which  don't
               support real links.)

     -r        suppress  history  rebuild.   Mostly  for  emergencies.   (This
               leaves  the history file out of date and larger than necessary,
               but  improves  speed  and  eliminates  the  need  for   several
               megabytes of temporary storage.)

     -h        do not expire any article which would be archived  if  it  were
               expired.  Mostly for emergencies, so that expire can be run (to
               delete articles in non-archived groups) even if space is  short
               in archiving areas.

     -v        verbose:  report some statistics after termination.

     -g        report expiry dates that  getdate(3)  does  not  like.   Expire
               ignores  such  dates,  treating  the  article  as  if it had no
               explicit expiry date.

     -d        turn on (voluminous and cryptic) debugging output.

     Expire considers the middle field of a history line to consist of one  or
     more  subfields  separated  by `~'.  The first is the arrival date, which
     can be either a getdate(3)-readable date  or  a  decimal  seconds  count;
     expire  leaves this field unchanged.  The second----if present, non-null,
     and not `-'----is an explicit expiry date for the file, again  in  either
     format,  which  expire  will  convert  to  a  decimal seconds count as it
     regenerates the  history  file.   Subsequent  fields  are  preserved  but
     ignored.

     Doexpire checks whether another doexpire is running, checks that there is
     enough  disk  space, invokes expire with any expireoptions given and with
     /usr/lib/news/explist as the control file, and reports  any  difficulties
     by  sending  mail  to  usenet.   This is usually better than just running
     expire directly.  If  space  is  not  adequate  for  archiving,  doexpire
     reports  this  and invokes expire with the -h option.  If -r is not among
     the expireoptions, and disk space  is  persistently  inadequate  for  the
     temporaries  needed  for  history  rebuilding,  doexpire reports this and
     invokes expire with the -r option anyway.

     Mkhistory rebuilds the history file and  its  auxiliaries  to  match  the
     articles  in  /usr/spool/news.   Upact  updates  the  third fields of the
     active file to match the  articles  in  /usr/spool/news  (for  historical
     reasons, expire does not do this).  Recovact updates the second fields of
     the active file to match the articles  in  /usr/spool/news,  for  use  in
     disaster  recovery  based on an outdated active file.  These programs are
     all fairly slow and they all lock the whole news system for the  duration
     of the run, so they should not be run casually.




C News                              15 Jan 1991                              3



EXPIRE(8)                  Unix Programmer's Manual                  EXPIRE(8)


FILES
     /usr/lib/news/history       history file
     /usr/lib/news/history.pag   dbm database for history file
     /usr/lib/news/history.dir   dbm database for history file
     /usr/lib/news/explist       expiry control file
     /usr/lib/news/history.o     history file as of last expiry
     /usr/lib/news/history.n*    new history file and dbm files abuilding
     /usr/lib/news/LOCKexpire    doexpire's lock file
     /usr/lib/newsbin/expire/*   various auxiliaries

SEE ALSO
     inews(1), dbm(3), relaynews(8)

HISTORY
     Written at U of Toronto by Henry Spencer,  with  contributions  by  Geoff
     Collyer.

BUGS
     Archiving is always done by copying, never by linking.  This has the side
     effect  that  cross-posted  articles  are archived as several independent
     copies.

     The -p subject-finder botches continued header lines, as does  mkhistory,
     although such lines are rare.

     Upact is a distasteful kludge, but then, so is the  third  field  of  the
     active file.

     Upact forces the third field of the active  file  to  be  at  least  five
     digits,  for backward compatibility, but otherwise just makes it as large
     as necessary.  The group-creation operations always create it ten  digits
     long.   The  discrepancy  is harmless, since unlike the second field, the
     third field is never updated in place.

     One cannot put more than one newsgroup into a single archiving  directory
     with  the  `='  feature, since the article numbers will collide with each
     other and expire doesn't do anything about this.  Note that  archiving  a
     newsgroup  which  has  subgroups  into  an  `='  directory  puts  all the
     subgroups in the same directory as the parent!  (Specifying the group  as
     `foo.bar,!foo.bar.all' will avoid this.)

     Mkhistory is inherently incapable of  reconstructing  history-file  lines
     corresponding  to  expired  articles.   Protection  against  old articles
     reappearing is thus somewhat limited for a while after the  history  file
     is rebuilt.

     Expire uses access(2) to test for the presence of archiving  directories,
     which can cause anomalies if it is run setuid (normally it's not).










C News                              15 Jan 1991                              4

