doc/pod/expire.ctl.pod

   1 =head1 NAME
   2
   3 expire.ctl - Configuration file for article expiration
   4
   5 =head1 DESCRIPTION
   6
   7 The file I<pathetc>/expire.ctl is the default configuration file for
   8 B<expire> and B<expireover>, which read it at start-up.  It serves two
   9 purposes:  it defines how long history entries for expired or rejected
  10 articles are remembered, and it determines how long articles stored on the
  11 server are retained.
  12
  13 Normally, if all of the storage methods used by the server are
  14 self-expiring (such as CNFS), all lines except the C</remember/> setting
  15 (described below) are ignored.  This can be changed with the B<-N> option
  16 to B<expire> or B<expireover>.
  17
  18 Black lines and lines beginning with a number sign (C<#>) are ignored.
  19 All other lines should be in one of two formats.  The order of the file is
  20 significant, and the last matching entry will be used.
  21
  22 The first format specifies how long to keep history entries for articles
  23 that aren't present in the news spool.  These are articles that have
  24 either already expired, or articles which the server rejected (when
  25 I<remembertrash> is set to true in F<inn.conf>).  There should be one and
  26 only one line in this format, which looks like:
  27
  28     /remember/:<days>
  29
  30 where <days> is a decimal number that specifies the minimum number of days
  31 a history record for a given message ID is retained, regardless of whether
  32 the article is present in the spool.  (History entries for articles still
  33 present in the spool are always retained.)
  34
  35 The primary reason to retain a record of old articles is in case a peer
  36 offers old articles that were previously accepted but have already
  37 expired.  Without a history record for such articles, the server would
  38 accept the article again and readers would see duplicate articles.
  39 Articles older than a certain number of days won't be accepted by the
  40 server at all (see I<artcutoff> in inn.conf(5) and the B<-c> flag in
  41 innd(8)), and this setting should probably match that time period (10 days
  42 by default) to ensure that the server never accepts duplicates.
  43
  44 Most of the lines in this file will be in the second format, which
  45 consists of either four or five colon-separated fields:
  46
  47     <pattern>:<flag>:<min>:<default>:<max>
  48
  49 if I<groupbaseexpiry> is true in F<inn.conf> (the default), and otherwise:
  50
  51     <classnum>:<min>:<default>:<max>
  52
  53 All lines must be in the correct format given the current setting of
  54 I<groupbaseexpiry>, and therefore the two formats cannot co-exist in the
  55 same file.
  56
  57 Normally, a rule matches a newsgroup through the combination of the
  58 <pattern> and <flag> fields.  <pattern> is a uwildmat(3)-style pattern,
  59 specifying the newsgroups to which the line is applied.  Note that the
  60 last matching entry will be used, so general patterns (such as defaults
  61 for all groups where <pattern> is C<*>) should appear at the beginning of
  62 the file before more specific settings.
  63
  64 The <flag> field can be used to further limit newsgroups to which the line
  65 applies, and should be chosen from the following set:
  66
  67     M   Only moderated groups
  68     U   Only unmoderated groups
  69     A   All groups
  70     X   Remove the article from all groups it appears in
  71
  72 One of M, U, or A must be specified.  X should be used in combination with
  73 one of the other letters, not by itself.
  74
  75 An expiration policy is applied to every article in a newsgroup it
  76 matches.  There is no way to set an expiration policy for articles
  77 crossposted to groups you don't carry that's different than other articles
  78 in the same group.  Normally, articles are not completely deleted until
  79 they expire out of every group to which they were posted, but if an
  80 article is expired following a rule where <flag> contains X, it is deleted
  81 out of all newsgroups to which it was posted immediately.
  82
  83 If I<groupbaseexpiry> is instead set to false, there is no <pattern> and
  84 <flag> field and the above does not apply.  Instead, there is a single
  85 <classnum> field, which is either a number matching the storage class
  86 number specified in F<storage.conf> or C<*> to specify a default for all
  87 storage classes.  All articles stored in a storage class will be expired
  88 following the instructions in the line with a matching <classnum>, and
  89 when articles are expired, they're always removed from all groups to which
  90 they were posted.
  91
  92 The remaining three fields are the same in either format, and are used to
  93 determine how long an article should be kept.  Each field should be either
  94 a decimal number of days (fractions like C<8.5> are allowed, but remember
  95 that articles are only removed when B<expire> or B<expireover> is run,
  96 normally once a day by B<news.daily>) or the word C<never>.
  97
  98 The middle field, <default>, will be used as the expiration period for
  99 most articles.  The other two fields, <min> and <max>, only come into
 100 play if the article requests a particular expiration date with an Expires
 101 header.  Articles with an Expires header will be expired at the date given
 102 in that header, subject to the constraints that they will be retained at
 103 least <min> days and no longer than <max> days.
 104
 105 If <min> is set to C<never>, no article matching that line will ever be
 106 expired.  If <default> is set to C<never>, no article matching that line
 107 without an explicit Expires header will ever be expired.  If <max> is
 108 set to C<never>, Expires headers will be honored no matter how far into
 109 the future they are.
 110
 111 One should think of the fields as a lower bound, the default, and an upper
 112 bound.  Since most articles do not have an Expires header, the second
 113 field is the most important and most commonly applied.
 114
 115 Articles that do not match any expiration rule will not be expired, but
 116 this is considered an error and will result in a warning.  There should
 117 always be a default line (a line with a <pattern> of C<*> and <flag> of
 118 C<A>, or a line with a <classnum> of C<*>), which can explicitly state
 119 that articles should never expire by default if that's the desired
 120 configuration.  The default line should generally be the first line of the
 121 file (except for C</remember/>) so that other expiration rules can
 122 override it.
 123
 124 It is often useful to honor the Expires header in articles, especially
 125 those in moderated groups.  To do this, set <min> to zero, <default> to
 126 whatever normal expiration you wish, and <max> to C<never> or some large
 127 number, like 365 days for a maximum article life of a year.
 128
 129 To ignore any Expires header, set all three fields to the same value.
 130
 131 =head1 EXAMPLES
 132
 133 When I<groupbaseexpiry> is true (the default):
 134
 135     # Keep expired article history for 10 days, matching artcutoff.
 136     /remember/:10
 137
 138     # Most articles stay for two weeks, ignoring Expires.
 139     *:A:14:14:14
 140
 141     # Accept Expires headers in moderated groups for up to a year and
 142     # retain moderated groups for a bit longer.
 143     *:M:1:30:365
 144
 145     # Keep local groups for a long time and local project groups forever.
 146     example.*:A:90:90:90
 147     example.project.*:A:never:never:never
 148
 149 When I<groupbaseexpiry> is false, for class-based expiration:
 150
 151     # Keep expired article history for 10 days, matching artcutoff.
 152     /remember/:10
 153
 154     # Set a default expiration of seven days.
 155     *:7:7:7
 156
 157     # Class 0 is retained for two weeks.
 158     0:14:14:14
 159
 160 =head1 HISTORY
 161
 162 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Converted to
 163 POD by Russ Allbery <rra@stanford.edu>.
 164
 165 $Id: expire.ctl.pod 7207 2005-04-11 18:18:40Z rra $
 166
 167 =head1 SEE ALSO
 168
 169 expire(8), expireover(8), inn.conf(5), innd(8), news.daily(8),
 170 storage.conf(5), uwildmat(3)
 171
 172 =cut