INN commit: trunk/doc/pod (4 files)
INN Commit
Russ_Allbery at isc.org
Tue Aug 14 18:49:27 UTC 2007
Date: Tuesday, August 14, 2007 @ 11:49:27
Author: iulius
Revision: 7646
Improve POD documentation and correct typos.
Add a note regarding 2 GB cycbuffs.
The length of a buffer name cannot be higher than 8 characters.
Modified:
trunk/doc/pod/buffindexed.conf.pod
trunk/doc/pod/ckpasswd.pod
trunk/doc/pod/ctlinnd.pod
trunk/doc/pod/cycbuff.conf.pod
----------------------+
buffindexed.conf.pod | 5 +++++
ckpasswd.pod | 22 +++++++++++-----------
ctlinnd.pod | 34 +++++++++++++++++++---------------
cycbuff.conf.pod | 41 +++++++++++++++++++++++++++--------------
4 files changed, 62 insertions(+), 40 deletions(-)
Modified: buffindexed.conf.pod
===================================================================
--- buffindexed.conf.pod 2007-08-14 18:46:00 UTC (rev 7645)
+++ buffindexed.conf.pod 2007-08-14 18:49:27 UTC (rev 7646)
@@ -52,6 +52,11 @@
support); this limitation may be fixed in the future. For more
information on setting up the buffers, see L<CREATING BUFFERS>.
+An example of F<buffindexed.conf> file can be:
+
+ 0:/usr/local/news/spool/overview/OV1:1536000
+ 1:/usr/local/news/spool/overview/OV2:1536000
+
When you first start B<innd> with everything configured properly, you
should see messages like this in I<pathlog>/news.notice:
Modified: ckpasswd.pod
===================================================================
--- ckpasswd.pod 2007-08-14 18:46:00 UTC (rev 7645)
+++ ckpasswd.pod 2007-08-14 18:49:27 UTC (rev 7646)
@@ -9,11 +9,11 @@
=head1 DESCRIPTION
-B<ckpasswd> is the basic password authenticator for nnrpd, suitable for
+B<ckpasswd> is the basic password authenticator for B<nnrpd>, suitable for
being run from an auth stanza in F<readers.conf>. See readers.conf(5) for
-more information on how to configure an nnrpd authenticator.
+more information on how to configure an B<nnrpd> authenticator.
-B<ckpasswd> accepts a username and password from nnrpd and tells nnrpd(8)
+B<ckpasswd> accepts a username and password from B<nnrpd> and tells nnrpd(8)
whether that's the correct password for that username. By default, when
given no arguments, it tries to check the password using PAM if support
for PAM was found when INN was built. Failing that, it tries to check the
@@ -31,7 +31,7 @@
When using any method other than PAM, B<ckpasswd> expects all passwords to
be stored encrypted by the system crypt(3) function and calls crypt(3) on
-the supplied password before comparing it to the expected password. IF
+the supplied password before comparing it to the expected password. If
you're using a different password hash scheme (like MD5), you must use
PAM.
@@ -85,7 +85,7 @@
(and each line may have an additional colon after the encrypted password
and additional data; that data will be ignored by B<ckpasswd>). Lines
-starting with a number sign (`#') are ignored. INN does not come with a
+starting with a number sign (C<#>) are ignored. INN does not come with a
utility to create the encrypted passwords, but B<htpasswd> (which comes
with Apache) can do so and it's a quick job with Perl (see the example
script under B<-d>). If using Apache's B<htpasswd> program, be sure to
@@ -94,13 +94,13 @@
=item B<-g>
Attempt to look up system group corresponding to username and return a
-string like "user at group" to be matched against in F<readers.conf>. This
+string like C<user at group> to be matched against in F<readers.conf>. This
option is incompatible with the B<-d> and B<-f> options.
=item B<-p> I<password>
Use I<password> as the password for authentication rather than reading a
-password using the nnrpd authenticator protocol. This option is useful
+password using the B<nnrpd> authenticator protocol. This option is useful
only for testing your authentication system (particularly since it
involves putting a password on the command line), and does not work when
B<ckpasswd> is run by B<nnrpd>. If this option is given, B<-u> must also
@@ -109,14 +109,14 @@
=item B<-s>
Check passwords against the result of getspnam(3) instead of getpwnam(3).
-This function, on those systems that supports it, reads from /etc/shadow
+This function, on those systems that supports it, reads from F</etc/shadow>
or similar more restricted files. If you want to check passwords supplied
to nnrpd(8) against system account passwords, you will probably have to
use this option on most systems.
Most systems require special privileges to call getspnam(3), so in order
to use this option you may need to make B<ckpasswd> setgid to some group
-(like group "shadow") or even setuid root. B<ckpasswd> has not been
+(like group C<shadow>) or even setuid root. B<ckpasswd> has not been
specifically audited for such uses! It is, however, a very small program
that you should be able to check by hand for security.
@@ -167,7 +167,7 @@
will check a username of C<test> and a password of C<testing> against the
username and passwords stored in F</path/to/passwd/file>. On success,
-B<ckpasswd> will print C<User:test> and exit with status 0. On failure,
+B<ckpasswd> will print C<User:test> and exit with status C<0>. On failure,
it will print some sort of error message and exit a non-zero status.
=head1 HISTORY
@@ -178,7 +178,7 @@
=head1 SEE ALSO
-readers.conf(5), nnrpd(8)
+crypt(3), pam(7), readers.conf(5), nnrpd(8).
Linux users who want to use PAM should read the Linux-PAM System
Administrator's Guide at
Modified: ctlinnd.pod
===================================================================
--- ctlinnd.pod 2007-08-14 18:46:00 UTC (rev 7645)
+++ ctlinnd.pod 2007-08-14 18:49:27 UTC (rev 7646)
@@ -68,9 +68,9 @@
I<arrival>, I<expires>, and I<posted> should be the number of seconds
since epoch and indicate when the article arrived, when it expires (via
-the Expires header), and when it was posted (given in the Date header),
-respectively. I<expires> should be 0 if the article doesn't have an
-Expires header. I<token> is the storage API token for the article, and
+the Expires: header), and when it was posted (given in the Date: header),
+respectively. I<expires> should be C<0> if the article doesn't have an
+Expires: header. I<token> is the storage API token for the article, and
may be empty.
This command can only be used while the server is running, and will be
@@ -166,7 +166,7 @@
If the server throttled itself because it accumulated too many I/O errors,
this command will reset the error count.
-If the server was not started with the B<-ny> flag, this command also does
+If B<innd> was not started with the B<-n y> flag, this command also does
the equivalent of a C<readers> command with C<yes> as the flag and
I<reason> as the text.
@@ -188,6 +188,10 @@
signal number or one of C<hup>, C<int>, or C<term>; case is not
significant.
+=item logmode
+
+Cause the server to log its current operating mode to syslog.
+
=item lowmark I<file>
Reset the low-water marks in the F<active> file based on the contents of
@@ -202,10 +206,6 @@
This command is mostly used by B<news.daily> to update the I<active> file
after nightly expiration.
-=item logmode
-
-Cause the server to log its current operating mode to syslog.
-
=item mode
Print the server's operating mode as a multi-line summary of the
@@ -217,7 +217,7 @@
Print the name and relevant information for the given incoming or outgoing
channel, or for all channels if I<channel> is an empty string. The
-respose is formatted as:
+response is formatted as:
<name>:<number>:<type>:<idle>:<status>
@@ -253,7 +253,7 @@
specified at configure time, normally C<usenet>). I<mode> may also be
omitted; if so, it will default to C<y> (a normal, unmoderated group).
The combination of defaults make it possible to use the text of the
-Control header directly (although don't do this without checking the
+Control: header directly (although don't do this without checking the
syntactic validity of the header first).
This command can only be done while the server is running or throttled
@@ -272,14 +272,15 @@
enable or disable the action of the B<-n> flag, use C<n> for the letter
and C<y> or C<n>, respectively, for the value.
-The supported values for I<letter> are a, c, H, i, l, n, o, T, t, and X.
+The supported values for I<letter> are C<a>, C<c>, C<H>, C<i>, C<l>, C<n>,
+C<o>, C<T>, C<t>, and C<X>.
=item pause I<reason>
Pause the server so that no incoming articles are accepted. No existing
connections are closed, but the history database is closed. This should
be used for short-term locks, such as when replacing the history
-database. If the server was not started with the B<-ny> flag, this
+database. If the server was not started with the B<-n y> flag, this
command also does the equivalent of a C<readers> command with C<no> as the
flag and I<reason> as the text.
@@ -340,7 +341,7 @@
support.
If I<what> is the word C<filter.python>, the F<filter_innd.py> file is
-reloaded. If a Python method named filter_before_reload() exists, it will
+reloaded. If a Python method named C<filter_before_reload> exists, it will
be called prior to re-reading F<filter_innd.py>. If a Python method named
C<__init__> exists, it will be called after F<filter_innd.py> has been
reloaded. Reloading the Python filter does not enable filtering if it has
@@ -414,7 +415,10 @@
connections. Close the history database. This should be used for
long-term locks or for running a large number of C<newgroup> and
C<rmgroup> commands without restarting all outgoing feeds between each
-one. If the server was not started with the B<-ny> flag, then this
+one. (Note that changing the status of existing newsgroups when the
+server is throttled cannot be done.)
+
+If the server was not started with the B<-n y> flag, then this
command also does the equivalent of a C<readers> command with C<no> as the
flag and I<reason> as the text.
@@ -483,6 +487,6 @@
=head1 SEE ALSO
active(5), active.times(5), buffchan(8), incoming.conf(5), innd(8),
-inndcomm(3), inn.conf(5), newsfeeds(5), nnrpd(8), overview.fmt(5)
+inndcomm(3), inn.conf(5), newsfeeds(5), nnrpd(8), overview.fmt(5).
=cut
Modified: cycbuff.conf.pod
===================================================================
--- cycbuff.conf.pod 2007-08-14 18:46:00 UTC (rev 7645)
+++ cycbuff.conf.pod 2007-08-14 18:49:27 UTC (rev 7646)
@@ -10,6 +10,16 @@
if the CNFS (Cyclic News File System) storage method is used. INN will
look for it in I<pathetc> (as set in F<inn.conf>).
+CNFS stores articles in logical objects called I<metacycbuffs>. Each
+metacycbuff is in turn composed of one or more physical buffers called
+I<cycbuffs>. As articles are written to the metacycbuff, each article is
+written to the next cycbuff in the list in a round-robin fashion (unless
+C<sequential> mode is specified, in which case each cycbuff is filled
+before moving on to the next). This is so that you can distribute the
+individual cycbuffs across multiple physical disks and balance the load
+between them. Note that in order to use any cycbuff larger than 2 GB,
+you need to build INN with the B<--enable-largefiles> option.
+
For information about how to configure INN to use CNFS, see
storage.conf(5).
@@ -30,14 +40,14 @@
=item cycbuffupdate:<interval>
-Sets the number of articles are written before the cycbuff header is
+Sets the number of articles written before the cycbuff header is
written back to disk to <interval>. Under most operating systems, the
header doesn't have to be written to disk for the updated data to be
available to other processes on the same system that are reading articles
out of CNFS, but any accesses to the CNFS cycbuffs over NFS will only see
the data present at the last write of the header. After a system crash,
all updates since the last write of the CNFS header may be lost. The
-default value, if this line is omitted, is 25, meaning that the header is
+default value, if this line is omitted, is C<25>, meaning that the header is
written to disk after every 25 articles stored in that cycbuff.
=item refreshinterval:<interval>
@@ -45,7 +55,7 @@
Sets the interval (in seconds) between re-reads of the cycbuff header to
<interval>. This primarily affects B<nnrpd> and controls the frequency
with which it updates its knowledge of the current contents of the CNFS
-cycbuffs. The default value, if this line is omitted, is 30.
+cycbuffs. The default value, if this line is omitted, is C<30>.
=item cycbuff:<name>:<file>:<size>
@@ -56,6 +66,8 @@
the buffer in kilobytes (1KB is 1024 bytes). If <file> is not a block
device, it should be <size> * 1024 bytes long.
+If you're trying to stay under 2 GB, keep your sizes below C<2097152>.
+
=item metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]
Specifies a collection of CNFS buffers that make up a single logical
@@ -64,29 +76,30 @@
actually put articles in a cycbuff, it has to be listed as part of some
metacycbuff which is then referenced in F<storage.conf>.
-<name> is the symbolic name of the metacycbuff, referred to in the options
-field of cnfs entries in F<storage.conf>. <buffer> is the name of a
-cycbuff (the <name> part of a cycbuff line), and any number of cycbuffs
-may be specified, separated by commas.
+<name> is the symbolic name of the metacycbuff, referred to in the options:
+field of C<cnfs> entries in F<storage.conf>. It must be no longer than
+eight characters. <buffer> is the name of a cycbuff (the <name> part of
+a cycbuff line), and any number of cycbuffs may be specified, separated
+by commas.
If there is more than one cycbuff in a metacycbuff, there are two ways
that INN can distribute articles between the cycbuffs. The default mode,
-INTERLEAVE, stores the articles in each cycbuff in a round-robin fashion,
+C<INTERLEAVE>, stores the articles in each cycbuff in a round-robin fashion,
one article per cycbuff in the order listed. If the cycbuffs are of
wildly different sizes, this can cause some of them to roll over much
faster than others, and it may not give the best performance depending on
-your disk layout. The other storage mode, SEQUENTIAL, instead writes to
+your disk layout. The other storage mode, C<SEQUENTIAL>, instead writes to
each cycbuff in turn until that cycbuff is full and then moves on to the
next one, returning to the first and starting a new cycle when the last
one is full. To specify a mode rather than leaving it at the default, add
-a colon and the mode (INTERLEAVE or SEQUENTIAL) at the end of the
+a colon and the mode (C<INTERLEAVE> or C<SEQUENTIAL>) at the end of the
metacycbuff line.
=back
B<innd> only reads F<cycbuff.conf> on startup, so if you change anything
-in this file and want B<innd> to pick up the changes, you have to stop and
-restart it. C<ctlinnd reload ''> is not sufficient.
+in this file and want B<innd> to pick up the changes, you have to use
+C<ctlinnd xexec innd>; C<ctlinnd reload ''> is not sufficient.
When articles are stored, the cycbuff into which they're stored is saved
as part of the article token. In order for INN to retrieve articles from
@@ -185,7 +198,7 @@
innd: CNFS-sm No magic cookie found for cycbuff ONE, initializing
-where ONE will be whatever you called your cycbuff.
+where C<ONE> will be whatever you called your cycbuff.
=head1 HISTORY
@@ -196,6 +209,6 @@
=head1 SEE ALSO
-ctlinnd(8), innd(8), nnrpd(8), sm(1), storage.conf(5)
+ctlinnd(8), innd(8), nnrpd(8), sm(1), storage.conf(5).
=cut
More information about the inn-committers
mailing list