afs-backend

(sysctl/remctl backend script for AFS maintenance)

SYNOPSIS

afs-backend release volume

afs-backend create volume quota mount

afs-backend delete volume

afs-backend quota volume quota

Either sysctl or remctl is required to run this script. Any new installation should use remctl. The AFS commands fs, pts, and vos are required, as are volcreate and volnuke for volume creation and deletion. By default, a volrelease wrapper is used to release volumes; this can be replaced in the script with a call to vos release if desired.

afs-backend by default uses an existing K4 ticket cache and runs aklog to obtain AFS tokens. Set KRB5CCNAME at the top of the script if you use K5 instead of K4. kstart is recommended as a program to maintain the ticket cache.

Be sure to update the reporting address, realm, and volume type mapping at the top of this script for your cell, and change the principal mapping if you don't use K4 principal names in AFS.

DESCRIPTION

This script is intended to be run from sysctl or remctl to perform various AFS administrative commands that should be restricted by ACL. It's intended to allow specific people to perform actions that would normally require AFS administrative access, but only for particular volumes and possibly with other constraints.

Currently, it supports four operations, release to release an AFS volume (which takes only the name of the volume), create to create an AFS volume, which takes the volume name, the quota (in MB), and the mount point (which should begin with /afs/.ir), delete to delete a volume (taking only the name of the volume), and quota to set the quota on a volume to the provided value (in MB).

All actions are checked against an ACL file. Blank lines and lines beginning with # in this file are ignored, and all other lines should have one of the following two syntaxes:

    <action> <volume>  <user> [<user> ...]
    <action> /<regex>/ <user> [<user> ...]

where <action> is create, release, delete, or quota, <volume> is the name of a volume, <regex> is a regular expression matching a set of volumes to which that line applies (regular expressions must be surrounded by //), and <user> is either a Kerberos identity for a particular user or is the name of a PTS group (distinguished from a regular user by the fact that only PTS group names containing colons are supported). If a PTS group is given, any user who is a member of that PTS group will be granted access. If a Kerberos identity is given, it should be the Kerberos v4 identity for the user (so rcmd.host instead of host/host.stanford.edu) unless the configuration is changed at the top of this script.

If the action is create, afs-backend maps the volume name to a volume type using rules that are currently contained in this script. If new types of volumes are added, new mapping rules from volume names to types may have to be added to the configuration at the top of this script so that afs-backend can pass the appropriate volume type to volcreate. This script currently cannot handle creation of replicated volumes.

If the action is delete, <volume> doesn't have to be a volume name. If instead it begins with /, it is taken to be a mount point and the volume to remove is determined by that mount point. In this case, the mount point will also be removed when the volume is removed.

An action of help is also supported and just prints out the available commands. This action isn't checked against the ACL.

afs-backend retrieves the user identity from the environment variable SCUSER or REMUSER, which is set by sysctl or remctl respectively. It reports the output from the command that it runs to both stdout and via e-mail to afs-reports at stanford.edu (configured at the beginning of this script). If the operation failed, the Subject header of that e-mail will begin with FAIL. If some unexpected error occurred, the Subject header of that e-mail will begin with ERROR.

EXAMPLES

Release ls.tripwire:

    afs-backend release ls.tripwire

Create a new volume named ls.trip.example with a quota of 10MB (or, actually, 10,000KB, fitting the somewhat odd quota standard that we use at Stanford) and mounted at /afs/.ir/site/leland/tripwire/example.Stanford.EDU:

    afs-backend create ls.trip.example 10 \
        /afs/.ir/site/leland/tripwire/example.Stanford.EDU

Delete a volume named ls.trip.example:

    afs-backend delete ls.trip.example

(note that the mount point still must be removed separately).

Set the quota on ls.trip.example to 20MB (actually 20,000 KB):

    afs-backend quota ls.trip.example 20

afs-backend should normally never be run directly, only via sysctl or remctl. If it must be run directly for some reason, the environment variable SCUSER or REMUSER must be set to the authenticated user.

ENVIRONMENT

REMUSER: Expected to contain the authenticated Kerberos identity of the user running this script via remctl, ending in @ and the realm.
SCUSER: Expected to contain the authenticated Kerberos identity of the user running this script via sysctl, without the realm (just the principal portion of the identity).

FILES

/afs/ir/service/afs/scripts/volcreate: The expected location of the volcreate script, which is used to create volumes. A -t option is passed to it indicating the volume type, which is determined by afs-backend from the name of the volume. The volume name, quota, and mount point are taken from the arguments to afs-backend, and no additional ACLs are passed in. volcreate is expected to handle the ACLs itself.
/afs/ir/service/afs/scripts/volrelease: The expected location of the volrelease script, used to release volumes. This script automatically passes the right arguments to vos release and retries on failure for a set number of times.
/afs/ir/service/afs/scripts/volnuke: The expected location of the volnuke script, which is used to delete volumes. If the supplied volume is actually a mount point, this script is called with the -m option. The -F option is always used to force non-interactive operation.
/etc/afs-remctl/acl: The expected location of the ACL file describing which users have which volume release and creation permissions, as described in DESCRIPTION above.
/usr/bin/aklog: The path to the program to run to obtain AFS tokens from a ticket cache.
/var/run/lsdb.k5.tgt: The expected path to a K5 ticket cache for an identity that has the ability to create, release, and remove AFS volumes and set volume quota. It should be in both system:administrators and in UserList on the AFS servers.

fs, pts, and vos are searched for in /usr/bin, then in /usr/afsws/bin for fs, and then in /usr/pubsw/bin.

AUTHOR

Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE

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