doc/pod/cycbuff.conf.pod

   1 =head1 NAME
   2
   3 cycbuff.conf - Configuration file for INN CNFS storage method
   4
   5 =head1 DESCRIPTION
   6
   7 This file defines the cyclical buffers that make up the storage pools for
   8 CNFS (Cyclic News File System).  Some options controlling the behavior of
   9 the CNFS storage system can also be set here.  F<cycbuff.conf> is required
  10 if the CNFS (Cyclic News File System) storage method is used.  INN will
  11 look for it in I<pathetc> (as set in F<inn.conf>).
  12
  13 For information about how to configure INN to use CNFS, see
  14 storage.conf(5).
  15
  16 Blank lines and lines beginning with a hash sign (C<#>) are ignored.  All
  17 other lines must be of one of the following forms:
  18
  19     cycbuffupdate:<interval>
  20     refreshinterval:<interval>
  21     cycbuff:<name>:<file>:<size>
  22     metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]
  23
  24 (where items enclosed in [] are optional).  Order is mostly not
  25 significant, but all I<cycbuff> lines must occur before all I<metacycbuff>
  26 lines.  Long lines can be continued on the next line by ending the line
  27 with a backslash (C<\>).
  28
  29 =over 4
  30
  31 =item cycbuffupdate:<interval>
  32
  33 Sets the number of articles are written before the cycbuff header is
  34 written back to disk to <interval>.  Under most operating systems, the
  35 header doesn't have to be written to disk for the updated data to be
  36 available to other processes on the same system that are reading articles
  37 out of CNFS, but any accesses to the CNFS cycbuffs over NFS will only see
  38 the data present at the last write of the header.  After a system crash,
  39 all updates since the last write of the CNFS header may be lost.  The
  40 default value, if this line is omitted, is 25, meaning that the header is
  41 written to disk after every 25 articles stored in that cycbuff.
  42
  43 =item refreshinterval:<interval>
  44
  45 Sets the interval (in seconds) between re-reads of the cycbuff header to
  46 <interval>.  This primarily affects B<nnrpd> and controls the frequency
  47 with which it updates its knowledge of the current contents of the CNFS
  48 cycbuffs.  The default value, if this line is omitted, is 30.
  49
  50 =item cycbuff:<name>:<file>:<size>
  51
  52 Configures a particular CNFS cycbuff.  <name> is a symbolic name for the
  53 buffer, to be used later in a metacycbuff line.  It must be no longer than
  54 seven characters.  <file> is the full path to the buffer file or block
  55 device, and must be no longer than 63 characters.  <size> is the length of
  56 the buffer in kilobytes (1KB is 1024 bytes).  If <file> is not a block
  57 device, it should be <size> * 1024 bytes long.
  58
  59 =item metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]
  60
  61 Specifies a collection of CNFS buffers that make up a single logical
  62 storage location from the perspective of INN.  Metacycbuffs are referred
  63 to in F<storage.conf> as storage locations for articles, so in order to
  64 actually put articles in a cycbuff, it has to be listed as part of some
  65 metacycbuff which is then referenced in F<storage.conf>.
  66
  67 <name> is the symbolic name of the metacycbuff, referred to in the options
  68 field of cnfs entries in F<storage.conf>.  <buffer> is the name of a
  69 cycbuff (the <name> part of a cycbuff line), and any number of cycbuffs
  70 may be specified, separated by commas.
  71
  72 If there is more than one cycbuff in a metacycbuff, there are two ways
  73 that INN can distribute articles between the cycbuffs.  The default mode,
  74 INTERLEAVE, stores the articles in each cycbuff in a round-robin fashion,
  75 one article per cycbuff in the order listed.  If the cycbuffs are of
  76 wildly different sizes, this can cause some of them to roll over much
  77 faster than others, and it may not give the best performance depending on
  78 your disk layout.  The other storage mode, SEQUENTIAL, instead writes to
  79 each cycbuff in turn until that cycbuff is full and then moves on to the
  80 next one, returning to the first and starting a new cycle when the last
  81 one is full.  To specify a mode rather than leaving it at the default, add
  82 a colon and the mode (INTERLEAVE or SEQUENTIAL) at the end of the
  83 metacycbuff line.
  84
  85 =back
  86
  87 B<innd> only reads F<cycbuff.conf> on startup, so if you change anything
  88 in this file and want B<innd> to pick up the changes, you have to stop and
  89 restart it.  C<ctlinnd reload all ''> is not sufficient.
  90
  91 When articles are stored, the cycbuff into which they're stored is saved
  92 as part of the article token.  In order for INN to retrieve articles from
  93 a cycbuff, that cycbuff must be listed in F<cycbuff.conf>.  However, if
  94 INN should not write to a cycbuff, it doesn't need to be (and shouldn't
  95 be) listed in a metacycbuff.
  96
  97 This provides an easy way to retire a cycbuff.  Just remove it from its
  98 metacycbuff, leaving in the cycbuff line, and restart B<innd> (with, for
  99 example, C<ctlinnd xexec innd>).  No new articles will be put into the
 100 cycbuff, but neither will any articles expire from it.  After you no
 101 longer need the articles in the cycbuff, just remove it entirely from
 102 F<cycbuff.conf>.  Then all of the articles will appear to have been
 103 deleted to INN, and the next nightly expire run will clean up any
 104 remaining references to them.
 105
 106 Adding a new cycbuff just requires creating it (see below), adding a
 107 cycbuff line, adding it to a metacycbuff, and then restarting B<innd>.
 108
 109 =head1 CREATING CYCBUFFS
 110
 111 When creating a new cycbuff, there are two different methods for creating
 112 the buffers in which the articles will be stored.
 113
 114 =over 4
 115
 116 =item 1.
 117
 118 Create a large file on top of a regular file system.  The easiest way to
 119 do this is probably with dd(1), using a command like:
 120
 121     dd if=/dev/zero of=/path/to/cycbuff bs=1024 count=<size>
 122
 123 where <size> is the size from the cycbuff line in F<cycbuff.conf>.
 124 F<INSTALL> contains a script that will generate these commands for you
 125 from your F<cycbuff.conf> file.
 126
 127 This is the simplest method, but has the disadvantage that very large
 128 files on regular file systems can be fairly slow to access, particularly
 129 at the end of the file, and INN incurs unnecessary file system overhead
 130 when accessing the cycbuff.
 131
 132 =item 2.
 133
 134 Use block devices directly.  If your operating system allows you to call
 135 mmap() on block devices (Solaris and recent versions of Linux do, FreeBSD
 136 at last report does not), this is the recommended method since you can
 137 avoid all of the native file system overhead.  Note, however, that each
 138 cycbuff cannot be larger than 2GB with this method, so if you need a lot
 139 of spool space, you may have to go back to disk files.
 140
 141 Partition the disk to make each partition equal to or smaller than 2GB.
 142 If you're using Solaris, set up your partitions to avoid the first
 143 cylinder of the disk (or otherwise the cycbuff header will overwrite the
 144 disk partition table and render the cycbuffs inaccessible).  Then, create
 145 device files for each block device you're going to use.
 146
 147 It's not recommended to use the block device files in F</dev>, since the
 148 news system doesn't have permission to write to them and changing the
 149 permissions of the system device files may affect something else.
 150 Instead, use mknod(1) to create a new set of block devices (in somewhere
 151 like I<pathspool>/cycbuffs that's only writable by the news user).  To do
 152 this, run C<ls -Ll> on the devices in F</dev> that correspond to the block
 153 devices that you want to use.  The major and minor device numbers are in
 154 the fifth and sixth columns (right before the date), respectively.  Then
 155 run mknod like:
 156
 157     mknod <file> b <major> <minor>
 158
 159 where <file> is the path to the device to create (matching the <file> part
 160 of the cycbuff line) and <major> and <minor> are the major and minor
 161 device numbers as discovered above.
 162
 163 Here's a short script to do this when given the path to the system device
 164 file as an argument:
 165
 166     #!/bin/sh
 167     base=`echo "$1" | sed 's%.*/%%'`
 168     major=`ls -Ll "$1" | awk '{print $5}' | tr -d ,`
 169     minor=`ls -Ll "$1" | awk '{print $6}`
 170     mkdir -p /usr/local/news/spool/cycbuffs
 171     mknod /usr/local/news/spool/cycbuffs/"$base" b "$major" "$minor"
 172     chown news:news /usr/local/news/spool/cycbuffs/"$base"
 173     chmod 644 /usr/local/news/spool/cycbuffs/"$base"
 174
 175 Make sure that the created files are owned by the news user and news
 176 group, as specified at configure time (the default being C<news> for
 177 both).  Also make sure that the permissions on the devices allow the news
 178 user to read and write, and if you want other users on the system to be
 179 able to use B<sm> to retrieve articles, make sure they're world-readable.
 180
 181 =back
 182
 183 Once you have everything configured properly and you start B<innd>, you
 184 should see messages in F<news.notice> that look like:
 185
 186     innd: CNFS-sm No magic cookie found for cycbuff ONE, initializing
 187
 188 where ONE will be whatever you called your cycbuff.
 189
 190 =head1 HISTORY
 191
 192 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
 193 Rewritten into POD by Russ Allbery <rra@stanford.edu>.
 194
 195 $Id: cycbuff.conf.pod 7860 2008-06-07 12:46:49Z iulius $
 196
 197 =head1 SEE ALSO
 198
 199 ctlinnd(8), innd(8), nnrpd(8), sm(1), storage.conf(5)
 200
 201 =cut