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