X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=innduct.git;a=blobdiff_plain;f=doc%2Fman%2Fstorage.conf.5;fp=doc%2Fman%2Fstorage.conf.5;h=0000000000000000000000000000000000000000;hp=fd47384dcf72e672560ead4a9310f47022b537ca;hb=b7a32e2d73e3ab1add8208d3e157f7269a31ef4d;hpb=ac902a8299ff4469b356836f431ead31c3377377 diff --git a/doc/man/storage.conf.5 b/doc/man/storage.conf.5 deleted file mode 100644 index fd47384..0000000 --- a/doc/man/storage.conf.5 +++ /dev/null @@ -1,282 +0,0 @@ -.\" $Revision: 6124 $ -.TH STORAGE.CONF 5 -.SH NAME -storage.conf \- configuration file for storage manager -.SH DESCRIPTION -The storage manager is a -unified interface between INN and a variety of different storage method, -allowing the news administrator to choose between different storage methods -with different tradeoffs (or even use several at the same time for -different newsgroups, or articles of different sizes). The rest of INN -need not care what type of storage method was used for a given article; -the storage manager will figure this out automatically when that article -is retrieved via the storage API. -.PP -The -.I /storage.conf -file contains the rules to be used in assigning -articles to different storage methods. -.PP -The file consists of a series of storage method entries. -Blank lines and lines beginning with a number sign (``#'') are ignored. -The maximum number of characters in each line is 255. -The order of entries in this file is important, see below. -.PP -Each entry specifies a storage method and a set of rules. Articles that -match all of the rules of a storage method entry will be stored using that -storage method; if an article matches multiple storage method entries, -the first will be used. Each entry is formatted as follows: -.RS -.nf - -method { - class: - newsgroups: - size: [,] - expires: [,] - options: - exactmatch: -} - -.fi -.RE -If spaces or tabs are included in a value, that value must be quoted -with ``"''. -If either ``#'' or ``"'' are meant to be included verbatim in a value, -they should be escaped with ``\\''. -.PP - is the name of a storage method to use for articles that -match the rules of this entry. The currently available storage methods -are -\&``timecaf'', ``timehash'', ``cnfs'', ``tradspool'' and ``trash''. -See the STORAGE METHODS section below for more details. -.PP -The meanings of the keys in each entry are as follows: -.TP -.B class -An identifier for this storage method entry. should be a -number and should be unique across all of the entries in this file. It's -used mainly for specifying expiration times by storage class as described in -.IR expire.ctl (5). -.TP -.B newsgroups -What newsgroups are stored using this storage method. is a -.IR uwildmat (3) -pattern that is matched against the newsgroups an article is posted to. -If ``storeonxref'' in inn.conf is ``true'', this pattern will be matched -against the newsgroup names in the ``Xref'' header; otherwise, it will be -matched against newsgroup names in the ``Newsgroups'' header (see -.IR inn.conf (5) -for discussion of the differences between these possibilities). Poison -wildmat expressions (expressions starting with ``@'') are allowed and can -be used to exclude certain group patterns. ``!'' cannot be used, however. -The pattern is matched in order. There is no default newsgroups -pattern; if an entry should match all newsgroups, use an explicit -\&``newsgroups: *''. -.TP -.B size -A range of article sizes (in bytes) that should be stored using this -storage method. -If is ``0'' or not given, the upper size of articles is limited -only by ``maxartsize'' in -.IR inn.conf . -The ``size'' field is optional and may be omitted entirely if you want -articles of any size (that otherwise fulfill the requirements of this -storage method entry) to be stored in this storage method. -.TP -.B expires -A range of article expiration times that should be stored using this -storage method. Be careful; this is less useful than it may appear at -first. This is based -.B only -on the ``Expires'' header of the article, not on any local expiration -policies or anything in -.IR expire.ctl ! -If is non-zero, then this entry -.B will not match -any article without an ``Expires'' header. -This key is therefore only really useful for assigning articles with -requested longer expire times to a separate storage method. Articles only -match if the time until expiration (that is, the amount of time into the -future that the ``Expires'' header of the article requests that it remain -around) falls in the interval specified by and . The -format of these parameters is 0d0h0m0s (days, hours, minutes, and -seconds into the future). If is ``0s'' or is not specified, -there is no upper bound on expire times falling into this entry (note that -this key has no effect on when the article will actually be expired, only -on whether or not the article will be stored using this storage method). -This field is also optional and may be omitted entirely if all articles -with or without an ``Expires'' header (that otherwise fulfill the -requirements of this storage method entry) should be stored according to -it. -.TP -.B options -This key is for passing special options to storage methods that require -them (currently only ``cnfs''). See the STORAGE METHODS section below for -a description of its use. -.TP -.B exactmatch -If this key is set to ``true'', all newsgroups will be examined to see if -they match newsgroups patterns. (Normally, any nonzero number of matching -newsgroups is sufficient, provided no newsgroup matches a poison wildmat as -described above.) This is a boolan value and ``true'', ``yes'' -and ``on'' are usable to enable this key. The case of these values is not -significant. The default is false. -.PP -If an article matches all of the constraints of an entry, it is stored via -that storage method and is associated with that . This -file is scanned in order and the first matching entry is used to store the -article. -.PP -If an article doesn't match any entry, either by being posted to a -newsgroup that doesn't match any of the patterns or by being -outside the size and expires ranges of all entries whose newsgroups -pattern it does match, the article is not stored and is rejected by -.IR innd (8). -When this happens, the error message -.RS -.nf - -cant store article: no matching entry in storage.conf - -.fi -.RE -is logged to syslog. If you want to silently drop articles matching -certain newsgroup patterns or size or expires ranges, assign them to the -\&``trash'' storage method rather than having them not match any storage -method entry. -.SH STORAGE METHODS -Currently, there are four storage methods available. Each method has its -pros and cons; you can choose any mixture of them as is suitable for your -environment. Note that each method has an attribute ``EXPENSIVESTAT'' which -indicates whether checking the existence of an article is expensive or not. -This is used to run -.IR expireover (8). -.TP -.B cnfs -The ``cnfs'' storage method stores articles in large cyclic buffers (CNFS -stands for Cyclic News File System). It's by far the fastest of all -storage methods (except for ``trash''), since it eliminates the overhead -of dealing with a file system and creating new files. Articles are stored -in CNFS buffers in arrival order, and when the buffer fills, it wraps -around to the beginning and stores new articles over top of the oldest -articles in the buffer. The expire time of articles stored in CNFS -buffers is therefore entirely determined by how long it takes the buffer -to wrap around, which depends on how quickly data is being stored in it. -(This method is therefore said to have self-expire functionality.) -\&``EXPENSIVESTAT'' is ``false'' for this method. -CNFS has its own configuration file, -.IR cycbuff.conf , -which describes some subtlties to the basic description given above. -Storage method entries for the ``cnfs'' storage method must have an -\&``options'' field specifying the metacycbuff into which articles -matching that entry should be stored; see -.IR cycbuff.conf (5) -for details on metacycbuffs. -.TP -.B timecaf -This method stores multiple articles in one file, whose name is based on -the article's arrival time and the storage class. The file name will be -.IR /timecaf-nn/bb/aacc.CF , -where ``nn'' is the hexadecimal value of , ``bb'' and -\&``aacc'' are hexadecimal components of the arrival time, and ``CF'' is a -hardcoded extension. (The arrival time, in seconds since the epoch, is -converted to hexadecimal and interpreted as 0xaabbccdd, with ``aa'', -``bb'', and ``cc'' used to build the path.) This method does not have -self-expire functionality (meaning -.IR expire (8) -has to run periodically to delete old articles). -\&``EXPENSIVESTAT'' is ``false'' for this method. -.TP -.B timehash -This method is very similar to ``timecaf'' except that each article is -stored in a separate file. The name of the file for a given article will -be -.IR /time-nn/bb/cc/yyyy-aadd , -where ``nn'' is the hexadecimal value of , ``yyyy'' is a -hexadecimal sequence number, and ``bb'', ``cc'', and ``aadd'' are -components of the arrival time in hexadecimal (the arrival time is -interpreted as documented above under ``timecaf''). This method does not -have self-expire functionality. -\&``EXPENSIVESTAT'' is ``true'' for this method. -.TP -.B tradspool -Traditional spool, or ``tradspool'', is the traditional news article -storage format. Each article is stored in a file named: -.IR /news/group/name/nnnnn , -where ``news/group/name'' is the name of the newsgroup to which the -article was posted with each period changed to a slash, and ``nnnnn'' is -the sequence number of the article in that newsgroup. For crossposted -articles, the article is linked into each newsgroup to which it is -crossposted (using either hard or symbolic links). This is the way -versions of INN prior to 2.0 stored all articles, as well as being the -article storage format used by C News and earlier news systems. -This method does not have self-expire functionality. -\&``EXPENSIVESTAT'' is ``true'' for this method. -.TP -.B trash -This method silently discards all articles stored in it. Its only real -uses are for testing and for silently discarding articles matching a -particular storage method entry (for whatever reason). Articles stored in -this method take up no disk space and can never be retrieved, so this -method has self-expire functionality of a sort. -\&``EXPENSIVESTAT'' is ``false'' for this method. -.SH EXAMPLE -The following sample storage.conf file would store all articles posted to -alt.binaries.* in the ``BINARIES'' CNFS metacycbuff, all articles over -roughly 50 KB in any other hierarchy in the ``LARGE'' CNFS metacycbuff, -all other articles in alt.* in one timehash class, and all other articles -in any newsgroups in a second timehash class, except for the internal.* -hierarchy which is stored in traditional spool format. -.RS -.nf - -method tradspool { - class: 1 - newsgroups: internal.* -} - -method cnfs { - class: 2 - newsgroups: alt.binaries.* - options: BINARIES -} - -method cnfs { - class: 3 - newsgroups: * - size: 50000 - options: LARGE -} - -method timehash { - class: 4 - newsgroups: alt.* -} - -method timehash { - class: 5 - newsgroups: * -} - -.fi -.RE -Notice that the last storage method entry will catch everything. This is -a good habit to get into; make sure that you have at least one catch-all -entry just in case something you didn't expect falls through the cracks. -Notice also that the special rule for the internal.* hierarchy is first, -so it will catch even articles crossposted to alt.binaries.* or over 50 KB -in size. -.SH HISTORY -Written by Katsuhiro Kondou for InterNetNews. -.de R$ -This is revision \\$3, dated \\$4. -.. -.R$ $Id: storage.conf.5 6124 2003-01-14 06:03:29Z rra $ -.SH "SEE ALSO" -cycbuff.conf(5), -expire.ctl(5), -inn.conf(5), -innd(8), -newsfeeds(5), -uwildmat(3).