mvto

(Move an AFS volume from anywhere, intelligently)

SYNOPSIS

mvto [-Ahfnsv] [-t threshold] volume server partition [server partition ...]

mvto [-Afns] -l list [-t threshold] server partition [server partition ...]

mvto [-Afns] -L list [-t threshold]

DESCRIPTION

mvto is a smart vos move that uses vos examine to determine where the volume is currently located and how it is currently replicated. It essentially allows the user to say "make the volume distribution look like this" and it will make the changes necessary to do that. For replicated volumes, the first server/partition pair is taken as the location of the read/write and every additional server/partition pair is taken as a site to put a replica. (One replica is automatically put on the same partition as the read/write, if any replication sites are specified, so the result will be a replication site on every server/partition pair given.)

mvto will check the available space on the partition to which a volume is being moved and any partitions where replicas are being added and will decline to do anything if its operation would take that partition over 90% full. This threshold can be changed with the -t option.

If the volume is replicated and is already located on the same server as the destination, even if it's on a different partition, this is considered by mvto to be "good enough" and the volume will not be moved. Similarly with replication sites, if there is already a replication site on that server (even on a different partition), that replication site won't be moved or removed and will be counted as one of the replication sites for the volume. To move replicated volumes between partitions on the same server requires more finesse and special cases since one cannot have two replicas on the same server, so it should be done by hand.

If any details about the replication of the volume had to be changed (and the volume is replicated), the volume will be released. In practice, this means that unless the volume is already located on all of the same servers given on the command line, already has a replication site on the same partition as the read/write, and already has the right number of replication sites, the volume will be released if replicated.

If the volume needs to be released, mvto will check to see if it has any unreleased changes. If so, it will refuse to perform any operations unless the --force (or -f) command-line option is given to avoid accidentally releasing volumes with unreleased changes. Don't rely on this check completely, since the volume could be modified between when mvto checks and when it actually releases the volume.

If the read/write volume has to be moved, mvto will run vos backup on the volume after the move (since volume moves have a side effect of deleting the backup volume). Don't use this program on volumes that shouldn't have a backup volume.

mvto will neither increase nor decrease the replication of a volume. If the number of replication sites should be changed, or if the volume is currently unreplicated and should be replicated, this should be done by hand before running mvto, using vos addsite and vos remove.

AFS servers may be specified as just a number; all numeric server names will have afssvr prepended to them.

As with all AFS commands, partitions may be specified as a simple letter, as vicepX, or as /vicepX. More than 26 partitions on one server is not supported. Partitions may also be specified as ., in which case the partition on that server with the most free space according to vos partinfo is chosen, or as a string of letters and letter ranges such as ace-gm, in which case the partition of the set specified with the most free space is chosen. (In this example, the set is /vicepa, /vicepc, /vicepe through /vicepg, or /vicepm on the given sever.)

mvto passes the verbose flag to most vos commands it runs.

OPTIONS

-A, --localauth

Call commands with -localauth to use the local KeyFile. This will require running mvto as root on a system that has the AFS KeyFile, such as a file server system. When running in this mode, no tokens are required, so there is no risk of tokens expiring during a long mvto process, leaving partially-moved volumes and other issues requiring a manual cleanup.

-f, --force

Release a volume if a release is required, even if that volume has unreleased changes. Without this flag, mvto will refuse to release a volume that has unreleased changes.

-h, --help

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

-l list, --list=list

Rather than take a single volume name on the command line, read in a list of volumes to act on from the file list. list should contain a simple list of AFS volume names, one per line, and each volume will be moved as if it were specified on the mvto command line, using the location information given on the command line.

-L list, --location-list=list

Similar to -l described above, but rather than taking just a list of volumes, one per line, instead expect a list of volumes followed by server and partition information for where to put those volumes. The server and partition information should be separated by whitespace and will be interpreted exactly as if it were given on the command line.

For example, running mvto -L list with a file named list that contains:

    user.rra afssvr12 .
    user.neilc afssvr10 e

would be equivalent to running the two commands:

    mvto user.rra afssvr12 .
    mvto user.neilc afssvr10 e

Command-line arguments cannot be given in the list file, only server and partition information. The -s flag may still be given on the command line and will affect how the location information in the list file is interpreted.

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

Print out volume status information and the commands that mvto would run, but don't execute any of them.

-s, --single

Rather than being a complete specification of the location at which the volume should be put, the command-line arguments are taken to be two server/partition pairs. The first is the current location of a site of the volume (either a replica or the read/write with its replica), and the second pair is the location to move that site to.

This allows mvto to be used to evacuate a single replication site server without having to know where the other sites for each of those volumes are located, while still taking advantage of mvto's understanding of vos release, creation of backup volumes, keeping a replica with the read/write volume, and so forth.

It generally doesn't make any sense to use this option with unreplicated volumes unless it's used in conjunction with -L with mixed RO and RW volumes. Otherwise, there's no reason not to use the regular syntax. What's special about this option is that it leaves all other sites of a volume alone.

-t threshold, --threshold=threshold

The safety threshold. mvto will not move a volume or add a replica to a partition if by doing so it would increase the usage of that partition above this threshold (specified as a ratio of used space to total space). The default is 0.9 (90% full). To disable this safety check, use -t 1.0.

-v, --version

Print out the version of mvto and exit.

CONFIGURATION

mvto 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:

$MVTO_THRESHOLD

The threshold up to which mvto is willing to fill a partition, expressed as a ratio of its total available space. The default value is 0.9, meaning that mvto will fill a partition up to 90% full. This setting is overridden by the -t command-line option.

$VOS

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

EXAMPLES

Move the volume ls.trip.windlord, wherever it is, to afssvr3 /vicepd:

    mvto ls.trip.windlord afssvr3 /vicepd

Move the volume ls to afssvr5 /vicepa, with replication sites on that same partition, on afssvr6 /vicepk, and on afssvr10 /vicepb:

    mvto ls 5 a 6 k 10 b

Move the volume pubsw to the partition on afssvr10 with the most free space, with one replication site on afssvr11 on whichever partition of the first three has the most free space. This volume will be released even if it has unreleased changes.

    mvto -f pubsw 10 . 11 a-c

Move all of the volumes in the file evacuate to the most empty partition on afssvr9. Note that the check for the most empty partition is done anew for each individual volume move, so the volumes will be spread out across the server.

    mvto -l evacuate afssvr9 .

For the volume pubsw, move only the site (whether a replica or a read/write with replica) on afssvr10 a to the most empty partition on afssvr11:

    mvto -s pubsw afssvr10 /vicepa 11 .

Do the same for every volume listed in the file evacuate:

    mvto -l evacuate -s 10 vicepa 11 .

Move every volume in the file locations to the locations specified on that line of the file, aborting if moving a volume would bring any partition to over 90% full:

    mvto -t 0.90 -L locations

CAVEATS

mvto by default uses the tokens of the user running mvto. This means there is a risk of the tokens expiring in the middle of the mvto run if a lot of volumes are being moved. Be aware of the lifespan of your tokens and obtain new tokens right before running mvto if the job will run for some time.

If your Kerberos realm allows renewable tickets, you may want to run mvto under krenew (part of the kstart package), which will keep renewing your tickets while mvto is running.

Alternately, you can run mvto as root on a system with a copy of the AFS KeyFile and use the -A option to pass -localauth to all of the vos commands. This will eliminate the risk of tokens expiring.

BUGS

If a replicated volume has no RO replica on the same server as its RW site, moving the RW site with mvto -s will increase the replication of the volume by adding a new RO site at the destination for the RW site without removing one of the other RO sites.

AUTHORS

Russ Allbery <eagle@eyrie.org>, based on a much simpler script by Neil Crellin <neilc@stanford.edu> that only handled unreplicated volumes.

COPYRIGHT AND LICENSE

Copyright 1998, 1999, 2001, 2003, 2004, 2005, 2011 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

krenew(1), vos(1), vos_addsite(1), vos_backup(1), vos_examine(1), vos_move(1), vos_release(1), vos_remove(1)

krenew is part of the kstart package, which is available at <http://www.eyrie.org/~eagle/software/kstart/>.

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