doc/man/cycbuff.conf.5

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "CYCBUFF.CONF 5"
 132 .TH CYCBUFF.CONF 5 "2008-06-07" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 cycbuff.conf \- Configuration file for INN CNFS storage method
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 This file defines the cyclical buffers that make up the storage pools for
 138 \&\s-1CNFS\s0 (Cyclic News File System).  Some options controlling the behavior of
 139 the \s-1CNFS\s0 storage system can also be set here.  \fIcycbuff.conf\fR is required
 140 if the \s-1CNFS\s0 (Cyclic News File System) storage method is used.  \s-1INN\s0 will
 141 look for it in \fIpathetc\fR (as set in \fIinn.conf\fR).
 142 .PP
 143 For information about how to configure \s-1INN\s0 to use \s-1CNFS\s0, see
 144 \&\fIstorage.conf\fR\|(5).
 145 .PP
 146 Blank lines and lines beginning with a hash sign (\f(CW\*(C`#\*(C'\fR) are ignored.  All
 147 other lines must be of one of the following forms:
 148 .PP
 149 .Vb 4
 150 \&    cycbuffupdate:<interval>
 151 \&    refreshinterval:<interval>
 152 \&    cycbuff:<name>:<file>:<size>
 153 \&    metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]
 154 .Ve
 155 .PP
 156 (where items enclosed in [] are optional).  Order is mostly not
 157 significant, but all \fIcycbuff\fR lines must occur before all \fImetacycbuff\fR
 158 lines.  Long lines can be continued on the next line by ending the line
 159 with a backslash (\f(CW\*(C`\e\*(C'\fR).
 160 .IP "cycbuffupdate:<interval>" 4
 161 .IX Item "cycbuffupdate:<interval>"
 162 Sets the number of articles are written before the cycbuff header is
 163 written back to disk to <interval>.  Under most operating systems, the
 164 header doesn't have to be written to disk for the updated data to be
 165 available to other processes on the same system that are reading articles
 166 out of \s-1CNFS\s0, but any accesses to the \s-1CNFS\s0 cycbuffs over \s-1NFS\s0 will only see
 167 the data present at the last write of the header.  After a system crash,
 168 all updates since the last write of the \s-1CNFS\s0 header may be lost.  The
 169 default value, if this line is omitted, is 25, meaning that the header is
 170 written to disk after every 25 articles stored in that cycbuff.
 171 .IP "refreshinterval:<interval>" 4
 172 .IX Item "refreshinterval:<interval>"
 173 Sets the interval (in seconds) between re-reads of the cycbuff header to
 174 <interval>.  This primarily affects \fBnnrpd\fR and controls the frequency
 175 with which it updates its knowledge of the current contents of the \s-1CNFS\s0
 176 cycbuffs.  The default value, if this line is omitted, is 30.
 177 .IP "cycbuff:<name>:<file>:<size>" 4
 178 .IX Item "cycbuff:<name>:<file>:<size>"
 179 Configures a particular \s-1CNFS\s0 cycbuff.  <name> is a symbolic name for the
 180 buffer, to be used later in a metacycbuff line.  It must be no longer than
 181 seven characters.  <file> is the full path to the buffer file or block
 182 device, and must be no longer than 63 characters.  <size> is the length of
 183 the buffer in kilobytes (1KB is 1024 bytes).  If <file> is not a block
 184 device, it should be <size> * 1024 bytes long.
 185 .IP "metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]" 4
 186 .IX Item "metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]"
 187 Specifies a collection of \s-1CNFS\s0 buffers that make up a single logical
 188 storage location from the perspective of \s-1INN\s0.  Metacycbuffs are referred
 189 to in \fIstorage.conf\fR as storage locations for articles, so in order to
 190 actually put articles in a cycbuff, it has to be listed as part of some
 191 metacycbuff which is then referenced in \fIstorage.conf\fR.
 192 .Sp
 193 <name> is the symbolic name of the metacycbuff, referred to in the options
 194 field of cnfs entries in \fIstorage.conf\fR.  <buffer> is the name of a
 195 cycbuff (the <name> part of a cycbuff line), and any number of cycbuffs
 196 may be specified, separated by commas.
 197 .Sp
 198 If there is more than one cycbuff in a metacycbuff, there are two ways
 199 that \s-1INN\s0 can distribute articles between the cycbuffs.  The default mode,
 200 \&\s-1INTERLEAVE\s0, stores the articles in each cycbuff in a round-robin fashion,
 201 one article per cycbuff in the order listed.  If the cycbuffs are of
 202 wildly different sizes, this can cause some of them to roll over much
 203 faster than others, and it may not give the best performance depending on
 204 your disk layout.  The other storage mode, \s-1SEQUENTIAL\s0, instead writes to
 205 each cycbuff in turn until that cycbuff is full and then moves on to the
 206 next one, returning to the first and starting a new cycle when the last
 207 one is full.  To specify a mode rather than leaving it at the default, add
 208 a colon and the mode (\s-1INTERLEAVE\s0 or \s-1SEQUENTIAL\s0) at the end of the
 209 metacycbuff line.
 210 .PP
 211 \&\fBinnd\fR only reads \fIcycbuff.conf\fR on startup, so if you change anything
 212 in this file and want \fBinnd\fR to pick up the changes, you have to stop and
 213 restart it.  \f(CW\*(C`ctlinnd reload all ''\*(C'\fR is not sufficient.
 214 .PP
 215 When articles are stored, the cycbuff into which they're stored is saved
 216 as part of the article token.  In order for \s-1INN\s0 to retrieve articles from
 217 a cycbuff, that cycbuff must be listed in \fIcycbuff.conf\fR.  However, if
 218 \&\s-1INN\s0 should not write to a cycbuff, it doesn't need to be (and shouldn't
 219 be) listed in a metacycbuff.
 220 .PP
 221 This provides an easy way to retire a cycbuff.  Just remove it from its
 222 metacycbuff, leaving in the cycbuff line, and restart \fBinnd\fR (with, for
 223 example, \f(CW\*(C`ctlinnd xexec innd\*(C'\fR).  No new articles will be put into the
 224 cycbuff, but neither will any articles expire from it.  After you no
 225 longer need the articles in the cycbuff, just remove it entirely from
 226 \&\fIcycbuff.conf\fR.  Then all of the articles will appear to have been
 227 deleted to \s-1INN\s0, and the next nightly expire run will clean up any
 228 remaining references to them.
 229 .PP
 230 Adding a new cycbuff just requires creating it (see below), adding a
 231 cycbuff line, adding it to a metacycbuff, and then restarting \fBinnd\fR.
 232 .SH "CREATING CYCBUFFS"
 233 .IX Header "CREATING CYCBUFFS"
 234 When creating a new cycbuff, there are two different methods for creating
 235 the buffers in which the articles will be stored.
 236 .IP "1." 4
 237 Create a large file on top of a regular file system.  The easiest way to
 238 do this is probably with \fIdd\fR\|(1), using a command like:
 239 .Sp
 240 .Vb 1
 241 \&    dd if=/dev/zero of=/path/to/cycbuff bs=1024 count=<size>
 242 .Ve
 243 .Sp
 244 where <size> is the size from the cycbuff line in \fIcycbuff.conf\fR.
 245 \&\fI\s-1INSTALL\s0\fR contains a script that will generate these commands for you
 246 from your \fIcycbuff.conf\fR file.
 247 .Sp
 248 This is the simplest method, but has the disadvantage that very large
 249 files on regular file systems can be fairly slow to access, particularly
 250 at the end of the file, and \s-1INN\s0 incurs unnecessary file system overhead
 251 when accessing the cycbuff.
 252 .IP "2." 4
 253 Use block devices directly.  If your operating system allows you to call
 254 \&\fImmap()\fR on block devices (Solaris and recent versions of Linux do, FreeBSD
 255 at last report does not), this is the recommended method since you can
 256 avoid all of the native file system overhead.  Note, however, that each
 257 cycbuff cannot be larger than 2GB with this method, so if you need a lot
 258 of spool space, you may have to go back to disk files.
 259 .Sp
 260 Partition the disk to make each partition equal to or smaller than 2GB.
 261 If you're using Solaris, set up your partitions to avoid the first
 262 cylinder of the disk (or otherwise the cycbuff header will overwrite the
 263 disk partition table and render the cycbuffs inaccessible).  Then, create
 264 device files for each block device you're going to use.
 265 .Sp
 266 It's not recommended to use the block device files in \fI/dev\fR, since the
 267 news system doesn't have permission to write to them and changing the
 268 permissions of the system device files may affect something else.
 269 Instead, use \fImknod\fR\|(1) to create a new set of block devices (in somewhere
 270 like \fIpathspool\fR/cycbuffs that's only writable by the news user).  To do
 271 this, run \f(CW\*(C`ls \-Ll\*(C'\fR on the devices in \fI/dev\fR that correspond to the block
 272 devices that you want to use.  The major and minor device numbers are in
 273 the fifth and sixth columns (right before the date), respectively.  Then
 274 run mknod like:
 275 .Sp
 276 .Vb 1
 277 \&    mknod <file> b <major> <minor>
 278 .Ve
 279 .Sp
 280 where <file> is the path to the device to create (matching the <file> part
 281 of the cycbuff line) and <major> and <minor> are the major and minor
 282 device numbers as discovered above.
 283 .Sp
 284 Here's a short script to do this when given the path to the system device
 285 file as an argument:
 286 .Sp
 287 .Vb 8
 288 \&    #!/bin/sh
 289 \&    base=`echo "$1" | sed 's%.*/%%'`
 290 \&    major=`ls \-Ll "$1" | awk '{print $5}' | tr \-d ,`
 291 \&    minor=`ls \-Ll "$1" | awk '{print $6}`
 292 \&    mkdir \-p /usr/local/news/spool/cycbuffs
 293 \&    mknod /usr/local/news/spool/cycbuffs/"$base" b "$major" "$minor"
 294 \&    chown news:news /usr/local/news/spool/cycbuffs/"$base"
 295 \&    chmod 644 /usr/local/news/spool/cycbuffs/"$base"
 296 .Ve
 297 .Sp
 298 Make sure that the created files are owned by the news user and news
 299 group, as specified at configure time (the default being \f(CW\*(C`news\*(C'\fR for
 300 both).  Also make sure that the permissions on the devices allow the news
 301 user to read and write, and if you want other users on the system to be
 302 able to use \fBsm\fR to retrieve articles, make sure they're world\-readable.
 303 .PP
 304 Once you have everything configured properly and you start \fBinnd\fR, you
 305 should see messages in \fInews.notice\fR that look like:
 306 .PP
 307 .Vb 1
 308 \&    innd: CNFS\-sm No magic cookie found for cycbuff ONE, initializing
 309 .Ve
 310 .PP
 311 where \s-1ONE\s0 will be whatever you called your cycbuff.
 312 .SH "HISTORY"
 313 .IX Header "HISTORY"
 314 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
 315 Rewritten into \s-1POD\s0 by Russ Allbery <rra@stanford.edu>.
 316 .PP
 317 $Id: cycbuff.conf.5 7880 2008-06-16 20:37:13Z iulius $
 318 .SH "SEE ALSO"
 319 .IX Header "SEE ALSO"
 320 \&\fIctlinnd\fR\|(8), \fIinnd\fR\|(8), \fInnrpd\fR\|(8), \fIsm\fR\|(1), \fIstorage.conf\fR\|(5)