doc/man/expire.ctl.5

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "EXPIRE.CTL 5"
 132 .TH EXPIRE.CTL 5 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 expire.ctl \- Configuration file for article expiration
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 The file \fIpathetc\fR/expire.ctl is the default configuration file for
 138 \&\fBexpire\fR and \fBexpireover\fR, which read it at start\-up.  It serves two
 139 purposes:  it defines how long history entries for expired or rejected
 140 articles are remembered, and it determines how long articles stored on the
 141 server are retained.
 142 .PP
 143 Normally, if all of the storage methods used by the server are
 144 self-expiring (such as \s-1CNFS\s0), all lines except the \f(CW\*(C`/remember/\*(C'\fR setting
 145 (described below) are ignored.  This can be changed with the \fB\-N\fR option
 146 to \fBexpire\fR or \fBexpireover\fR.
 147 .PP
 148 Black lines and lines beginning with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored.
 149 All other lines should be in one of two formats.  The order of the file is
 150 significant, and the last matching entry will be used.
 151 .PP
 152 The first format specifies how long to keep history entries for articles
 153 that aren't present in the news spool.  These are articles that have
 154 either already expired, or articles which the server rejected (when
 155 \&\fIremembertrash\fR is set to true in \fIinn.conf\fR).  There should be one and
 156 only one line in this format, which looks like:
 157 .PP
 158 .Vb 1
 159 \&    /remember/:<days>
 160 .Ve
 161 .PP
 162 where <days> is a decimal number that specifies the minimum number of days
 163 a history record for a given message \s-1ID\s0 is retained, regardless of whether
 164 the article is present in the spool.  (History entries for articles still
 165 present in the spool are always retained.)
 166 .PP
 167 The primary reason to retain a record of old articles is in case a peer
 168 offers old articles that were previously accepted but have already
 169 expired.  Without a history record for such articles, the server would
 170 accept the article again and readers would see duplicate articles.
 171 Articles older than a certain number of days won't be accepted by the
 172 server at all (see \fIartcutoff\fR in \fIinn.conf\fR\|(5) and the \fB\-c\fR flag in
 173 \&\fIinnd\fR\|(8)), and this setting should probably match that time period (10 days
 174 by default) to ensure that the server never accepts duplicates.
 175 .PP
 176 Most of the lines in this file will be in the second format, which
 177 consists of either four or five colon-separated fields:
 178 .PP
 179 .Vb 1
 180 \&    <pattern>:<flag>:<min>:<default>:<max>
 181 .Ve
 182 .PP
 183 if \fIgroupbaseexpiry\fR is true in \fIinn.conf\fR (the default), and otherwise:
 184 .PP
 185 .Vb 1
 186 \&    <classnum>:<min>:<default>:<max>
 187 .Ve
 188 .PP
 189 All lines must be in the correct format given the current setting of
 190 \&\fIgroupbaseexpiry\fR, and therefore the two formats cannot co-exist in the
 191 same file.
 192 .PP
 193 Normally, a rule matches a newsgroup through the combination of the
 194 <pattern> and <flag> fields.  <pattern> is a \fIuwildmat\fR\|(3)\-style pattern,
 195 specifying the newsgroups to which the line is applied.  Note that the
 196 last matching entry will be used, so general patterns (such as defaults
 197 for all groups where <pattern> is \f(CW\*(C`*\*(C'\fR) should appear at the beginning of
 198 the file before more specific settings.
 199 .PP
 200 The <flag> field can be used to further limit newsgroups to which the line
 201 applies, and should be chosen from the following set:
 202 .PP
 203 .Vb 4
 204 \&    M   Only moderated groups
 205 \&    U   Only unmoderated groups
 206 \&    A   All groups
 207 \&    X   Remove the article from all groups it appears in
 208 .Ve
 209 .PP
 210 One of M, U, or A must be specified.  X should be used in combination with
 211 one of the other letters, not by itself.
 212 .PP
 213 An expiration policy is applied to every article in a newsgroup it
 214 matches.  There is no way to set an expiration policy for articles
 215 crossposted to groups you don't carry that's different than other articles
 216 in the same group.  Normally, articles are not completely deleted until
 217 they expire out of every group to which they were posted, but if an
 218 article is expired following a rule where <flag> contains X, it is deleted
 219 out of all newsgroups to which it was posted immediately.
 220 .PP
 221 If \fIgroupbaseexpiry\fR is instead set to false, there is no <pattern> and
 222 <flag> field and the above does not apply.  Instead, there is a single
 223 <classnum> field, which is either a number matching the storage class
 224 number specified in \fIstorage.conf\fR or \f(CW\*(C`*\*(C'\fR to specify a default for all
 225 storage classes.  All articles stored in a storage class will be expired
 226 following the instructions in the line with a matching <classnum>, and
 227 when articles are expired, they're always removed from all groups to which
 228 they were posted.
 229 .PP
 230 The remaining three fields are the same in either format, and are used to
 231 determine how long an article should be kept.  Each field should be either
 232 a decimal number of days (fractions like \f(CW8.5\fR are allowed, but remember
 233 that articles are only removed when \fBexpire\fR or \fBexpireover\fR is run,
 234 normally once a day by \fBnews.daily\fR) or the word \f(CW\*(C`never\*(C'\fR.
 235 .PP
 236 The middle field, <default>, will be used as the expiration period for
 237 most articles.  The other two fields, <min> and <max>, only come into
 238 play if the article requests a particular expiration date with an Expires
 239 header.  Articles with an Expires header will be expired at the date given
 240 in that header, subject to the constraints that they will be retained at
 241 least <min> days and no longer than <max> days.
 242 .PP
 243 If <min> is set to \f(CW\*(C`never\*(C'\fR, no article matching that line will ever be
 244 expired.  If <default> is set to \f(CW\*(C`never\*(C'\fR, no article matching that line
 245 without an explicit Expires header will ever be expired.  If <max> is
 246 set to \f(CW\*(C`never\*(C'\fR, Expires headers will be honored no matter how far into
 247 the future they are.
 248 .PP
 249 One should think of the fields as a lower bound, the default, and an upper
 250 bound.  Since most articles do not have an Expires header, the second
 251 field is the most important and most commonly applied.
 252 .PP
 253 Articles that do not match any expiration rule will not be expired, but
 254 this is considered an error and will result in a warning.  There should
 255 always be a default line (a line with a <pattern> of \f(CW\*(C`*\*(C'\fR and <flag> of
 256 \&\f(CW\*(C`A\*(C'\fR, or a line with a <classnum> of \f(CW\*(C`*\*(C'\fR), which can explicitly state
 257 that articles should never expire by default if that's the desired
 258 configuration.  The default line should generally be the first line of the
 259 file (except for \f(CW\*(C`/remember/\*(C'\fR) so that other expiration rules can
 260 override it.
 261 .PP
 262 It is often useful to honor the Expires header in articles, especially
 263 those in moderated groups.  To do this, set <min> to zero, <default> to
 264 whatever normal expiration you wish, and <max> to \f(CW\*(C`never\*(C'\fR or some large
 265 number, like 365 days for a maximum article life of a year.
 266 .PP
 267 To ignore any Expires header, set all three fields to the same value.
 268 .SH "EXAMPLES"
 269 .IX Header "EXAMPLES"
 270 When \fIgroupbaseexpiry\fR is true (the default):
 271 .PP
 272 .Vb 2
 273 \&    # Keep expired article history for 10 days, matching artcutoff.
 274 \&    /remember/:10
 275 .Ve
 276 .PP
 277 .Vb 2
 278 \&    # Most articles stay for two weeks, ignoring Expires.
 279 \&    *:A:14:14:14
 280 .Ve
 281 .PP
 282 .Vb 3
 283 \&    # Accept Expires headers in moderated groups for up to a year and
 284 \&    # retain moderated groups for a bit longer.
 285 \&    *:M:1:30:365
 286 .Ve
 287 .PP
 288 .Vb 3
 289 \&    # Keep local groups for a long time and local project groups forever.
 290 \&    example.*:A:90:90:90
 291 \&    example.project.*:A:never:never:never
 292 .Ve
 293 .PP
 294 When \fIgroupbaseexpiry\fR is false, for class-based expiration:
 295 .PP
 296 .Vb 2
 297 \&    # Keep expired article history for 10 days, matching artcutoff.
 298 \&    /remember/:10
 299 .Ve
 300 .PP
 301 .Vb 2
 302 \&    # Set a default expiration of seven days.
 303 \&    *:7:7:7
 304 .Ve
 305 .PP
 306 .Vb 2
 307 \&    # Class 0 is retained for two weeks.
 308 \&    0:14:14:14
 309 .Ve
 310 .SH "HISTORY"
 311 .IX Header "HISTORY"
 312 Written by Rich \f(CW$alz\fR <rsalz@uunet.uu.net> for InterNetNews.  Converted to
 313 \&\s-1POD\s0 by Russ Allbery <rra@stanford.edu>.
 314 .PP
 315 $Id: expire.ctl.5 7880 2008-06-16 20:37:13Z iulius $
 316 .SH "SEE ALSO"
 317 .IX Header "SEE ALSO"
 318 \&\fIexpire\fR\|(8), \fIexpireover\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInews.daily\fR\|(8),
 319 \&\fIstorage.conf\fR\|(5), \fIuwildmat\fR\|(3)