RKIVE(5)

NAME
rkive.cf - USENET Source Archiver Configuration File.

DESCRIPTION
rkive.cf allows the administrator to configure the way in which USENET sources are archived.

The configuration file is used to indicate where the archives are to be located, who will own the archive members, etc. The configuration file is divided into two sections, a global section and the individual newsgroup specifications.

The syntax of the individual line types are as follows:

    Global Variable Line
        Variable = value

    Newsgroup Identifier
        $$comp.source.whatever

    Newsgroup Variable Line
        Variable : value

Note that the '=' is used to designate a global variable and that the ':' is used to determine a newsgroup variable.

The global variables are divided up into variables that pertain to all archiving as well as defaults to be used in the event that the archive administrator has not set a specific value for a "defaultable" variable.

GLOBAL VARIABLES

SPOOLDIR =
    This is the base directory for the news subsystem.

PROBLEMS =
    The name of the base directory used to store any duplicate or "problem" articles that rkive(1) cannot deal with. All articles are stored under this directory in a newsgroup / volume directory structure.

LOG =
    The location of the master log in which actions are logged. If this variable is not set, no global logging takes place.

LOG_FORMAT =
    The format of the records of the master log file. This variable only pertains to the global log file format. The actual format specification must be enclosed in "". See article(1) for a discussion of the available selection format capabilities.

INDEX =
    The location of the master index file (if one is to be kept). The index can be used to interface with the netlib source retrieval software facility.

INDEX_FORMAT =
    The format of the records of the master index file. The actual format specification must be enclosed in "". See article(1) for a discussion of the available selection format capabilities.

MAIL =
    If specified, logged actions are mailed to the users listed. The user names are a comma separated list. It is not necessary to specify any users.

The following values are used if the administrator has not set a value for a corresponding newsgroup configuration item.

TYPE =
    This is the default archive type. There are 7 possible ways in which to archive USENET sources,

                  Volume-Issue,
                  Archive-Name,
                  Chronological,
                  Article Number,
                  Comp-Archives,
                  External-Command or
                  Only-Archive-Name.

    These are used to determine if you wish the articles archived in a

           /basedir/amiga/Volume1/v001i22 or
           /basedir/amiga/Volume1/sitonit or
           /basedir/amiga/Volume89/Jun/890628.01 or
           /basedir/amiga/Volume1/44 format.

    Comp-Archives is used only for the comp.archives newsgroup or newsgroups that supply Archive-name: but do not supply a volume number. External-Command is used if you want to have an external program/script deal with the article. The External-Command type must be accompanied with an ARCHIVE_CMD entry with specifies the external program for rkive to use.

PATCHES =
    This variable determines the way in which patches are installed into the archive. If the PATCHES entry is not defined either globally or within the newsgroup, the article is handled as a regular article and is stored according to the specified parameters of the newsgroup. The following are the valid possible values for the PATCHES variable:

    PATCHES=Historical
        This is the same as if no PATCHES entry existed at all. It is useful if Historical patches archiving is the default but there are certain newsgroups that have it specified differently.

    PATCHES=Package
        Package patches archiving allows the inbound patch to be placed with the directory with the initially posted articles. In this manner all parts and fixes of a package are together making it easier for software retrieval by uucp requests and mail request facilities such as netlib.

OWNER =
    The owner of the archive files after they are stored in the archive.

GROUP =
    The group ownership of the archive files after they are stored in the archive.

MODE =
    The default modes of the files residing in the archive.

COMPRESS =
    The location of the compression utility if the files are to be reduced. If this variable is specified, it must contain the full path to the command used to perform the compression.

CHECKHASH =
    The location of the checkhash utility if the files are to be tested for transit damage. Currently, only comp.sources.unix and comp.sources.misc supports this type of testing. The X-Checksum-Snerfu: header has been used in the past. This header is being phased out in favor of the X-Md4-Signature: header. If this variable is specified, it must contain the full path to the command used to perform the verification testing on the articles.

NNTP =
    The location of the NNTP server where the articles are to be archived from. This can be specified globally if all or most newsgroups are archived from a single NNTP server.

ARCHIVE_CMD =
    This is the path to an external command to pass all articles to that are in need of archiving. This is used when with the archive specification TYPE=External-Command. This command line may be augmented with variables specified in the rkive.cf file. See article.1 for a description of the format specification characters available.

MATCH =
    rkive allows you to use globbing to determine if an article is to be archived or not. This is the specification by which articles must match to be archived. The match specification may span multiple lines. A at the end of a line is used to indicate that the specification is continued on another line.

The following is a sample global variable section.

SPOOLDIR=/usr/spool/news
PROBLEMS=/usenet/problems
LOG=/usenet/archive.log
LOG_FORMAT= "%O %T %l"
INDEX= /usenet/index
INDEX_FORMAT= "%a %T"
MAIL=kent,rick,chris
TYPE= Archive-Name
PATCHES= Package
OWNER=src
GROUP=archive
MODE=0444
#COMPRESS=/usr/local/bin/compress
#CHECKHASH=/usr/local/bin/checkhash -s

In the above sample, if any of the individual newsgroups had not had the type of the archive specified, the type would have defaulted to an Archive-Name (if the newsgroup had the auxiliary headers required to support Archive-Name). By default, no compression was to be done. All results would have been mailed to the accounts of kent, rick and chris. If a newsgroup had not specified the ownership and modes of the destination archive members, the values specified in the global OWNER, GROUP, and MODE would have been used.

NEWSGROUP SPECIFICATIONS

An individual newsgroup entry is identified by a $$ as the first two characters of the line. The name of the newsgroup (in newsgroup format) follows such as

    $$comp.sources.unix

BASEDIR :
    This is the base directory for the archive.

LOG :
    The location of the log file in which actions are logged. If this variable is not set, no logging takes place.

LOG_FORMAT :
    The format of the records of the log file. The actual format specification must be enclosed in "". See article(1) for a discussion of the available selection format capabilities.

INDEX :
    The location of the index file (if one is to be kept). The index can be used to interface with the netlib source retrieval software facility.

INDEX_FORMAT :
    The format of the records of the index file. The actual format specification must be enclosed in "". See article(1) for a discussion of the available selection format capabilities.

MAIL :
    If specified, logged actions are mailed to the list of users specified. The user names are a comma separated list. It is not necessary to specify any users.

TYPE :
    This is the archive type. There are 7 possible ways in which to archive USENET sources,

                  Volume-Issue,
                  Archive-Name,
                  Chronological,
                  Article Number,
                  Comp-Archives,
                  External-Command or
                  Only-Archive-Name.

    Comp-Archives is used only for the comp.archives newsgroup or newsgroups that supply Archive-name: but do not supply a volume number. External-Command is used if you want to have an external program/script deal with the article. The External-Command type must be accompanied with an ARCHIVE_CMD entry with specifies the external program for rkive to use. Only-Archive-Name is used when the only articles that should be archived are articles that contain Archive-name: lines. The difference between Comp-Archives and Only-Archive-Name is that Comp-Archives expects all articles in the newsgroup have valid Archive-name: header lines and those that do not generate an error condition. Only-Archive-Name usage expects that only a few articles in the newsgroup have Archive-name: headers lines and silently ignores those that do not have the header line.

PATCHES :
    This variable determines the way in which patches are installed into the newsgroup's archive. If the PATCHES entry is not defined either globally or within the newsgroup, the article is handled as a regular article and is stored according to the specified parameters of the newsgroup. The following are the valid possible values for the PATCHES variable:

    PATCHES: Historical
        This is the same as if no PATCHES entry existed at all. It is useful if Historical patches archiving is the default but there are certain newsgroups that have it specified differently.

    PATCHES: Package
        Package patches archiving allows the inbound patch to be placed with the directory with the initially posted articles. In this manner all parts and fixes of a package are together making it easier for software retrieval by uucp requests and mail request facilities such as netlib.

OWNER :
    The the owner of the files after they are stored in the archive directory for the newsgroup.

GROUP :
    The group ownership of the archive files after they are stored in the archive directory for the newsgroup.

MODE :
    The default modes of the files residing in the archive directory.

COMPRESS :
    The location of the compression utility if the files are to be reduced. If this variable is specified, it must contain the full path to the command used to perform the compression.

CHECKHASH :
    The location of the checkhash utility if the files are to be tested for transit damage. Currently, only comp.sources.unix supports this type of testing. If this variable is specified, it must contain the full path to the command used to perform the test.

NNTP :
    The location of the NNTP server where the articles are to be archived from. This can be specified globally if all or most newsgroups are archived from a single NNTP server, or on a by newsgroup basis. If NNTP is specified globally and you wish to archive a newsgroup from your local system, add the following entry to the newsgroup specifications.

    NNTP: local

    This tells rkive to negate the global value. Case does not matter in the specification of local.

ARCHIVED_LOG :
    rkive requires that it be able to determine if an article has been previously archived. By default, rkive uses a file named .archived ($BASEDIR/.archived) which stores the message-id of the previously archived articles. If it is inconvient to store the .archived file in the base directory of the archive, a alternate path/location can be specified by the use of ARCHIVED_LOG.

PATCHLOG :
    rkive writes an entry to a file called .patchlog when it it encounters a Patch-To: line. By default, rkive uses a file named .patchlog ($BASEDIR/.patchlog). If it is inconvient to store the .patchlog file in the base directory of the archive, a alternate path/location can be specified by the use of PATHLOG.

ARCHIVE_CMD :
    This is the path to an external command to pass all articles to that are in need of archiving. This is used when with the archive specification TYPE=External-Command. This command line may be augmented with variables specified in the rkive.cf file. The additional format specification characters that can be used to build a command line with the information that is configured in the rkive.cf file. The specification character '$' is used to indicate that there is a variable that needs to be filled in. After the $, a character follows that indicates the type of information that is to supplied. The indicator characters and their meanings are:

    Global rkive.cf indicator characters:

    E - PROBLEMS - Path to the problems directory.
    I - INDEX - Location of the master index.
    J - INDEX_FORMAT - Format of the master index records.
    K - LOG_FORMAT - Format of the master log file records.
    L - LOG - Disk location of the master log file.
    S - SPOOLDIR - Base location of the news subsystem.
    U - MAIL - List of users to mail messages to.

    Newgroup specific indicator characters:

    a - ARCHIVED_LOG - Newsgroup's .archived file path
    B - BASEDIR - Base directory of the archive.
    c - COMPRESS - Path to compression program to be used.
    g - GROUP - Group id specified.
    h - CHECKHASH - Path to checkhash or checkmd4 utility.
    i - INDEX - Location of the newsgroup index.
    j - INDEX_FORMAT - Format of newsgroup index records.
    k - LOG_FORMAT - Format of newsgroup log file records.
    l - LOG - Disk location of the newsgroup log file.
    m - MODE - Modes of the archived files.
    o - OWNER - Owner of the archived files.
    p - PATCHES - Type of patches archiving to be done.
    u - MAIL - List of newsgroup users to mail messages to.
    N - NNTP - NNTP Server Host for the newsgroup.

    General indicator characters:

    b - Newsgroup's spool directory path.
    n - Newsgroup name.
    N - Disk path to the NNTP temporary transfer file.
    P - Actual disk path to the file to be archived.

MATCH :
    rkive allows you to use globbing to determine if an article is to be archived or not. This is the specification by which articles must match to be archived. The match specification may span multiple lines. A at the end of a line is used to indicate that the specification is continued on another line.

A sample entry for comp.sources.unix might look like:

$$comp.sources.unix
    BASEDIR: /usenet/unix
    TYPE: Volume-Issue
    PATCHES: Historical
    OWNER: kent
    GROUP: support
    MODE: 0664
    INDEX: /usenet/unix/index
    INDEX_FORMAT: "%O %a %S"
    COMPRESS: /usr/local/bin/compress
    CHECKHASH: /usr/local/bin/checkhash -s
    MAIL: kent,bob,sally

In the above sample, comp.sources.unix would be archived in /usenet/unix. The individual volume directories would be created there. All files would be owned by kent and the group support. The files would be writable by the group as well as the owner. (Not a smart idea but just for examples sake.) Logging is not being done although an index entry is being generated for each article archived. All files stored in the archive for this newsgroup are to be compressed using the compress program in /usr/local/bin. Mail is sent to kent, bob and sally when the archiving of comp.sources.unix has been completed. All files are tested with the checkhash command for validity before archiving.

SEE ALSO
rkive(1), article(1), ckconfig(1), checkhash(1), snefru(1)