chiark / gitweb /
debugging for thing that crashed
[innduct.git] / 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)