.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CYCBUFF.CONF 5" .TH CYCBUFF.CONF 5 "2008-06-07" "INN 2.4.5" "InterNetNews Documentation" .SH "NAME" cycbuff.conf \- Configuration file for INN CNFS storage method .SH "DESCRIPTION" .IX Header "DESCRIPTION" This file defines the cyclical buffers that make up the storage pools for \&\s-1CNFS\s0 (Cyclic News File System). Some options controlling the behavior of the \s-1CNFS\s0 storage system can also be set here. \fIcycbuff.conf\fR is required if the \s-1CNFS\s0 (Cyclic News File System) storage method is used. \s-1INN\s0 will look for it in \fIpathetc\fR (as set in \fIinn.conf\fR). .PP For information about how to configure \s-1INN\s0 to use \s-1CNFS\s0, see \&\fIstorage.conf\fR\|(5). .PP Blank lines and lines beginning with a hash sign (\f(CW\*(C`#\*(C'\fR) are ignored. All other lines must be of one of the following forms: .PP .Vb 4 \& cycbuffupdate: \& refreshinterval: \& cycbuff::: \& metacycbuff::[,,...][:] .Ve .PP (where items enclosed in [] are optional). Order is mostly not significant, but all \fIcycbuff\fR lines must occur before all \fImetacycbuff\fR lines. Long lines can be continued on the next line by ending the line with a backslash (\f(CW\*(C`\e\*(C'\fR). .IP "cycbuffupdate:" 4 .IX Item "cycbuffupdate:" Sets the number of articles are written before the cycbuff header is written back to disk to . 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 \s-1CNFS\s0, but any accesses to the \s-1CNFS\s0 cycbuffs over \s-1NFS\s0 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 \s-1CNFS\s0 header may be lost. The default value, if this line is omitted, is 25, meaning that the header is written to disk after every 25 articles stored in that cycbuff. .IP "refreshinterval:" 4 .IX Item "refreshinterval:" Sets the interval (in seconds) between re-reads of the cycbuff header to . This primarily affects \fBnnrpd\fR and controls the frequency with which it updates its knowledge of the current contents of the \s-1CNFS\s0 cycbuffs. The default value, if this line is omitted, is 30. .IP "cycbuff:::" 4 .IX Item "cycbuff:::" Configures a particular \s-1CNFS\s0 cycbuff. is a symbolic name for the buffer, to be used later in a metacycbuff line. It must be no longer than seven characters. is the full path to the buffer file or block device, and must be no longer than 63 characters. is the length of the buffer in kilobytes (1KB is 1024 bytes). If is not a block device, it should be * 1024 bytes long. .IP "metacycbuff::[,,...][:]" 4 .IX Item "metacycbuff::[,,...][:]" Specifies a collection of \s-1CNFS\s0 buffers that make up a single logical storage location from the perspective of \s-1INN\s0. Metacycbuffs are referred to in \fIstorage.conf\fR as storage locations for articles, so in order to actually put articles in a cycbuff, it has to be listed as part of some metacycbuff which is then referenced in \fIstorage.conf\fR. .Sp is the symbolic name of the metacycbuff, referred to in the options field of cnfs entries in \fIstorage.conf\fR. is the name of a cycbuff (the part of a cycbuff line), and any number of cycbuffs may be specified, separated by commas. .Sp If there is more than one cycbuff in a metacycbuff, there are two ways that \s-1INN\s0 can distribute articles between the cycbuffs. The default mode, \&\s-1INTERLEAVE\s0, 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, \s-1SEQUENTIAL\s0, 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 (\s-1INTERLEAVE\s0 or \s-1SEQUENTIAL\s0) at the end of the metacycbuff line. .PP \&\fBinnd\fR only reads \fIcycbuff.conf\fR on startup, so if you change anything in this file and want \fBinnd\fR to pick up the changes, you have to stop and restart it. \f(CW\*(C`ctlinnd reload all ''\*(C'\fR is not sufficient. .PP When articles are stored, the cycbuff into which they're stored is saved as part of the article token. In order for \s-1INN\s0 to retrieve articles from a cycbuff, that cycbuff must be listed in \fIcycbuff.conf\fR. However, if \&\s-1INN\s0 should not write to a cycbuff, it doesn't need to be (and shouldn't be) listed in a metacycbuff. .PP This provides an easy way to retire a cycbuff. Just remove it from its metacycbuff, leaving in the cycbuff line, and restart \fBinnd\fR (with, for example, \f(CW\*(C`ctlinnd xexec innd\*(C'\fR). No new articles will be put into the cycbuff, but neither will any articles expire from it. After you no longer need the articles in the cycbuff, just remove it entirely from \&\fIcycbuff.conf\fR. Then all of the articles will appear to have been deleted to \s-1INN\s0, and the next nightly expire run will clean up any remaining references to them. .PP Adding a new cycbuff just requires creating it (see below), adding a cycbuff line, adding it to a metacycbuff, and then restarting \fBinnd\fR. .SH "CREATING CYCBUFFS" .IX Header "CREATING CYCBUFFS" When creating a new cycbuff, there are two different methods for creating the buffers in which the articles will be stored. .IP "1." 4 Create a large file on top of a regular file system. The easiest way to do this is probably with \fIdd\fR\|(1), using a command like: .Sp .Vb 1 \& dd if=/dev/zero of=/path/to/cycbuff bs=1024 count= .Ve .Sp where is the size from the cycbuff line in \fIcycbuff.conf\fR. \&\fI\s-1INSTALL\s0\fR contains a script that will generate these commands for you from your \fIcycbuff.conf\fR file. .Sp This is the simplest method, but has the disadvantage that very large files on regular file systems can be fairly slow to access, particularly at the end of the file, and \s-1INN\s0 incurs unnecessary file system overhead when accessing the cycbuff. .IP "2." 4 Use block devices directly. If your operating system allows you to call \&\fImmap()\fR on block devices (Solaris and recent versions of Linux do, FreeBSD at last report does not), this is the recommended method since you can avoid all of the native file system overhead. Note, however, that each cycbuff cannot be larger than 2GB with this method, so if you need a lot of spool space, you may have to go back to disk files. .Sp Partition the disk to make each partition equal to or smaller than 2GB. If you're using Solaris, set up your partitions to avoid the first cylinder of the disk (or otherwise the cycbuff header will overwrite the disk partition table and render the cycbuffs inaccessible). Then, create device files for each block device you're going to use. .Sp It's not recommended to use the block device files in \fI/dev\fR, since the news system doesn't have permission to write to them and changing the permissions of the system device files may affect something else. Instead, use \fImknod\fR\|(1) to create a new set of block devices (in somewhere like \fIpathspool\fR/cycbuffs that's only writable by the news user). To do this, run \f(CW\*(C`ls \-Ll\*(C'\fR on the devices in \fI/dev\fR that correspond to the block devices that you want to use. The major and minor device numbers are in the fifth and sixth columns (right before the date), respectively. Then run mknod like: .Sp .Vb 1 \& mknod b .Ve .Sp where is the path to the device to create (matching the part of the cycbuff line) and and are the major and minor device numbers as discovered above. .Sp Here's a short script to do this when given the path to the system device file as an argument: .Sp .Vb 8 \& #!/bin/sh \& base=`echo "$1" | sed 's%.*/%%'` \& major=`ls \-Ll "$1" | awk '{print $5}' | tr \-d ,` \& minor=`ls \-Ll "$1" | awk '{print $6}` \& mkdir \-p /usr/local/news/spool/cycbuffs \& mknod /usr/local/news/spool/cycbuffs/"$base" b "$major" "$minor" \& chown news:news /usr/local/news/spool/cycbuffs/"$base" \& chmod 644 /usr/local/news/spool/cycbuffs/"$base" .Ve .Sp Make sure that the created files are owned by the news user and news group, as specified at configure time (the default being \f(CW\*(C`news\*(C'\fR for both). Also make sure that the permissions on the devices allow the news user to read and write, and if you want other users on the system to be able to use \fBsm\fR to retrieve articles, make sure they're world\-readable. .PP Once you have everything configured properly and you start \fBinnd\fR, you should see messages in \fInews.notice\fR that look like: .PP .Vb 1 \& innd: CNFS\-sm No magic cookie found for cycbuff ONE, initializing .Ve .PP where \s-1ONE\s0 will be whatever you called your cycbuff. .SH "HISTORY" .IX Header "HISTORY" Written by Katsuhiro Kondou for InterNetNews. Rewritten into \s-1POD\s0 by Russ Allbery . .PP $Id: cycbuff.conf.5 7880 2008-06-16 20:37:13Z iulius $ .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIctlinnd\fR\|(8), \fIinnd\fR\|(8), \fInnrpd\fR\|(8), \fIsm\fR\|(1), \fIstorage.conf\fR\|(5)