.TH noffle.conf 5
.\" $Id: noffle.conf.5 645 2006-07-12 19:26:41Z bears $

.SH NAME
noffle.conf \- Configuration file for NOFFLE news server

.SH DESCRIPTION

The
.B NOFFLE
news server - see
.BR noffle (1)
- takes its configuration from a configuration file.
By default this file is \fI/etc/noffle.conf\fP.

.PP
.B noffle.conf
is a normal text file containing
.B NOFFLE
settings, one per line.

.PP
Leading whitespace on a line is ignored, as is any comment
text. Comment text begins with a '#' character and continues to the
end of the line. Blank lines are permitted.

.SH SETTINGS

.TP
.B server <hostname>[:<port>] [<user> <pass>]
Name of the remote server. If no port given, port 119 is used.
Username and password for servers that need authentication
(Original AUTHINFO). The password may not contain white-spaces.
If there are multiple server entries in the config file, all of them are
used for getting groups. In this case the first server should be
the one of your main provider. Note that you must always
run 'noffle \-\-query groups'
after making changes to the server entries.

.TP
.B getgroups <group pattern> [, <group pattern> ...]
Only retrieve from the most recently specified server newsgroups that match
the specified patterns. The patterns can contain \fIwildcards\fP, and
there can be multiple
.B getgroups
lines. For further details on
.B getgroups
processing in tandem with \fBomitgroups\fP, see the section on
.B omitgroups
following.
.br
Default: All groups

.TP
.B omitgroups <group pattern> [, <group pattern> ...]
Don't retrieve from the most recently specified server newsgroups that match
the specified patterns. The patterns can contain \fIwildcards\fP, and
there can be multiple
.B omitgroups
lines. When processing a new newsgroup name, it is checked first to see
if it appears on the
.B getgroups
list (if any). If not, the group is rejected.
Then the group is checked to see if it appears on the
.B omitgroups
list. If it does not, the group is accepted as a group
.B NOFFLE
will list and collect as required.
.br
Default: No groups

.TP
.B max\-fetch <n>
Never get more than <n> articles. If there are more, the oldest ones
are discarded.
.br
Default: 300

.TP
.B from\-domain <domain>
When invoked as
.BR inews (1)
.B NOFFLE
will add a From: line to posts that lack one. The address given
uses the userid of the user who invoked 
.B inews
and the specified domain.
.br
Default: The system domain

.TP
.B log\-debug <log category> [<log category ...]
Log debugging information from the specified log category
or categories. Logging is via the system logging daemon
.BR syslogd (8)
(to the debug facility) and additionally to stderr when running
interactively.  The available categories for logging are
.BR all ,
.BR none ,
.BR config ,
.BR auth ,
.BR control ,
.BR expire ,
.BR fetch ,
.BR filter ,
.BR newsbase ,
.BR noffle ,
.BR post ,
.BR protocol ,
.BR requests
and
.BR server.
The
.B noffle
category is automatically selected whenever any other category is
selected. These messages are in addition to messages logged to the
system logging daemon error, information and notification facilities.
.br
Default: none

.TP
.B organization <organization>
When invoked as
.BR inews (1)
.B NOFFLE
will, unless the \-O flag is specified, add an Organization: line to
posts that lack one. If no
.B organization
is specified, the line is not added.
.br
Default: <empty string>

.TP
.B mail\-to <address>
Receiver of failed postings. If empty then failed postings are returned
to the sender (taking the address from the article's Reply-To, Sender,
X-Sender or From field, in this order).
.br
Default: <empty string>

.TP
.B auto\-unsubscribe yes|no
Automatically remove groups from fetch list if they have not been
accessed for a number of days. Groups are only unsubscribed if there
are fresh articles arriving and remaining unread.
.br
Default: no

.TP
.B auto\-unsubscribe\-days <n>
Number of days used for auto-unsubscribe option.
.br
Default: 30

.TP
.B thread\-follow\-time <n>
Automatically mark articles for download in thread mode, if they
are referencing an article that has been opened by a reader within the last
<n> days.
.br
Default: 7

.TP
.B connect\-timeout <n>
Timeout for connecting to remote server in seconds.
.br
Default: 30

.TP
.B auto\-subscribe yes|no
Automatically put groups on fetch list if someone reads them.
<mode> can be full, over, thread (depending on the fetch mode) or
off (do not subscribe automatically). Condition for putting a group
on the list is that an article is opened. For this reason there is
always a pseudo article visible in groups that are not on the fetch list.
.br
Default: no

.TP
.B auto\-subscribe\-mode <group pattern> full|thread|over
Mode for auto-subscribe option for groups that match the given
pattern. 
.br
Default: none

.TP
.B default\-auto\-subscribe\-mode full|thread|over
Default mode for auto-subscribe option. Used for all groups that do
not match a pattern specified with
.B auto\-subscribe\-mode
entries (if any).
.br
Default: over

.TP
.B info\-always\-unread yes|no
An information article is presented for all unsubscribed
newsgroups. If auto-subscribe mode is off, there is a possibility of
someone reading the article but forgetting the instructions therein
and not knowing how to return to a read article. This option causes
the information article always to be present as an unread article in a
group when auto-subscribe if off. It does this by incrementing the
article number of the information article every time it is read.
.br
Default: yes

.TP
.B authenticate\-client yes|no
Insist that clients authenticate themselves using the NNTP
AUTHINFO USER/AUTHINFO PASS transaction before any news is served.
This option is recognised only when NOFFLE has been built with
authentication enabled.
The form of the authentication is determined at compile time; either
PAM is used (with a service name "noffle"), or the userlist
file is scanned. This file, by default \fI/etc/noffle.users\fP,
is a text file. Spaces, comments starting with '#' and blank lines are
ignored. Other lines must contain space-separated 'username password'
pairs. For security reasons the userlist file must be a regular file,
not a link, and must be owner readable only. Finally, note that the
NNTP AUTHINFO USER/AUTHINFO PASS transaction is not encrypted in any
way, and so must itself be considered insecure.
.br
Default: no

.TP
.B post\-locally yes|no
Place articles posted to external servers in the local aticle database
immediately. Some servers may rewrite Message-IDs, which will cause
duplicate postings of this option is enabled. Also, if for some reason
the post to the remote server fails, the article still exists in the local
database, which may be a source of some confusion.
.br
Default: no

.TP
.B replace\-messageid yes|no
Always replace the Message-ID of a posted article with a Message-ID
generated by NOFFLE. NOFFLE by default adds a Message-ID if none is
present. However, some news readers may generate Message-IDs that are
not accepted by some servers (for example the server may insist the
Message-ID domain is part of the server domain) or may not always be
unique. In either of these cases you may prefer to have NOFFLE always
replace the Message-ID.
.br
Default: no

.TP
.B add\-messageid\-if-missing yes|no
NOFFLE by default will always add a Message-ID a posted article if the
article does not have a Message-ID. This is required if
.B post\-locally
is set. However, some news servers in the wild have been observed
to prefer to assign their own Message-IDs, to the extent of often
rejecting posts with perfectly legitimate Message-IDs. If you are
unfortunate enough to be confronted by one of these beasts, you can
change
.B add\-messageid\-if-missing
to
.B no
to leave adding a Message-ID to the upstream server. If you do this,
you
.B must
also set
.B post\-locally
to
.B no
or posting an article without a Message-ID will generate an error.
.br
Default: yes

.TP
.B hostname <fully.qualified.domain.name>
Specify right-hand side of Message-IDs generated by NOFFLE.
If omitted, the fully qualified domain name of your system will be used.
If you do not have a fully qualified domain name, your upstream
newsserver or someone else might allow you to use a subdomain name.
.br
Default: <the fully qualified domain name of your system>

.TP
.B append\-reply\-to yes|no
Append a 'Reply-To:' header to messages posted without it.
The address from the 'From:' header is used. Though this might seem 
pretty useless at first glance it may be desireable as some providers were 
known to overwrite the 'From:' header.
.br
Default: yes

.TP
.B path\-header <path header content>
Articles posted without a Path: header have one added by NOFFLE.
When
.B path\-header
has its default value (empty) the header content
is "<hostname>!not-for-mail".
Use the
.B path\-header
setting to provide alternate content for the Path: header.
This will very rarely be necessary.
.br
Default: <empty string>

.TP
.B default\-expire <n>
The default expiry period, in days. An expiry period of 0 means "never".
.br
Default: 14

.TP
.B noffle\-user <n>
The username under which NOFFLE normally runs. If NOFFLE is invoked by
root, it will drop its real and effective UID to this user as soon as
possible.
.br
Default: news

.TP
.B noffle\-group <n>
The group under which NOFFLE normally runs. NOFFLE will change to this
real and effective GID as soon as possible.
.br
Default: news

.TP
.B expire <group pattern> <n>
The expiry period for a newsgroup or set of newsgroups, in days. The
expiry pattern can contain \fIwildcards\fP, and there can be multiple
.B expire
lines. When checking the expiry period for a group, the expiry
patterns are checked in the order in which they appear in
.I /etc/noffle.conf
until the first match occurs. If no pattern matches the group name, the
.B default expiry period
is used. An expiry period of 0 means "never".
.br
Default: no

.TP
.B filter <filter specification>
Add the specified filter to the list of filters to be applied to incoming
articles. Filters are applied in the order in which they appear in
.I /etc/noffle.conf
and are further described in the section
.B FILTERS
below.
.br
Default: No filters

.SH "GROUP NAME WILDCARDS"

.B NOFFLE
uses a wildcard format that closely matches filename-style wildcards.
\fIalt.binaries.*\fP, for example, matches all newsgroups under the
.I alt.binaries
hierarchy. A full description of the format (known as
.B wildmat
patterns) is as follows.

.TP
.BI \e x
Turns off the special meaning of
.I x
and matches it directly; this is used mostly before a question mark or
asterisk, and is not special inside square brackets.
.TP
.B ?
Matches any single character.
.TP
.B *
Matches any sequence of zero or more characters.
.TP
.BI [ x...y ]
Matches any single character specified by the set
.IR x...y .
A minus sign may be used to indicate a range of characters.
That is,
.I [0\-5abc]
is a shorthand for
.IR [012345abc] .
More than one range may appear inside a character set;
.I [0-9a-zA-Z._]
matches almost all of the legal characters for a host name.
The close bracket,
.IR ] ,
may be used if it is the first character in the set.
The minus sign,
.IR \- ,
may be used if it is either the first or last character in the set.
.TP
.BI [^ x...y ]
This matches any character
.I not
in the set
.IR x...y ,
which is interpreted as described above.
For example,
.I [^]\-]
matches any character other than a close bracket or minus sign.

.SH FILTERS

.B NOFFLE
supports basic filtering on incoming articles. Articles to be downloaded
can be matched against one or more criteria and matching articles are
marked for download using one of the group subscribe modes
.BR full ,
.B over
or
.BR thread .
Alternatively the filter may specify that the article mode is
.B discard
in which case neither the article nor the article overview will
be downloaded.

.PP
A
.B filter
configuration line consist of one or more filter specifications
following the
.B filter
keyword on the line. The available specifications are:

.PP
.B action
=
.IR "full|over|thread|discard|default" .
Specifies the action to be taken if the filter matches. If not specified
or specified as
.BR default ,
the action is as specified by the group's subscription mode.
.PP
.B group
=
.IR "<group pattern>" .
Matches if any group in which the article appears matches the
specified group pattern.
.PP
.B subject
=
.IR "<regular expression>" .
Matches if the article subject matches the given regular expression.
See the section on regular expressions below.
.PP
.B from
=
.IR "<regular expression>" .
Matches if the article From: address matches the given regular expression.
See the section on regular expressions below.
.PP
.B msgid
=
.IR "<regular expression>" .
Matches if the article message ID matches the given regular expression.
See the section on regular expressions below.
.PP
.B bytes
< or = or >
.IR <number> .
Matches if the number of bytes in the article is less than, equal to, or
greater than the given number.
.PP
.B lines
< or = or >
.IR <number> .
Matches if the number of lines in the article is less than, equal to, or
greater than the given number.
.PP
.B refs
< or = or >
.IR <number> .
Matches if the number of articles referenced by the article is less
than, equal to, or greater than the given number.
.PP
.B reference
=
.IR "<regular expression>" .
Matches if one of the message IDs in the reference line matches the
given regular expression. See the section on regular expressions below.
.PP
.B xposts
< or = or >
.IR <number> .
Matches if the number of groups the article is posted to is less
than, equal to, or greater than the given number.
.PP
.B date
< or = or >
.IR "<date expression>" .
Matches if the article is older, from the same day or newer than the
given date expression. See the section on date expressions below.
.PP
.B older
=
.IR "<date expression>" .
Equals
.B date <
.
.PP
.B newer
=
.IR "<date expression>" .
Equals
.B date >
.
.PP
.B post-status 
=
.IR "mod|yes|no" .
Matches if the current newsgroup is moderated, not moderated or closed.
Unlike the 
.B group
filter, only the current newsgroup is checked.

.PP
Numbers may have a suffix of 'k' or 'm'. As you might expect, 'k'
indicates the number is to be multiplied by 1024 and 'm' indicates
it is to be multiplied by 1024*1024. Thus 10k is 10240 and 1m is 1048576.

.PP
For example, the following filters download all articles in groups
in the alt.binaries tree in full if they are < 10k in size, otherwise
downloads overviews.
.PP
.I filter group=alt.binaries.* bytes < 10k action=full
.br
.I filter group=alt.binaries.* action=over
.PP
This filter discards all articles with a subject resembling
the infamous "$$$ Make Money Now! $$$".
.PP
\fIfilter subject="\\$*.*Make.*[M|m]oney.*\\$" action=discard\fR

.SH REGULAR EXPRESSIONS

.B NOFFLE
uses extended POSIX-style regular expressions in its filters. Regular
expressions are a powerful means of describing patterns that match
text. A full description is to be found in 
.BR regex (7).

.SH DATE EXPRESSIONS

.B NOFFLE
uses very simple date expressions. You can use fixed dates in rfc-2822 style
or variable dates:
.PP
.I date="14 May 2002 18:32:50 +0200"
matches any article sent up to 24 hours before or after the above fixed date.
Please don't forget the timezone specification.
.PP
.I date>"now+1.5"
matches any article newer than 36 hours from the current date.
.PP
.I date="lastupdate\-14"
matches any article older than 14 days since the date of the last
.B noffle \-\-fetch
or
.B noffle \-\-query groups
from the current newsserver.
.PP
.I date="invalid"
matches any article with an invalid date header.
.PP
.SH SEE ALSO

.BR noffle (1)
.BR regex (7)

.SH AUTHORS

Markus Enzenberger <me@markus\-enzenberger.de>
.br
Volker Wysk <volker.wysk@student.uni\-tuebingen.de>
.br
Jim Hague <jim.hague@acm.org>
.br
Uwe Hermann <uh1763@bingo\-ev.de>
.br
Mirko Liss <mirko.liss@web.de>

1998-2003.