volcreate-logs

(Create and grant quota to log volumes in AFS)

SYNOPSIS

volcreate-logs [-hmnqv] [-k ticket-cache]

DESCRIPTION

This program maintains the size and existence of log volumes in AFS, creating new ones for upcoming months or years as necessary and increasing their quota as necessary if they're getting too full. It reports all of its actions, by default to standard out but optionally through mail with the -m option.

The rules for each set of log volumes are defined in the program configuration file, in /etc/afs-admin-tools/log-volumes by default. It uses volcreate to create all new log volumes, and therefore initial ACLs for new log volumes can be set using volcreate's ACL handling capabilities. See volcreate(1) for more information.

In order to use volcreate-logs to manage a set of volumes, the volumes must use standard directory structure and naming conventions. This means that under some root log directory, volumes must be organized like:

    ROOT/<year>/<month>

where <year> is the four-digit year and <month> is the two-digit month (with zero-padding where necessary). If there is a separate volume for each month, those volumes are mounted at locations that look like the above; if there is only a single volume for each year's worth of logs, that volume is mounted at ROOT/<year> and will have subdirectories for each month created automatically. The log volumes are named logs.service.YYYYMM where service is some string representing the service being logged and YYYYMM is the four-digit year and two-digit month. If the volume only holds logs for one year, the volume will end with YYYY instead.

New volumes will be created for the following month on any date after the twentieth of the month (log volumes will only be created if the appropriate directory does not already exist). Existing log volumes will have their quota and usage checked. If the quota is under the configured size, it will be increased to match. If the usage is over 90%, the volume quota will be increased by 10%, rounded up to the nearest 10MB.

OPTIONS

-h, --help

Print out this documentation (which is done simply by feeding the script to perldoc -t).

-k path, --ticket-cache=path

Indicates that the Kerberos v4 ticket cache found at path should be used to obtain an AFS token. If this option is used, the AFS::Utils Perl module must be available. A new PAG will be created for the script, the K4 ticket cache set to path, and aklog will be run to get a token.

If path is relative, it is assumed to be relative to /var/run (or whatever path is set in the $LOGS_TICKETS configuration variable).

-m, --mail

Report via e-mail rather than to standard out. Sends an e-mail report to the address set in the $LOGS_ADDRESS configuration variable, which must be set. See CONFIGURATION below.

-n, --dry-run, --just-print

Don't take any action other than inspection. Instead, just print to standard out each command that would be executed.

-q, --quiet

Suppress any additional output other than the one line per action taken (done mostly by adding the -q option to volcreate).

-v, --version

Print out the version of volcreate-logs and exit.

CONFIGURATION

General Settings

volcreate-logs loads configuration settings from /etc/afs-admin-tools/config if that file exists. If it exists, it must be Perl code suitable for loading with require. This means that each line of the configuration file should be of the form:

    our $VARIABLE = VALUE;

where $VARIABLE is the configuration variable being set and VALUE is the value to set it to (which should be enclosed in quotes if it's not a number). The file should end with:

    1;

so that Perl knows the file was loaded correctly.

The supported configuration variables are:

$LOGS_ADDRESS

The address to which to send mailed reports. If the -m option is given, this configuration variable must be set.

$LOGS_CONFIG

The configuration file specifying what log volumes to manage. See Log Volumes below for the syntax. The default path is /etc/afs-admin-tools/log-volumes.

$LOGS_TICKETS

The default root path for ticket files, used for the -k option if a relative path to a ticket file was given. The default value is /var/run.

$AKLOG

The full path to aklog, used to obtain AFS tokens from a Kerberos ticket if the -k option was given. If this variable is not set, volcreate-logs defaults to looking for aklog on the user's PATH.

$FS

The full path to the AFS fs utility. If this variable is not set, volcreate-logs defaults to looking for fs on the user's PATH.

$VOLCREATE

The full path to the volcreate utility. If this variable is not set, volcreate-logs defaults to looking for volcreate on the user's PATH.

$VOS

The full path to the AFS vos utility. If this variable is not set, volcreate-logs defaults to /usr/local/sbin/vos or /usr/sbin/vos if they exist, and otherwise looks for vos on the user's PATH.

Log Volumes

The file set by the $LOGS_CONFIG configuration variable, defaulting to /etc/afs-admin-tools/log-volumes, specifies the collections of log volumes managed by this program. The configuration will be used to increase quota or create new log volumes as needed. The syntax is:

    log {
        name: <volume-name>
        path: <base-path>
        type: monthly | yearly
        quota: <quota>
    }

where <volume-name> is the base name of the volume (.YYYY or .YYYYMM will be appended), <base-path> is the root of the log structure (its immediate subdirectories must be the year directories), type is either monthly to create a new volume for each month or yearly to create one volume for each year of logs, and <quota> is the starting quota for each volume in MB.

Blank lines and lines beginning with # are ignored.

EXAMPLES

Process all of the current rules, reporting actions to standard out.

    volcreate-logs

Do the same, but instead send the report via e-mail.

    volcreate-logs -m

Do the same, but obtain AFS credentials from /var/run/lsdb.k5.tgt:

    volcreate-logs -m -k lsdb.k5.tgt

Check to see what needs to be done, but don't actually do it. Instead, just print the commands that would be executed to standard out:

    volcreate-logs -n

Only check and reset quota or create new log volumes for the config file entries with a name value of logs.cgi or logs.www:

    volcreate-logs logs.cgi logs.www

FILES

/etc/afs-admin-tools/log-volumes

The default configuration file specifying the collections of log volumes managed by this program. The path to this file may be overridden by setting the $LOGS_CONFIG configuration variable.

AUTHOR

Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

Copyright 2002, 2004, 2011, 2012 The Board of Trustees of the Leland Stanford Junior University.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

newsyslog(1), volcreate(1)

The current version of newsyslog is available from its web site at <http://www.eyrie.org/~eagle/software/newsyslog/>.

This script is part of the afs-admin-tools package. The most recent version is available from the afs-admin-tools web page at <http://www.eyrie.org/~eagle/software/afs-admin-tools/>.

Last spun 2014-08-10 from POD modified 2014-04-14