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.

Converted to XHTML by faq2html version 1.33