chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / doc / man / expire.8
1 .\" $Revision: 5909 $
2 .TH EXPIRE 8
3 .SH NAME
4 expire \- Usenet article and history expiration program
5 .SH SYNOPSIS
6 .B expire
7 [
8 .BI \-d " dir"
9 ]
10 [
11 .BI \-f " file"
12 ]
13 [
14 .BI \-g " file"
15 ]
16 [
17 .BI \-h " file"
18 ]
19 [
20 .B \-i
21 ]
22 [
23 .B \-N
24 ]
25 [
26 .B \-n
27 ]
28 [
29 .B \-p
30 ]
31 [
32 .BI \-r " reason"
33 ]
34 [
35 .BI \-s " size"
36 ]
37 [
38 .B \-t
39 ]
40 [
41 .BI \-v " level"
42 ]
43 [
44 .BI \-w " number"
45 ]
46 [
47 .B \-x
48 ]
49 [
50 .BI \-z " file"
51 ]
52 [
53 .I expire.ctl
54 ]
55 .SH DESCRIPTION
56 .I Expire
57 scans the
58 .IR history (5)-format
59 text file
60 .I <pathdb in inn.conf>/history
61 and uses the information recorded in it to purge itself of old news articles.
62 Articles stored using a storage method that has self-expire
63 functionality are by default not affected by
64 .IR expire 's
65 primary behavior (but see the ``\fB\-N\fP'' flag to disable this).  In
66 this case,
67 .I expire.ctl
68 is ignored except ``/remember/'' line for that article;
69 .I expire
70 does still probe to see if the article still exists and purges the
71 relevant history and overview entries if appropriate.
72 However, if ``groupbaseexpiry'' in
73 .I inn.conf
74 is true,
75 .I expire
76 acts on all articles as specified by
77 .I expire.ctl
78 regardless of whether their storage methods have self-expire
79 functionality.  In this case, the ``\fB\-e\fP'', \&``\fB\-k\fP'',
80 ``\fB\-N\fP'', ``\fB\-p\fP'', ``\fB\-q\fP'', ``\fB\-w\fP'' and
81 ``\fB\-z\fP'' flags are ignored.
82 .PP
83 Note that
84 .I expire
85 never purges articles which do not match any entry in
86 .IR expire.ctl .
87 .SH OPTIONS
88 .TP
89 .B \-d dir
90 If the ``\fB\-d\fP'' flag is used, then the new history file and database is
91 created in the specified directory,
92 .IR dir .
93 This is useful when the filesystem does not have sufficient space to
94 hold both the old and new history files.
95 When this flag is used,
96 .I expire
97 leaves the server paused and creates a zero-length file named after the
98 new history file, with an extension of ``.done'' to indicate that
99 it has successfully completed the expiration.
100 The calling script should install the new history file and un-pause the server.
101 The ``\fB\-r\fP'' flag should be used with this flag.
102 .TP
103 .B \-f file
104 To specify an alternate history file, use the ``\fB\-f\fP'' flag.
105 This flag is valid when used with the ``\fB\-d\fP'', and the output will
106 be written to the specified file.
107 The default without ``\fB\-f\fP'' flag is ``history''.
108 .TP
109 .B \-g file
110 If the ``\fB\-g\fP'' flag is given, then a one-line summary equivalent to the
111 output of ``\fB\-v\fP 1'', except preceded by the current time, will be
112 appended to the specified
113 .IR file .
114 .TP
115 .B \-h file
116 To specify an alternate input text history file, use the ``\fB\-h\fP'' flag.
117 .I Expire
118 uses the old
119 .IR dbz (3)
120 database to determine the size of the new one.
121 (If ``\fB\-d\fP'' flag is not used, the output filename will be the same
122 as the input filename with an extension of ``.n''.)
123 The default without ``\fB\-h\fP'' flag is
124 .IR <pathdb\ in\ inn.conf>/history .
125 .TP
126 .B \-i
127 To ignore the old database, use the ``\fB\-i\fP'' flag.
128 .TP
129 .B \-N
130 The control file is normally ignored for articles in storage methods
131 which have self-expire functionality.
132 If the ``\fB\-N\fP'' flag is used,
133 .I expire
134 still uses the control file for these articles.
135 .TP
136 .B \-n
137 If
138 .I innd
139 is not running, use the ``\fB\-n\fP'' flag and
140 .I expire
141 will not send the ``pause'' or ``go'' commands.
142 (For more details on the commands, see
143 .IR ctlinnd (8)).
144 Note that
145 .I expire
146 only needs exclusive access for a very short time \(em long enough to see
147 if any new articles arrived since it first hit the end of the file, and to
148 rename the new files to the working files.
149 .TP
150 .B \-p
151 .I Expire
152 makes its decisions on the time the article arrived, as found in the
153 .I history
154 file.
155 This means articles are often kept a little longer than with other
156 expiration programs that base their decisions on the article's posting
157 date.
158 To use the article's posting date, use the ``\fB\-p\fP'' flag.
159 .TP
160 .B \-r reason
161 .I Expire
162 normally sends a ``pause'' command to the local
163 .IR innd (8)
164 daemon when it needs exclusive access to the history file, using
165 the string ``Expiring'' as the reason.
166 To give a different reason, use the ``\fB\-r\fP'' flag.
167 The process ID will be appended to the reason.
168 When
169 .I expire
170 is finished and the new history file is ready, it sends a ``go'' command.
171 See also the ``\fB\-n\fP'' flag.
172 .TP
173 .B \-s size
174 Optimize the new history database for approximately 
175 .I size
176 pairs (lines in
177 .IR history ).
178 Accurately specifying the size will create a more efficient database.
179 (The size should be the estimated eventual size of the file, typically
180 the size of the old file.)
181 .TP
182 .B \-t
183 If the ``\fB\-t\fP'' flag is used, then
184 .I expire
185 will generate a list of the tokens that should be removed on its
186 standard output, and the new history file will be left in
187 .IR history.n ,
188 .IR history.n.dir ,
189 .I history.n.index
190 and
191 .IR history.n.hash .
192 This flag be useful for debugging when used with the ``\fB\-n\fP''
193 flags.  Note that if the ``\fB\-f\fP'' flag is used, then the
194 name specified with that flag will be used instead of
195 .IR history .
196 .TP
197 .B \-v level
198 The ``\fB\-v\fP'' flag is used to increase the verbosity of the program,
199 generating messages to standard output.
200 The
201 .I level
202 should be a number, where higher numbers result in more output.
203 Level one will print totals of the various actions done (not valid if a
204 new history file is not written), level two will print a report on each
205 individual file, while level five results in multiple lines of output
206 for every history line processed.
207 .TP
208 .B \-w number
209 Use the ``\fB\-w\fP'' flag to ``warp'' time so that
210 .I expire
211 thinks it is running at some time other then the current time.
212 The value should be a signed floating point number indicating the number
213 of days to use as the offset.
214 .TP
215 .B \-x
216 If the ``\fB\-x\fP'' flag is used, then
217 .I expire
218 will not create any new history files.  This is most useful when combined
219 with the ``\fB\-n\fP'' and `\fB`\-t\fP'' flags to see how
220 different expiration policies would change the amount of disk space used.
221 .TP
222 .B \-z file
223 If the ``\fB\-z\fP'' flag is used, then articles are not removed, but their
224 names are appended to the specified
225 .IR file .
226 See the description of
227 .I delayrm
228 in
229 .IR news.daily (8).
230 .PP
231 If a filename is specified, it is taken as the control file and parsed
232 according to the rules in
233 .IR expire.ctl .
234 A single dash (``\-'') may be used to read the file from standard input.
235 If no file is specified, the file
236 .I <pathetc in inn.conf>/expire.ctl
237 is read.
238 .SH HISTORY
239 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
240 .de R$
241 This is revision \\$3, dated \\$4.
242 ..
243 .R$ $Id: expire.8 5909 2002-12-03 05:17:18Z vinocur $
244 .SH "SEE ALSO"
245 ctlinnd(8),
246 dbz(3),
247 expire.ctl(5),
248 history(5),
249 inn.conf(5),
250 innd(8),
251 inndcomm(3).