doc/pod/expireover.pod

   1 =head1 NAME
   2
   3 expireover - Expire entries from the news overview database
   4
   5 =head1 SYNOPSIS
   6
   7 B<expireover> [B<-ekNpqs>] [B<-f> I<file>] [B<-w> I<offset>]
   8 [B<-z> I<rmfile>] [B<-Z> I<lowmarkfile>]
   9
  10 =head1 DESCRIPTION
  11
  12 B<expireover> expires old entries from the news overview database.  It
  13 reads in a list of newsgroups (by default from I<pathdb>/active, but a
  14 different file can be specified with the B<-f> option) and then removes
  15 from the overview database mentions of any articles that no longer exist
  16 in the news spool.
  17
  18 If I<groupbaseexpiry> in I<inn.conf> is true, B<expireover> also removes
  19 old articles from the news spool according to the expiration rules in
  20 F<expire.ctl>.  Otherwise it only removes overview entries for articles
  21 that have already been removed by some other process, and B<-e>, B<-k>,
  22 B<-N>, B<-p>, B<-q>, B<-w>, and B<-z> are all ignored.
  23
  24 When I<groupbaseexpiry> is set, the default behavior of B<expireover> is
  25 to remove the article from the spool once it expires out of all of the
  26 newsgroups to which it was crossposted.  The article is, however, removed
  27 from the overview database of each newsgroup as soon as it expires out of
  28 that individual newsgroup.  The effect is that an article crossposted to
  29 several groups will be removed from the overview database from each group
  30 one-by-one as its age passes the expiration threshold for that group as
  31 set in F<expire.ctl>, and then when it expires out of the last newsgroup,
  32 it will be deleted from the news spool.
  33
  34 Articles that are stored in self-expiring storage backends such as CNFS
  35 are normally treated differently and not expired until they expire out of
  36 the backend regardless of F<expire.ctl>.  See B<-N>, however.
  37
  38 By default, B<expireover> purges all overview information for newsgroups
  39 that have been removed from the server; this behavior is suppressed if
  40 B<-f> is given.
  41
  42 =head1 OPTIONS
  43
  44 =over 4
  45
  46 =item B<-e>
  47
  48 Remove articles from the news spool and all overview databases as soon as
  49 they expire out of any newsgroup to which they are posted, rather than
  50 retain them until they expire out of all newsgroups.  B<-e> and B<-k>
  51 cannot be used at the same time.  This flag is ignored if
  52 I<groupbaseexpiry> is false.
  53
  54 =item B<-f> I<file>
  55
  56 Use I<file> as the newsgroup list instead of I<pathdb>/active.  I<file>
  57 can be C<-> to indicate standard input.  Using this flag suppresses the
  58 normal purge of all overview information from newsgroups that have been
  59 removed from the server.
  60
  61 =item B<-k>
  62
  63 Retain all overview information for an article, as well as the article
  64 itself, until it expires out of all newsgroups to which it was posted.
  65 This can cause articles to stick around in a newsgroup for longer than the
  66 F<expire.ctl> rules indicate, when they're crossposted.  B<-e> and B<-k>
  67 cannot be used at the same time.  This flag is ignored if
  68 I<groupbaseexpiry> is false.
  69
  70 =item B<-N>
  71
  72 Apply F<expire.ctl> rules to expire articles even from storage methods
  73 that have self-expire functionality.  This may remove articles from
  74 self-expiring storage methods before the articles "naturally" expire.
  75 This flag is ignored if I<groupbaseexpiry> is false.
  76
  77 =item B<-p>
  78
  79 By default, B<expireover> bases decisions on whether to remove an article
  80 on the arrival time on the server.  This means that articles may be kept a
  81 little longer than if the decision were based on the article's posting
  82 date.  If this option is given, expiration decisions are based on the
  83 article posting date instead.  This flag is ignored if I<groupbaseexpiry>
  84 is false.
  85
  86 =item B<-q>
  87
  88 B<expireover> normally prints statistics at the end of the expiration
  89 process.  B<-q> suppresses this report.  This flag is ignored if
  90 I<groupbaseexpiry> is false.
  91
  92 =item B<-s>
  93
  94 B<expireover> normally only checks the existence of articles in the news
  95 spool if querying the storage method for that article to see if it still
  96 exists is considered "inexpensive."  To always check the existence of all
  97 articles regardless of how resource-intensive this may be, use the B<-s>
  98 flag.  See storage.conf(5) for more information about this metric.
  99
 100 =item B<-w> I<offset>
 101
 102 "Warps" time so that B<expireover> thinks that it's running at some time
 103 other than the current time.  This is occasionally useful to force groups
 104 to be expired or not expired without changing F<expire.ctl> for the expire
 105 run.  I<offset> should be a signed floating point number specifying the
 106 number of days difference from the current time to use as "now."  This
 107 flag is ignored if I<groupbaseexpiry> is false.
 108
 109 =item B<-z> I<rmfile>
 110
 111 Don't remove articles immediately but instead write the path to the
 112 article or the token of the article to I<rmfile>, which is suitable input
 113 for fastrm(1).  This can substantially speed up deletion of expired
 114 articles for those storage methods where each article is a single file
 115 (such as tradspool and timehash).  See the description of I<delayrm> in
 116 news.daily(8) for more details.  This flag is ignored if
 117 I<groupbaseexpiry> is false.
 118
 119 =item B<-Z> I<lowmarkfile>
 120
 121 Write the lowest article numbers for each newsgroup as it's expired to the
 122 specified file.  This file is then suitable for C<ctlinnd lowmark>.  See
 123 ctlinnd(8) for more information.
 124
 125 =back
 126
 127 =head1 EXAMPLES
 128
 129 Normally B<expireover> is invoked from news.daily(8), which handles such
 130 things as processing the I<rmfile> and I<lowmarkfile> if necessary.
 131 Sometimes it's convenient to manually expire a particular newsgroup,
 132 however.  This can be done with a command like:
 133
 134     echo example.test | expireover -f - -Z /usr/local/news/tmp/lowmark
 135     ctlinnd lowmark /usr/local/news/tmp/lowmark
 136
 137 This can be particularly useful if a lot of articles in a particular group
 138 have expired but the overview information is still present, causing some
 139 clients to see a lot of "this article may have been cancelled" messages
 140 when they first enter the newsgroup.
 141
 142 =head1 HISTORY
 143
 144 Written by Rob Robertson <rob@violet.berkeley.edu> and Rich $alz
 145 <rsalz@uunet.uu.net> (with help from Dave Lawrence <tale@uunet.uu.net>)
 146 for InterNetNews.
 147
 148 $Id: expireover.pod 5909 2002-12-03 05:17:18Z vinocur $
 149
 150 =head1 SEE ALSO
 151
 152 active(5), ctlinnd(8), expire(8), expire.ctl(5), inn.conf(5),
 153 news.daily(8).
 154
 155 =cut