doc/man/storage.conf.5

   1 .\" $Revision: 6124 $
   2 .TH STORAGE.CONF 5
   3 .SH NAME
   4 storage.conf \- configuration file for storage manager
   5 .SH DESCRIPTION
   6 The storage manager is a
   7 unified interface between INN and a variety of different storage method,
   8 allowing the news administrator to choose between different storage methods
   9 with different tradeoffs (or even use several at the same time for
  10 different newsgroups, or articles of different sizes).  The rest of INN
  11 need not care what type of storage method was used for a given article;
  12 the storage manager will figure this out automatically when that article
  13 is retrieved via the storage API.
  14 .PP
  15 The
  16 .I <pathetc in inn.conf>/storage.conf
  17 file contains the rules to be used in assigning
  18 articles to different storage methods.
  19 .PP
  20 The file consists of a series of storage method entries.
  21 Blank lines and lines beginning with a number sign (``#'') are ignored.
  22 The maximum number of characters in each line is 255.
  23 The order of entries in this file is important, see below.
  24 .PP
  25 Each entry specifies a storage method and a set of rules.  Articles that
  26 match all of the rules of a storage method entry will be stored using that
  27 storage method; if an article matches multiple storage method entries,
  28 the first will be used.  Each entry is formatted as follows:
  29 .RS
  30 .nf
  31
  32 method <methodname> {
  33         class: <storage_class>
  34         newsgroups: <wildmat>
  35         size: <minsize>[,<maxsize>]
  36         expires: <mintime>[,<maxtime>]
  37         options: <options>
  38         exactmatch: <bool>
  39 }
  40
  41 .fi
  42 .RE
  43 If spaces or tabs are included in a value, that value must be quoted
  44 with ``"''.
  45 If either ``#'' or ``"'' are meant to be included verbatim in a value,
  46 they should be escaped with ``\\''.
  47 .PP
  48 <methodname> is the name of a storage method to use for articles that
  49 match the rules of this entry.  The currently available storage methods
  50 are
  51 \&``timecaf'', ``timehash'', ``cnfs'', ``tradspool'' and ``trash''.
  52 See the STORAGE METHODS section below for more details.
  53 .PP
  54 The meanings of the keys in each entry are as follows:
  55 .TP
  56 .B class
  57 An identifier for this storage method entry.  <storage_class> should be a
  58 number and should be unique across all of the entries in this file.  It's
  59 used mainly for specifying expiration times by storage class as described in
  60 .IR expire.ctl (5).
  61 .TP
  62 .B newsgroups
  63 What newsgroups are stored using this storage method.  <wildmat> is a
  64 .IR uwildmat (3)
  65 pattern that is matched against the newsgroups an article is posted to.
  66 If ``storeonxref'' in inn.conf is ``true'', this pattern will be matched
  67 against the newsgroup names in the ``Xref'' header; otherwise, it will be
  68 matched against newsgroup names in the ``Newsgroups'' header (see
  69 .IR inn.conf (5)
  70 for discussion of the differences between these possibilities).  Poison
  71 wildmat expressions (expressions starting with ``@'') are allowed and can
  72 be used to exclude certain group patterns.  ``!'' cannot be used, however.
  73 The <wildmat> pattern is matched in order.  There is no default newsgroups
  74 pattern; if an entry should match all newsgroups, use an explicit
  75 \&``newsgroups: *''.
  76 .TP
  77 .B size
  78 A range of article sizes (in bytes) that should be stored using this
  79 storage method.
  80 If <maxsize> is ``0'' or not given, the upper size of articles is limited
  81 only by ``maxartsize'' in
  82 .IR inn.conf .
  83 The ``size'' field is optional and may be omitted entirely if you want
  84 articles of any size (that otherwise fulfill the requirements of this
  85 storage method entry) to be stored in this storage method.
  86 .TP
  87 .B expires
  88 A range of article expiration times that should be stored using this
  89 storage method.  Be careful; this is less useful than it may appear at
  90 first.  This is based
  91 .B only
  92 on the ``Expires'' header of the article, not on any local expiration
  93 policies or anything in
  94 .IR expire.ctl !
  95 If <mintime> is non-zero, then this entry
  96 .B will not match
  97 any article without an ``Expires'' header.
  98 This key is therefore only really useful for assigning articles with
  99 requested longer expire times to a separate storage method.  Articles only
 100 match if the time until expiration (that is, the amount of time into the
 101 future that the ``Expires'' header of the article requests that it remain
 102 around) falls in the interval specified by <mintime> and <maxtime>.  The
 103 format of these parameters is 0d0h0m0s (days, hours, minutes, and
 104 seconds into the future).  If <maxtime> is ``0s'' or is not specified,
 105 there is no upper bound on expire times falling into this entry (note that
 106 this key has no effect on when the article will actually be expired, only
 107 on whether or not the article will be stored using this storage method).
 108 This field is also optional and may be omitted entirely if all articles
 109 with or without an ``Expires'' header (that otherwise fulfill the
 110 requirements of this storage method entry) should be stored according to
 111 it.
 112 .TP
 113 .B options
 114 This key is for passing special options to storage methods that require
 115 them (currently only ``cnfs'').  See the STORAGE METHODS section below for
 116 a description of its use.
 117 .TP
 118 .B exactmatch
 119 If this key is set to ``true'', all newsgroups will be examined to see if
 120 they match newsgroups patterns.  (Normally, any nonzero number of matching
 121 newsgroups is sufficient, provided no newsgroup matches a poison wildmat as
 122 described above.)  This is a boolan value and ``true'', ``yes''
 123 and ``on'' are usable to enable this key.  The case of these values is not
 124 significant.  The default is false.
 125 .PP
 126 If an article matches all of the constraints of an entry, it is stored via
 127 that storage method and is associated with that <storage_class>.  This
 128 file is scanned in order and the first matching entry is used to store the
 129 article.
 130 .PP
 131 If an article doesn't match any entry, either by being posted to a
 132 newsgroup that doesn't match any of the <wildmat> patterns or by being
 133 outside the size and expires ranges of all entries whose newsgroups
 134 pattern it does match, the article is not stored and is rejected by
 135 .IR innd (8).
 136 When this happens, the error message
 137 .RS
 138 .nf
 139
 140 cant store article: no matching entry in storage.conf
 141
 142 .fi
 143 .RE
 144 is logged to syslog.  If you want to silently drop articles matching
 145 certain newsgroup patterns or size or expires ranges, assign them to the
 146 \&``trash'' storage method rather than having them not match any storage
 147 method entry.
 148 .SH STORAGE METHODS
 149 Currently, there are four storage methods available.  Each method has its
 150 pros and cons; you can choose any mixture of them as is suitable for your
 151 environment.  Note that each method has an attribute ``EXPENSIVESTAT'' which
 152 indicates  whether checking the existence of an article is expensive or not.
 153 This is used to run
 154 .IR expireover (8).
 155 .TP
 156 .B cnfs
 157 The ``cnfs'' storage method stores articles in large cyclic buffers (CNFS
 158 stands for Cyclic News File System).  It's by far the fastest of all
 159 storage methods (except for ``trash''), since it eliminates the overhead
 160 of dealing with a file system and creating new files.  Articles are stored
 161 in CNFS buffers in arrival order, and when the buffer fills, it wraps
 162 around to the beginning and stores new articles over top of the oldest
 163 articles in the buffer.  The expire time of articles stored in CNFS
 164 buffers is therefore entirely determined by how long it takes the buffer
 165 to wrap around, which depends on how quickly data is being stored in it.
 166 (This method is therefore said to have self-expire functionality.)
 167 \&``EXPENSIVESTAT'' is ``false'' for this method.
 168 CNFS has its own configuration file,
 169 .IR cycbuff.conf ,
 170 which describes some subtlties to the basic description given above.
 171 Storage method entries for the ``cnfs'' storage method must have an
 172 \&``options'' field specifying the metacycbuff into which articles
 173 matching that entry should be stored; see
 174 .IR cycbuff.conf (5)
 175 for details on metacycbuffs.
 176 .TP
 177 .B timecaf
 178 This method stores multiple articles in one file, whose name is based on
 179 the article's arrival time and the storage class.  The file name will be
 180 .IR <patharticles\ in\ inn.conf>/timecaf-nn/bb/aacc.CF ,
 181 where ``nn'' is the hexadecimal value of <storage_class>, ``bb'' and
 182 \&``aacc'' are hexadecimal components of the arrival time, and ``CF'' is a
 183 hardcoded extension.  (The arrival time, in seconds since the epoch, is
 184 converted to hexadecimal and interpreted as 0xaabbccdd, with ``aa'',
 185 ``bb'', and ``cc'' used to build the path.)  This method does not have
 186 self-expire functionality (meaning
 187 .IR expire (8)
 188 has to run periodically to delete old articles).
 189 \&``EXPENSIVESTAT'' is ``false'' for this method.
 190 .TP
 191 .B timehash
 192 This method is very similar to ``timecaf'' except that each article is
 193 stored in a separate file.  The name of the file for a given article will
 194 be
 195 .IR <patharticles\ in\ inn.conf>/time-nn/bb/cc/yyyy-aadd ,
 196 where ``nn'' is the hexadecimal value of <storage_class>, ``yyyy'' is a
 197 hexadecimal sequence number, and ``bb'', ``cc'', and ``aadd'' are
 198 components of the arrival time in hexadecimal (the arrival time is
 199 interpreted as documented above under ``timecaf'').  This method does not
 200 have self-expire functionality.
 201 \&``EXPENSIVESTAT'' is ``true'' for this method.
 202 .TP
 203 .B tradspool
 204 Traditional spool, or ``tradspool'', is the traditional news article
 205 storage format.  Each article is stored in a file named:
 206 .IR <patharticles\ in\ inn.conf>/news/group/name/nnnnn ,
 207 where ``news/group/name'' is the name of the newsgroup to which the
 208 article was posted with each period changed to a slash, and ``nnnnn'' is
 209 the sequence number of the article in that newsgroup.  For crossposted
 210 articles, the article is linked into each newsgroup to which it is
 211 crossposted (using either hard or symbolic links).  This is the way
 212 versions of INN prior to 2.0 stored all articles, as well as being the
 213 article storage format used by C News and earlier news systems.
 214 This method does not have self-expire functionality.
 215 \&``EXPENSIVESTAT'' is ``true'' for this method.
 216 .TP
 217 .B trash
 218 This method silently discards all articles stored in it.  Its only real
 219 uses are for testing and for silently discarding articles matching a
 220 particular storage method entry (for whatever reason).  Articles stored in
 221 this method take up no disk space and can never be retrieved, so this
 222 method has self-expire functionality of a sort.
 223 \&``EXPENSIVESTAT'' is ``false'' for this method.
 224 .SH EXAMPLE
 225 The following sample storage.conf file would store all articles posted to
 226 alt.binaries.* in the ``BINARIES'' CNFS metacycbuff, all articles over
 227 roughly 50 KB in any other hierarchy in the ``LARGE'' CNFS metacycbuff,
 228 all other articles in alt.* in one timehash class, and all other articles
 229 in any newsgroups in a second timehash class, except for the internal.*
 230 hierarchy which is stored in traditional spool format.
 231 .RS
 232 .nf
 233
 234 method tradspool {
 235     class: 1
 236     newsgroups: internal.*
 237 }
 238
 239 method cnfs {
 240     class: 2
 241     newsgroups: alt.binaries.*
 242     options: BINARIES
 243 }
 244
 245 method cnfs {
 246     class: 3
 247     newsgroups: *
 248     size: 50000
 249     options: LARGE
 250 }
 251
 252 method timehash {
 253     class: 4
 254     newsgroups: alt.*
 255 }
 256
 257 method timehash {
 258     class: 5
 259     newsgroups: *
 260 }
 261
 262 .fi
 263 .RE
 264 Notice that the last storage method entry will catch everything.  This is
 265 a good habit to get into; make sure that you have at least one catch-all
 266 entry just in case something you didn't expect falls through the cracks.
 267 Notice also that the special rule for the internal.* hierarchy is first,
 268 so it will catch even articles crossposted to alt.binaries.* or over 50 KB
 269 in size.
 270 .SH HISTORY
 271 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
 272 .de R$
 273 This is revision \\$3, dated \\$4.
 274 ..
 275 .R$ $Id: storage.conf.5 6124 2003-01-14 06:03:29Z rra $
 276 .SH "SEE ALSO"
 277 cycbuff.conf(5),
 278 expire.ctl(5),
 279 inn.conf(5),
 280 innd(8),
 281 newsfeeds(5),
 282 uwildmat(3).