afs-admin-tools release 2.0
(utilities for AFS management)
Maintained by Russ Allbery <eagle@eyrie.org>
These programs are free software; you may redistribute them and/or
modify them under the same terms as Perl itself. Please see the section
LICENSE below for more information.
BLURB
afs-admin-tools provides a collection of additional utilities to help
ease administration of AFS servers, volumes, and directory ACLs. It
includes scripts to report the differences between read-only and
read/write volumes; make all fs commands recursive; create, delete, and
move volumes more easily than with vos alone; and report AFS server
partition usage in a more readable form.
DESCRIPTION
This is a collection of the additional scripts and utilities we've
developed at Stanford University to ease administration of AFS. It's a
bit of a grab-bag of utilities that we've written and tweaked over time.
All of them are built around the idea of providing a more powerful
command-line interface and are written as wrappers around the regular
AFS commands.
frak compares a read/write AFS volume with its read-only replica and
reports on all of the differences. We use this as a sanity check before
releasing volumes to ensure we know what's changed. If you have bundle
available, it can optionally create bundles to revert and reapply the
changes.
fsr is a wrapper around the AFS fs command that turns all commands that
act on files or directories into recursive commands. It can be
configured to cross or not cross mount points. It's primarily useful
with setacl but is occasionally useful with other commands.
lsmounts recursively searches through an AFS volume and finds and
reports on mount points. It can optionally traverse mount points as
well to find mount points in volumes mounted under a particular
directory.
mvto is a smart vos move that automatically detects where the volume is
currently located so that one doesn't have to provide the source
location. It also supports other features handy for automating volume
moves, including taking the list of volumes and optionally the list of
destinations from a file, automatically handling read/write volumes with
read-only replicas on the same server, moving read-only replica volumes,
distributing the moved volumes across a set of servers and partitions,
and double-checking that there's enough space on a destination partition
before moving a volume to it.
partinfo is a wrapper around vos partinfo that provides more readable
output and optionally colorizes it, making it easier to tell at a glance
which partitions have free space and which are dangerously full.
volcreate is a smart vos create that takes a configuration file
specifying where to put volumes of a particular type. It can spread
volumes of a particular type across multiple server partitions to
balance space usage, can create replicated volumes and ensure that a
replica is present in each configured data center, can clone an existing
volume when creating a new one, and handles setting ACLs at the same
time as creating the volume. volcreate-logs is a specialized version of
volcreate that handles automatically creating date-based log volumes for
archiving of system logs.
volnuke is a smart vos remove that can determine the volume to remove
from its mount point, can remove any replicas along with the read/write
volume, can check whether the volume is still being accessed before
removing it, and automatically removes the mount point as well as the
volume if run on a mount point.
These scripts were originally written by various people at Stanford
University over the years, most notably Neil Crellin, Carol Oliver, and
Russ Allbery. They were originally maintained and distributed
independently, but have been combined into the afs-admin-tools
distribution so that they can more easily reuse common code.
REQUIREMENTS
All scripts are written in Perl and should work with Perl 5.006 or
later. They require the AFS client binaries be available in either some
standard locations (in /usr or /usr/local) or on the PATH.
frak requires Stat::lsMode, available from CPAN, and prefers to have a
diff program that supports -u (such as GNU diff). mvto and volnuke
require Date::Parse, available as part of the TimeDate distribution on
CPAN. volcreate-logs requires AFS::Utils (part of the AFS Perl module
suite), an aklog binary if run with a ticket cache specified on the
command line, and a local sendmail command if told to mail reports.
To run the full test suite, Test::More is required (part of Perl since
5.6.2). It also makes use of additional Perl modules for some tests.
These tests will be skipped automatically if the modules aren't
available. To run the full set of default tests, you will need the Perl
modules:
Test::MinimumVersion
Test::Pod
Test::Strict
and their dependencies. These modules are all available from CPAN.
Some parts of the test suite are suppressed by default because those
tests are normally only useful for the maintainer. This includes tests
of POD spelling and Perl coding style. To enable those tests, set the
environment variable RRA_MAINTAINER_TESTS to a true value. For these
tests, the additional Perl modules:
Test::Spelling
and their dependencies as well as a spell-checking program (several are
supported by Test::Spelling) are required. These modules are all
available from CPAN.
INSTALLATION
First, you should read the site configuration section at the beginning
of each script before you use it and adjust the configuration paths and
settings there for your site. Many of the scripts come with settings
that are somewhat Stanford-specific.
Then, follow the standard installation procedures for Perl modules,
which is to type the following commands:
perl Makefile.PL
make
make install
You'll probably need to do the "make install" as root.
For the time being, you could instead just copy the scripts you want to
use to a directory on your PATH. However, future releases will probably
move some shared code to a supporting Perl module.
SUPPORT
The afs-admin-tools web page at:
http://www.eyrie.org/~eagle/software/afs-admin-tools/
will always have the current version of this package, the current
documentation, and pointers to any additional resources.
I welcome bug reports and patches for this package at eagle@eyrie.org.
However, please be aware that I tend to be extremely busy and work
projects often take priority. I'll save your mail and get to it as soon
as I can, but it may take me a couple of months.
SOURCE REPOSITORY
afs-admin-tools is maintained using Git. You can access the current
source by cloning the repository at:
git://git.eyrie.org/afs/afs-admin-tools.git
or view the repository via the web at:
http://git.eyrie.org/?p=afs/afs-admin-tools.git
When contributing modifications, patches (possibly generated by
git-format-patch) are preferred to Git pull requests.
LICENSE
The afs-admin-tools distribution as a whole is covered by the following
copyright statement and license:
Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
2008, 2010, 2011, 2013
The Board of Trustees of the Leland Stanford Junior University
These programs are free software; you may redistribute them and/or
modify them under the same terms as Perl itself. This means that you
may choose between the two licenses that Perl is released under: the
GNU GPL and the Artistic License. Please see your Perl distribution
for the details and copies of the licenses.
All individual files are released under this license or a license that
is compatible with it. Files that are released under a compatible
license will have that license noted at the start of the file. Some
files may have additional copyright holders as noted in those files.