=head1 NAME

expire.ctl - Configuration file for article expiration

=head1 DESCRIPTION

The file I<pathetc>/expire.ctl is the default configuration file for
B<expire> and B<expireover>, which read it at start-up.  It serves two
purposes: it defines how long history entries for expired or rejected
articles are remembered, and it determines how long articles stored on the
server are retained.

Normally, if all of the storage methods used by the server are
self-expiring (such as CNFS), all lines except the C</remember/> setting
(described below) are ignored.  This can be changed with the B<-N> option
to B<expire> or B<expireover>.

Blank lines and lines beginning with a number sign (C<#>) are ignored.
All other lines should be in one of two formats.  The order of the file is
significant, and the last matching entry will be used.

The first format specifies how long to keep history entries for articles
that aren't present in the news spool.  These are articles that have
either already expired, or articles which the server rejected (when
I<remembertrash> is set to true in F<inn.conf>).  There should be one and
only one line in this format, which looks like:

    /remember/:<days>

where <days> is a decimal number that specifies the minimum number of days
a history record for a given Message-ID is retained (from its original
posting time), regardless of whether the article is present in the spool.
(History entries for articles still present in the spool are always retained.)
Setting it to C<never> means history records will be retained forever, C<0>
means history records for articles not present in the spool will be purged
when expiry programs run.  (This is notably useful in the case you need
re-injecting articles no longer present in your news spool but considered as
duplicate, because still present in history: you'll have to set C</remember/>
to C<0>, run the B<expire> process for instance via B<news.daily> called with
the same parameters as in crontab plus C<notdaily>, and undo the change in
F<expire.ctl>.  All previously rejected or removed articles will then not be
considered as duplicate if their Message-ID is proposed.)

The primary reason to retain a record of old articles is in case a peer
offers old articles that were previously accepted but have already
expired.  Without a history record for such articles, the server would
accept the article again and readers would see duplicate articles.
Articles older than a certain number of days won't be accepted by the
server at all (see I<artcutoff> in inn.conf(5) and the B<-c> flag in
innd(8)), and this setting should probably match that time period
to ensure that the server never accepts duplicates.  As the default
value for I<artcutoff> is C<10> days, it means that C</remember/>
should be set to C<11> days in order to take into account articles
whose posting date is one day into the future.

Most of the lines in this file will be in the second format, which
consists of either four or five colon-separated fields:

    <pattern>:<flag>:<min>:<default>:<max>

if I<groupbaseexpiry> is true in F<inn.conf> (the default), and otherwise:

    <classnum>:<min>:<default>:<max>

All lines must be in the correct format given the current setting of
I<groupbaseexpiry>, and therefore the two formats cannot co-exist in the
same file.

Normally, a rule matches a newsgroup through the combination of the
<pattern> and <flag> fields.  <pattern> is a I<uwildmat>-style pattern,
specifying the newsgroups to which the line is applied.  Note that the
last matching entry will be used, so general patterns (such as defaults
for all groups where <pattern> is C<*>) should appear at the beginning of
the file before more specific settings.

The <flag> field can be used to further limit newsgroups to which the line
applies, and should be chosen from the following set:

    M   Only moderated groups
    U   Only unmoderated groups
    A   All groups
    X   Remove the article from all groups it appears in

One of C<M>, C<U>, or C<A> must be specified.  C<X> should be used in
combination with one of the other letters, not by itself.

An expiration policy is applied to every article in a newsgroup it matches.
There is no way to set an expiration policy for articles crossposted to
groups you don't carry that's different than other articles in the same group.
Normally, articles are not completely deleted until they expire out of every
group to which they were posted, but if an article is expired following a rule
where <flag> contains C<X>, it is deleted out of all newsgroups to which it
was posted immediately.  (If that behaviour is wanted for all rules, you may
want to give the B<-e> flag to B<expireoverview>.)

If I<groupbaseexpiry> is instead set to false, there is no <pattern> and
<flag> field and the above does not apply.  Instead, there is a single
<classnum> field, which is either a number matching the storage class
number specified in F<storage.conf> or C<*> to specify a default for all
storage classes.  All articles stored in a storage class will be expired
following the instructions in the line with a matching <classnum>, and
when articles are expired, they're always removed from all groups to which
they were posted.

The remaining three fields are the same in either format, and are used to
determine how long an article should be kept from its original arrival
time (unless the B<-p> flag is passed to expire(8) or expireover(8), in
which case its original posting time is used).  Each field should be either
a decimal number of days (fractions like C<8.5> are allowed, but remember
that articles are only removed when B<expire> or B<expireover> is run,
normally once a day by B<news.daily>) or the word C<never>.

The middle field, <default>, will be used as the expiration period for
most articles.  The other two fields, <min> and <max>, only come into
play if the article requests a particular expiration date with an Expires
header field.  Articles with an Expires header field will be expired
at the date given in that header field, subject to the constraints that
they will be retained at least <min> days and no longer than <max> days.

If <min> is set to C<never>, no article matching that line will ever be
expired.  If <default> is set to C<never>, no article matching that line
without an explicit Expires header field will ever be expired.  If <max> is
set to C<never>, Expires header fields will be honored no matter how far into
the future they are.

One should think of the fields as a lower bound, the default, and an upper
bound.  Since most articles do not have an Expires header field, the second
field is the most important and most commonly applied.

Articles that do not match any expiration rule will not be expired, but
this is considered an error and will result in a warning.  There should
always be a default line (a line with a <pattern> of C<*> and <flag> of
C<A>, or a line with a <classnum> of C<*>), which can explicitly state
that articles should never expire by default if that's the desired
configuration.  The default line should generally be the first line of the
file (except for C</remember/>) so that other expiration rules can
override it.

It is often useful to honor the Expires header field in articles, especially
those in moderated groups.  To do this, set <min> to zero, <default> to
whatever normal expiration you wish, and <max> to C<never> or some large
number, like C<365> days for a maximum article life of a year.

To ignore any Expires header field, set all three fields to the same value.

=head1 EXAMPLES

When I<groupbaseexpiry> is true (the default):

    # Keep expired article history for 11 days, matching artcutoff plus one.
    /remember/:11

    # Most articles stay for two weeks, ignoring Expires header fields.
    *:A:14:14:14

    # Accept Expires header fields in moderated groups for up to a year and
    # retain moderated groups for a bit longer.
    *:M:1:30:365

    # Keep local groups for a long time and local project groups forever.
    example.*:A:1:90:90
    example.project.*:A:never:never:never

When I<groupbaseexpiry> is false, for class-based expiration:

    # Keep expired article history for 11 days, matching artcutoff plus one.
    /remember/:11

    # Set a default expiration of seven days and honour Expires header fields
    # within reasonable limits.
    *:1:7:35

    # Class 0 is retained for two weeks and honor Expires header fields
    # within reasonable limits.
    0:1:14:65

=head1 HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Converted to
POD by Russ Allbery <eagle@eyrie.org>.

=head1 SEE ALSO

expire(8), expireover(8), inn.conf(5), innd(8), libinn_uwildmat(3),
news.daily(8), storage.conf(5).

=cut
