=head1 NAME

expire - Usenet article and history expiration program

=head1 SYNOPSIS

B<expire> [B<-iNnptx>] [B<-d> I<dir>] [B<-f> I<file>] [B<-g> I<file>]
[B<-h> I<file>] [B<-r> I<reason>] [B<-s> I<size>] [B<-v> I<level>]
[B<-w> I<number>] [B<-z> I<file>] [I<expire.ctl>]

=head1 DESCRIPTION

B<expire> scans the history database and uses the information recorded in it
to purge itself of old news articles.  Its behaviour depends on the setting of
I<groupbaseexpiry> in F<inn.conf>.

When I<groupbaseexpiry> is false, article expiration is primarily done by
B<expire> based on the expiration rules in F<expire.ctl> that match the
storage class of each article.  The articles and the history entries are
removed by B<expire>, and then B<expireover> does the additional cleanup of
removing the overview database entries.  History entries of expired articles
are removed only if they are older than the number of days specified in the
C</remember/> line in F<expire.ctl>.  Articles stored using a storage method
that has self-expire functionality like CNFS are by default not affected by
B<expire>'s primary behaviour (but see the B<-N> flag to disable this).

When I<groupbaseexpiry> is true, article expiration is primarily done by
B<expireover> based on the expiration rules in F<expire.ctl> that match
each newsgroup.  Articles are removed from the news spool by B<expireover>,
and then B<expire> does some additional cleanup to remove old history database
entries.

For articles in self-expiring storage methods when I<groupbaseexpiry> is
set to false in F<inn.conf> and the B<-N> flag is not given, or for I<all>
articles when I<groupbaseexpiry> is set to true, F<expire.ctl> is ignored
except the C</remember/> line; B<expire> then only probes to see if the
article still exists, and purges the relevant history entries if appropriate.

Regardless the setting of I<groupbaseexpiry>, B<expireover> should be run
along with B<expire>, usually via B<news.daily> out of cron.

Note that B<expire> never purges articles which do not match any entry
in F<expire.ctl>.

Also note that if I<groupbaseexpiry> is true, the server needs an overview
database in order to expire articles in storage backends that are not
self-expiring.  If you do not plan to have an overview database, it would then
be better to only use self-expiring backends like CNFS, as the history entries
will still get cleaned up by B<expire> when it detects that an article no
longer exists in that backend.

When the C<hissqlite> history method is in use, B<expire> updates the
history database in place instead of building a new file and swapping it.
It does not pause B<innd> (the two coordinate through the database).  The
B<-d> and B<-f> options, which write a rebuilt history to a side file, are
rejected; use B<-t> for a dry run (it reports what would be removed without
changing the history or the spool).  B<-x> on its own is also rejected,
because suppressing the history rewrite while still removing articles would
leave history entries for deleted articles.  See hissqlite(5).

=head1 OPTIONS

=over 4

=item B<-d> I<dir>

If the B<-d> flag is used with the C<hisv6> history method, then the new
F<history> file and database is created in the specified directory I<dir>.
This is useful when the filesystem does not have sufficient space to hold both
the old and new history files.  When this flag is used, B<expire> leaves the
server paused and creates a zero-length file named after the new history file,
with an extension of C<.done> to indicate that it has successfully completed
the expiration.  The calling script should install the new history file and
unpause the server.  The B<-r> flag should be used with this flag.

This option is not available with the C<hissqlite> history method.

=item B<-f> I<file>

To specify an alternate history file, use the B<-f> flag.  This flag is
valid when used with the B<-d> flag, and the output will be written
to the specified file.  The default without B<-f> is C<history>.

=item B<-g> I<file>

If the B<-g> flag is given, then a one-line summary equivalent to the
output of B<-v 1>, except preceded by the current time, will be appended
to the specified I<file>.

=item B<-h> I<file>

To specify an alternate input history database, use the B<-h> flag.  With a
C<hisv6> history method, B<expire> uses the old I<dbz> database to determine
the size of the new one.  (If the B<-d> flag is not used, the output filename
will be the same as the input filename with an extension of C<.n>.)

The default without the B<-h> flag is I<pathhistory>/F<history> for C<hisv6>
and I<pathhistory>/F<history.sqlite> for C<hissqlite>.

=item B<-i>

To ignore the old database for the computation of the estimated size of the
new C<hisv6> history database, use the B<-i> flag.

It has no effect with the C<hissqlite> history method.

=item B<-N>

The control file is normally ignored for articles in storage methods
which have self-expire functionality.  If the B<-N> flag is used,
B<expire> still uses the control file for these articles.

This parameter is only useful when I<groupbaseexpiry> is set to false in
F<inn.conf>.

=item B<-n>

If B<innd> is not running, use the B<-n> flag and B<expire> will not
send the C<pause> or C<go> commands.  (For more details on the commands,
see ctlinnd(8)).  Note that B<expire> only needs exclusive access for
a very short time S<-- long> enough to see if any new articles arrived
since it first hit the end of the file, and to rename the new files
to the working files.

This flag is only useful for the C<hisv6> history method as C<hissqlite> does
not need pausing B<innd>.

=item B<-p>

B<expire> makes its decisions on the time the article arrived, as found
in the F<history> file.  This means articles are often kept a little
longer than with other expiration programs that base their decisions
on the article's posting date.  To use the article's posting date,
use the B<-p> flag.

=item B<-r> I<reason>

B<expire> normally sends a C<pause> command to the local B<innd> daemon
when it needs exclusive access to the history database, using the string
C<Expiring> as the reason.  To give a different reason, use the B<-r> flag.
The process ID will be appended to the reason.  When B<expire> is finished
and the new history database is ready, it sends a C<go> command.  See
also the B<-n> flag.

This flag is only useful for the C<hisv6> history method as C<hissqlite> does
not need pausing B<innd>.

=item B<-s> I<size>

B<expire> determines the optimal size of the new C<hisv6> F<history> file from
the size of the old one.  In case you want to force a specific size, use this
flag to optimize the new history database for approximately I<size> key-value
pairs (i.e. lines in F<history>).  Accurately specifying the size will create
a more efficient database.  (The size should be the estimated eventual number
of articles, typically the size of the old F<history> file, in lines.)

It has no effect with the C<hissqlite> history method.

=item B<-t>

If the B<-t> flag is used, then B<expire> will generate a list of the tokens
that should be removed on its standard output.

With the C<hisv6> history method, the new F<history> file will be left in
F<history.n>, F<history.n.dir>, F<history.n.index> and F<history.n.hash>.
This flag is useful for debugging when used with the B<-n> flag.  Note that
if the B<-f> flag is used, then the name specified with that flag will be used
instead of F<history>.

With the C<hissqlite> history method, it acts as a dry run, reporting what
would be removed without changing the history database or the spool.

=item B<-v> I<level>

The B<-v> flag is used to increase the verbosity of the program, generating
messages to standard output.  The I<level> should be a number, where higher
numbers result in more output.  Level one will print totals of the various
actions done (not valid if a new history database is not written), level two
will print a report on each individual file, while level five results in
multiple lines of output for every history line processed.

=item B<-w> I<number>

Use the B<-w> flag to "warp" time so that B<expire> thinks it is running
at some time other than the current time.  The value should be a signed
floating point number indicating the number of days to use as the offset.

=item B<-x>

If the B<-x> flag is used, then B<expire> will not create any new C<hisv6>
history files.  This is most useful when combined with the B<-n> and B<-t>
flags to see how different expiration policies would change the amount of disk
space used.

This option is not available with the C<hissqlite> history method.

=item B<-z> I<file>

If the B<-z> flag is used, then articles are not removed, but their names
are appended to the specified I<file>.  See the description of B<delayrm>
in news.daily(8).  If a filename is specified, it is taken as the control
file and parsed according to the rules in F<expire.ctl>.  A single dash
(C<->) may be used to read the file from standard input.  If no file
is specified, the file I<pathetc>/expire.ctl is read.

=back

=head1 TOMBSTONE LOG

When I<expiretombstone> and I<groupbaseexpiry> are enabled in F<inn.conf>,
B<expire> consumes the per-cycle deletion log produced by B<expireover>,
B<innd>, and B<sm -r> (F<expireover.tombstone> and F<cancels.tombstone> log
files in I<pathdb>) so it can drop history entries for those articles without
doing a per-article C<SMretrieve(RETR_STAT)> syscall.  An empty tombstone is
treated as "no cancels this cycle" and the slow scan is skipped entirely.
See inn.conf(5) under I<expiretombstone> for the file lifecycle, locking
model, and recovery story.

=head1 HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Converted to
POD by Julien Elie.

=head1 SEE ALSO

ctlinnd(8), expire.ctl(5), expireover(8), hissqlite(5), history(5),
inn.conf(5), innd(8), libinn_dbz(3), libinn_inndcomm(3), news.daily(8).

=cut
