volcreate

#!/usr/bin/perl
our $VERSION = '2.8 (2025-07-01)';
#
# volcreate -- Create a volume, mount and set acl and quota
#
# Creates a new AFS volume on the given server and partition and mounts it
# in the file system, setting default ACLs if appropriate.  It then calls
# loadmtpt to update the mount point database.
#
# Written by Neil Crellin <neilc@stanford.edu>
#        and Russ Allbery <eagle@eyrie.org>
# Copyright 1998, 1999, 2000, 2002, 2004, 2005, 2011, 2012, 2013
#     The Board of Trustees of the Leland Stanford Junior University
#
# Updated by Bill MacAllister <bill@ca-zephyr.org>
# Copyright 2018
#    Bill MacAllister <bill@ca-zephyr.org>
#
# This program is free software; you may redistribute it and/or modify it
# under the same terms as Perl itself.

##############################################################################
# Modules and declarations
##############################################################################

use 5.006;
use strict;
use warnings;

use vars qw($JUSTPRINT);
use subs qw(system);

use Getopt::Long qw(GetOptions);

my ($clone, $help, $quiet, $replicas, $type, $version);
my $opt_mtpt;
my $opt_partition;
my $opt_quota;
my $opt_server;
my $opt_volume;

##############################################################################
# Site configuration
##############################################################################

# The cutoff proportion of candidate partitions that will be considered for
# placement of a read/write volume.  This can be overridden with the -p flag.
our $VOLCREATE_CUTOFF = 0.2;

# Unset by default, this requires that all mount points begin with a
# particular prefix, generally to ensure that stored mount points using
# loadmtpt are all named consistently.
our $VOLCREATE_MOUNT_PREFIX;

# The path to a file containing ACL rules for volumes.  See the documentation
# for its format.
our $ACLS = '/etc/afs-admin-tools/acl-rules';

# The path to a file containing a list of current AFS servers and their volume
# types.  See the documentation for its format.
our $SERVERS = '/etc/afs-admin-tools/servers';

# The full path to the loadmtpt utility from afs-mountpoints.  The default of
# the empty string says not to do mount point loading.
our $LOADMTPT = '';

# The full path to fs and vos.  vos may be in an sbin directory, which may
# not be on the user's path by default, so check there first.
our $FS  = 'fs';
our $VOS = grep { -x $_ } qw(/usr/local/sbin/vos /usr/sbin/vos);
$VOS ||= 'vos';

# Load the configuration file if it exists.
if (-f '/etc/afs-admin-tools/config') {
    require '/etc/afs-admin-tools/config';
}

##############################################################################
# Overrides
##############################################################################

# We override system to honor the global $JUSTPRINT variable.  It otherwise
# works the same way as system normally does.
sub system {
    if ($JUSTPRINT) {
        print "@_\n";
        return 0;
    } else {
        return CORE::system(@_);
    }
}

##############################################################################
# AFS information
##############################################################################

# Given a list of server name and partition pairs, fully qualify each and
# return them as a list of similar pairs, ordered by whichever partition has
# the most percentage free space.  If ., a list of letters, or letter ranges
# are given for the partition, pick the partition from that set that has the
# most free space.
sub find_targets {
    my @locations = @_;
    my @results;

    # Special-case the fully-qualifed case where the user gave the exact
    # server and partition.
    if (@locations == 1 && $locations[0][1] =~ /^[a-z]$/) {
        my ($server, $partition) = @{ $locations[0] };
        if ($server =~ /^\d+$/) {
            $server = 'afssvr' . $server;
        }
        $partition =~ s%^(?:/?vicep)?%/vicep%;
        return [$server, $partition];
    }

    # The normal case, where we need to go looking at current server usage to
    # gather the necessary information.
    while (@locations) {
        my ($server, $part) = @{ shift @locations };

        if ($server =~ /^\d+$/) {
            $server = 'afssvr' . $server;
        }
        if ($part eq '.') {
            $part = 'a-z';
        }
        open(INFO, "$VOS partinfo -server $server |")
          or die "$0: can't fork: $!\n";
        my @free;
        local $_;
        while (<INFO>) {
            if (
                m(^Free\ space\ on\ partition\ (/vicep[$part]):\ (\d+)\ K
                  \ blocks\ out\ of\ total\ (\d+)\s*\z)x
              )
            {
                my ($part, $free, $totl) = ($1, $2, $3);
                push(@free, [$part, $free, $free / $totl]);
            } elsif (
                m%^Free \s+ space \s+ on \s+ server \s+ (\S+)
                    \s+ partition \s+ (/vicep\S+):
                    \s+ (\d+) \s+ K \s+ blocks
                    \s+ out \s+ of \s+ total \s+ (\d+)$%xms
              )
            {
                my ($server, $part, $free, $totl) = ($1, $2, $3, $4);
                push(@free, [$part, $free, $free / $totl]);
            } elsif (m%^Free space on partition (/vicep.)%) {
                next;
            } else {
                die "$0: vos partinfo said $_\n";
            }
        }
        close INFO;
        if (!@free) {
            die "$0: no partition matching $part on $server\n";
        }
        @free = sort { $$b[1] <=> $$a[1] } @free;
        push(@results, map { [$server, $$_[0], $$_[2]] } @free);
    }
    @results = sort { $$b[2] <=> $$a[2] } @results;
    return map { [$$_[0], $$_[1]] } @results;
}

# Given a volume type for an unreplicated volume, look through the types file
# and find appropriate servers and partitions to use.  Returns a random server
# and partition pair from the 25% that have the most percentage free space.
sub find_best_normal {
    my $type = shift;
    my @locations;
    open(SERVERS, $SERVERS) or die "$0: can't open $SERVERS: $!\n";
    local $_;
    while (<SERVERS>) {
        if (/^\s*$/) {
            next;
        }
        if (/^\s*\#/) {
            next;
        }
        my ($server, @rules) = split;
        if ($rules[0] =~ /^\[.*\]$/) {
            shift @rules;
        }
        my $parts = '';
        for (@rules) {
            my ($part, $allowed);
            if (/:/) {
                ($part, $allowed) = split ':';
            } else {
                $part    = 'a-z';
                $allowed = $_;
            }
            if ($allowed eq $type) {
                $parts .= $part;
            }
        }
        if ($parts) {
            push(@locations, [$server, $parts]);
        }
    }
    close SERVERS;
    if (!@locations) {
        die "$0: no servers found for type $type\n";
    }
    my @result = find_targets @locations;
    return @{ $result[int rand(scalar(@result) * $VOLCREATE_CUTOFF)] };
}

# Given a volume type for a replicated volume and the number of replicas, look
# through the types file and find appropriate servers and partitions to use.
# Returns a list, where the first two elements are the server and partition to
# use for the read/write and the first replica and subsequent element pairs
# are the server and partition to use for the read-only replicas.  Handles
# geographic dispersion.
sub find_best_replicated {
    my ($type, $replicas) = @_;
    my (@rw, @ro, %servers);
    open(SERVERS, $SERVERS) or die "$0: can't open $SERVERS: $!\n";
    local $_;
    while (<SERVERS>) {
        if (/^\s*$/) {
            next;
        }
        if (/^\s*\#/) {
            next;
        }
        my ($server, @rules) = split;
        my $site;
        if ($rules[0] =~ /^\[(.*)\]$/) {
            $site = $1;
            shift @rules;
        }
        my $rwparts = '';
        my $roparts = '';
        for (@rules) {
            my ($part, $allowed);
            if (/:/) {
                ($part, $allowed) = split ':';
            } else {
                $part    = 'a-z';
                $allowed = $_;
            }
            if ($allowed eq "$type-rw") {
                $rwparts .= $part;
            } elsif ($allowed eq "$type-ro") {
                $roparts .= $part;
            }
        }
        if ($rwparts) {
            $servers{$server} = $site;
            push(@rw, [$server, $rwparts]);
        }
        if ($roparts) {
            $servers{$server} = $site;
            push(@ro, [$server, $roparts]);
        }
    }
    close SERVERS;
    if (!@rw || !@ro || @ro < $replicas - 1) {
        die "$0: insufficient servers found for type $type\n";
    }
    my @locations;
    my @targets = find_targets @rw;
    push(@locations, $targets[int rand(scalar(@targets) * $VOLCREATE_CUTOFF)]);
    my %sites = map { $_ => 1 } values %servers;
    for my $site (keys %sites) {
        if (@locations >= $replicas) {
            last;
        }
        if ($site eq $servers{ $locations[0][0] }) {
            next;
        }
        my @candidates = grep { $servers{ $$_[0] } eq $site } @ro;
        if (!@candidates) {
            next;
        }
        push(@locations, (find_targets @candidates)[0]);
    }
    my $found = @locations;
    if ($found < $replicas) {
        my %locations = map { @$_ } @locations;
        @ro = grep { !$locations{ $$_[0] } } @ro;
        push(@locations, (find_targets @ro)[0 .. ($replicas - $found - 1)]);
    }
    return @locations;
}

##############################################################################
# AFS operations
##############################################################################

# Create a volume, given the server, partition, volume name, and quota.  Dies
# on a failure to create the volume.
sub volume_create {
    my ($server, $partition, $volume, $quota) = @_;
    my $quota_kbytes;
    if ($quota =~ /^(\d+)$/xms) {
        $quota_kbytes = $quota * 1024;
    } elsif ($quota =~ /^(\d+)([kmgt])/xmsi) {
        my $q = $1;
        my $m = $2;
        if (lc($m) eq 't') {
            $quota_kbytes = $q * 1024 * 1024 * 1024;
        } elsif (lc($m) eq 'g') {
            $quota_kbytes = $q * 1024 * 1024;
        } elsif (lc($m) eq 'm') {
            $quota_kbytes = $q * 1024;
        } elsif (lc($m) eq 'k') {
            $quota_kbytes = $q;
        }
    }
    if (!$quota_kbytes) {
        die "ERROR: invalid quota value ($quota)\n";
    }

    system(
        $VOS,         'create',   '-server', $server,
        '-partition', $partition, '-name',   $volume,
        '-maxquota',  $quota_kbytes
      ) == 0
      or die 'Failed to create volume (status ', ($? >> 8), ")\n";
    system($VOS, 'backup', '-id', $volume) == 0
      or die 'Failed to backup volume (status ', ($? >> 8), ")\n";
    return;
}

# Clone a volume, given the server, partition, and volume name to use for the
# new volume and the name of the old volume to clone.
sub volume_clone {
    my ($server, $partition, $new, $old) = @_;
    require File::Temp;

    my ($fh, $filename) = File::Temp::tempfile(undef, UNLINK => 1);
    print "Dumping volume $old\n";
    system($VOS, 'dump', '-id', $old, '-file', $filename) == 0
      or die "$0: failed to dump volume $old (status ", ($? >> 8), ")\n";
    print "Restoring $new from ", $filename, "\n";
    system(
        $VOS,       'restore', '-server', $server, '-partition',
        $partition, '-name',   $new,      '-file', $filename
      ) == 0
      or die "$0: failed to create volume $new (status ", ($? >> 8), ")\n";
    close $fh;
    return;
}

# Mount the volume, chmod it to 755 since AFS creates it 777, and load the
# mount point into the database.  chmod the root of the volume to 755 since
# AFS creates it 777.
sub volume_mount {
    my ($volume, $mtpt) = @_;
    system($FS, 'mkmount', '-dir', $mtpt, '-vol', $volume) == 0
      or die 'Failed to make mount point (status ', ($? >> 8), ")\n";
    if ($JUSTPRINT) {
        print "chmod 755 $mtpt\n";
    } else {
        chmod(0755, $mtpt) or warn "Failed to chmod root: $!\n";
    }
    if ($LOADMTPT) {
        system($LOADMTPT, $mtpt) == 0
          or warn 'Failed to load mountpoint (status ', ($? >> 8), ")\n";
    }
}

# Set the ACLs of the volume appropriately.  Some volumes have their own
# particular ACL conventions; take care of those here as well.
sub volume_setacls {
    my ($volume, $mtpt, @acls) = @_;

    # Find any extra ACLs that apply to this volume.
    my @extra;
    if (open(ACLS, $ACLS)) {
        local $_;
        my $found = 0;
        while (<ACLS>) {
            if (/^\s+\#/) {
                next;
            }
            if (/^\s*$/) {
                next;
            }
            if (m%^/(.*)/\s*$%) {
                my $regex = $1;
                $found = ($volume =~ /$regex/);
            } elsif ($found && /^\s/) {
                my ($user, $acl, $bogus) = split;
                if ($bogus || !$user || !$acl) {
                    warn "$0: syntax error on line $. of $ACLS\n";
                    next;
                }
                push(@extra, $user, $acl);
            }
        }
        close ACLS;
    } else {
        warn "$0: cannot open $ACLS: $!\n";
    }

    # Append the extra ACLs that apply to this volume.
    push(@acls, @extra);

    # Actually set the ACLs.
    system($FS, 'setacl', '-path', $mtpt, '-acl', @acls) == 0
      or warn 'Failed to set acls (status ', ($? >> 8), ")\n";
}

# Given the volume name and then a list of server and partition pairs, create
# the replicas for a replicated volume and then release it.  The list of
# server and partition pairs must include the location of the read/write
# volume for the first replica.
sub volume_replicate {
    my ($volume, @locations) = @_;
    while (@locations) {
        my ($server, $partition) = @{ shift @locations };
        system($VOS, 'addsite', '-server', $server, '-partition', $partition,
            '-id', $volume) == 0
          or die "Failed to replicate volume to $server $partition",
          ' (status ', ($? >> 8), ")\n";
    }
    system($VOS, 'release', '-id', $volume, '-force') == 0
      or die 'Failed to release volume (status ', ($? >> 8), ")\n";
}

##############################################################################
# Main routine
##############################################################################

# Trim extraneous garbage from the path.
my $fullpath = $0;
$0 =~ s%.*/%%;

# Parse command line options.  We do allow an odd number of arguments for
# ACLs, in order to allow things like -clear.
Getopt::Long::config('bundling', 'no_ignore_case');
GetOptions(
    'c|clone=s'            => \$clone,
    'h|help'               => \$help,
    'q|quiet'              => \$quiet,
    'm|mountpt=s'          => \$opt_mtpt,
    'n|dry-run|just-print' => \$JUSTPRINT,
    'p|partition=s'        => \$opt_partition,
    'proportion=f'         => \$VOLCREATE_CUTOFF,
    'Q|quota=s'            => \$opt_quota,
    'r|replicas=i'         => \$replicas,
    's|server=s'           => \$opt_server,
    't|type=s'             => \$type,
    'v|version'            => \$version,
    'V|volume=s'           => \$opt_volume
) or exit 1;
if ($help) {
    exec('perldoc', '-t', $0) or die "Cannot fork: $!\n";
    exit 1;
} elsif ($version) {
    print "volcreate $VERSION\n";
    exit 1;
}
if ($replicas && !$type) {
    die "-r option given without -t option\n";
}
if ($VOLCREATE_CUTOFF > 1 || $VOLCREATE_CUTOFF < 0) {
    die "-p value must be between 0 and 1\n";
}
$replicas ||= 0;

# If quiet operation was requested, cheat by rerouting stdout to /dev/null.
if ($quiet) {
    open(STDOUT, '> /dev/null')
      or die "$0: cannot redirect stdout to /dev/null: $!\n";
}

# Fill in the various information that we need.
my ($server, $partition, $volume, $quota, $mtpt, @acls);
if ($type) {
    if ($type =~ /-r[wo]$/) {
        die "Type ends in -ro or -rw (maybe you meant to use the -r flag?)\n";
    }
    if ($opt_volume) {
        $volume = $opt_volume;
    } else {
        $volume = shift(@ARGV);
    }
    if ($opt_quota) {
        $quota = $opt_quota;
    } else {
        $quota = shift(@ARGV);
    }
    if ($opt_mtpt) {
        $mtpt = $opt_mtpt;
    } else {
        $mtpt = shift(@ARGV);
    }
    if (!$volume || !$quota || !$mtpt) {
        die "Usage: volcreate -t type volname quota mountpoint [acls]\n";
    }
    if (scalar(@ARGV) > 0) {
        @acls = @ARGV;
    }
} else {
    if ($opt_server) {
        $server = $opt_server;
    } else {
        $server = shift(@ARGV);
    }
    if ($opt_partition) {
        $partition = $opt_partition;
    } else {
        $partition = shift(@ARGV);
    }
    if ($opt_volume) {
        $volume = $opt_volume;
    } else {
        $volume = shift(@ARGV);
    }
    if ($opt_quota) {
        $quota = $opt_quota;
    } else {
        $quota = shift(@ARGV);
    }
    if ($opt_mtpt) {
        $mtpt = $opt_mtpt;
    } else {
        $mtpt = shift(@ARGV);
    }
    if (!$server || !$partition || !$volume || !$quota || !$mtpt) {
        die "Usage: volcreate server partition volname quota mtpt [acls]\n";
    }
    if (scalar(@ARGV) > 0) {
        @acls = @ARGV;
    }
}

# Ensure that the mount point starts with $VOLCREATE_MOUNT_PREFIX, if set.
# This is also useful for ensuring that the arguments weren't given in the
# wrong order and no argument was missing.
if (defined($VOLCREATE_MOUNT_PREFIX) and $LOADMTPT) {
    my $prefix = $VOLCREATE_MOUNT_PREFIX;
    if ($mtpt !~ m,^\Q$prefix\E,) {
        my $try = $mtpt;
        $try =~ s,^/afs/([^.]),/afs/.$1,;
        if ($try =~ m,^\Q$prefix\E,) {
            $mtpt = $try;
        } else {
            die "Mount point must begin with $prefix\n";
        }
    }
}

# fs mkm doesn't like trailing slashes on the mount point, and neither does
# the mount point database.
$mtpt =~ s%/+$%%;

# Make sure the parent directory of the mount point exists and the mount point
# doesn't already exist.
if (-e $mtpt) {
    die "Mount point $mtpt already exists\n";
}
my $parent = $mtpt;
if ($parent =~ s%/[^/]+$%%) {
    if (!-d $parent) {
        die "Parent directory of mount point $mtpt doesn't exist\n";
    }
}

# Canonify AFS server name and find the exact partition on which to create the
# read/write volume.
my @ros;
if ($type) {
    if ($replicas) {
        @ros = find_best_replicated($type, $replicas);
        ($server, $partition) = @{ $ros[0] };
    } else {
        ($server, $partition) = find_best_normal($type);
    }
} else {
    ($server, $partition) = @{ (find_targets [$server, $partition])[0] };
}

# Do the work of creating and mounting the read/write volume.
if ($clone) {
    volume_clone($server, $partition, $volume, $clone);
} else {
    volume_create($server, $partition, $volume, $quota);
}
volume_mount($volume, $mtpt);
if (!$clone) {
    volume_setacls($volume, $mtpt, @acls);
}

# If the volume is replicated, take care of creating and releasing the
# replicas now that the ACL is set correctly.
if ($replicas && $replicas > 0) {
    volume_replicate($volume, @ros);
}

exit 0;

__END__

##############################################################################
# Documentation
##############################################################################

=for stopwords
ACL afs Crellin acl afs-admin-tools afssvr3 afssvr14 fs -hnq loadmtpt
afs-mountpoints partinfo pubsw rra volcreate vos pubsw.byacc19

=head1 NAME

volcreate - Create and mount a new AFS volume

=head1 SYNOPSIS

B<volcreate> [B<-hnq>] [B<--version>] [B<-c> I<clone-from>]
[B<--proportion> I<cutoff>] I<server> I<partition> I<volume>
I<quota>[k|m|g|t] I<mount> [I<acl> ...]

B<volcreate> [B<-hnq>] [B<--version>] [B<-c> I<clone-from>]
[B<-proportion> I<cutoff>] [B<-r> I<replicas>] B<-t> I<type> I<volume>
I<quota>[k|m|g|t] I<mount> [I<acl> ...]

=head1 DESCRIPTION

B<volcreate> creates a new AFS volume on the given server and
partition, sets its quota, and mounts it in the file system at the
given path, optionally setting its ACL.  It then updates the AFS mount
point database to include this new volume.

I<server> is the AFS server on which to create the volume.  AFS
servers may be specified as just a number; all numeric server names
will have C<afssvr> prepended to them.  The server can optionally be
specified using the B<-s> option.

I<partition> is the partition on which to create that volume.
Partitions may be specified as a simple letter, as C<vicepX>, or as
C</vicepX>.  More than 26 partitions on one server is not supported.
Partitions may also be specified as C<.>, in which case a random
partition on that server in the top 20% in free space according to
B<vos partinfo> is chosen, or as a string of letters and letter ranges
such as C<ace-gm>, in which case a random partition of the set
specified in the top 20% in free space is chosen.  (In this example,
the set is /vicepa, /vicepc, /vicepe through /vicepg, or /vicepm on
the given sever.)  The 20% cutoff proportion can be overridden with
the B<-p> option.  The partition can be specified with the B<-p>
option.

Alternately, rather than giving a server and partition, B<volcreate>
accepts the B<-t> option to specify a volume type.  If this option is
given, no server or partition is necessary and B<volcreate> will
instead place the volume on an appropriate server by finding a random
partition in the top 20% of the most percentage space free of the
available server partitions for that volume type.  As above, the
cutoff proportion can be overridden with the B<--proportion> option.
For more information on defining volume types and associating them
with appropriate servers and partitions, see L<CONFIGURATION> below.

When B<-t> is given, B<-r> may also be given to specify a number of
replicas if a replicated volume is being created.  When creating a
replicated volume, the read/write copy will be placed as described above,
but the read-only replicas will be placed on the I<replicas> partitions
with the most free space.

I<volume> is the name of the volume to create.  I<quota> is the
volume's quota.  The quota value defaults to megabytes (B<not> in
kilobytes) if not units are specified.  Valid quota units are k, m, g,
and t which are kilobytes, megabytes, gigabytes, and terabytes
respectively.  I<mount> is the full path to the intended mount
location of the volume (this must begin with $VOLCREATE_MOUNT_PREFIX
so that the mount point database remains consistent).  I<acl> is any
normal ACL arguments to C<fs setacl>.  The quota, mount point, and
volume can also be specified using the B<-q>, B<-m>, and B<-v> options
respectively.

For some types of volumes, some ACLs will be set automatically.  This is
governed by the F<acl-rules> file; see L<CONFIGURATION> below.

=head1 OPTIONS

=over 4

=item B<-c> I<clone-from>, B<--clone>=I<clone-from>

Rather than creating a new, empty volume, clone the newly created volume
from the volume I<clone-from>.  This dumps the old volume into F</tmp>, so
be careful to do this on a system with a lot of space in F</tmp> if the
volume is large.  When this option is specified, the quota and ACLs
specified on the command line will be ignored, since they'll just be
copied from the old volume.  (The quota must still be specified, though,
even though it's ignored.  This is a wart in the interface.)

=item B<-h>, B<--help>

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

=item B<-m> I<mount point>, B<--mountpt>=I<mount point>

The mount point for the volume.

=item B<-n>, B<--dry-run>, B<--just-print>

Don't run any commands, just print out what would have been done.

=item B<-p> I<afs partition>, B<--partition>=I<afs partition>

The partition to create the volume on.

=item B<--proportion>=I<cutoff>

By default, when placing read/write volumes, the destination partition
will be chosen randomly from the top 20% of partitions ranked by the most
free space.  The placement of the volume is somewhat randomized to avoid
putting lots of small volumes on the same mostly unused partition,
creating a long-term space problem when all of those volumes are used.

This option can be used to change the number of partitions selected from
for this random placement.  The default is 0.2, representing that top 20%
metric.  A value of 0 will always choose the partition with the most free
space.  A value of 1 will cause the placement to be completely random
among all possible locations, without regard to which have the most free
space.  Any other value will be the proportion of the possible locations
that will be chosen between randomly.

=item B<-q>, B<--quiet>

Run quietly.  Only errors (if any) will be output.

=item B<-r> I<replicas>, B<--replicas>=I<replicas>

The number of replicas for the volume.  Use of this option indicates that
the volume is replicated, and it will be replicated at a number of sites
equal to the I<replicas> value.  The first replica will always be on the
same server and partition as the read/write volume; the rest will be
chosen from the servers that hold read-only replicas for that volume type.
B<-t> must be given if this option is used.

=item B<-s> I<afs server>, B<--server>=I<server>

The AFS file server to create the volume on.

=item B<-t> I<type>, B<--type>=I<type>

Create a volume of the specified type.  When this option is used, no
server or partition should be specified, and instead B<volcreate> will
find all the servers that can store that volume type and pick the server
and partition with the most percentage space free.  This option is
required to use B<-r>.

=item B<--version>

Print out the version of B<volcreate> and quit.

=item B<-v> I<volume name>, B<--volume>=I<volume name>

The name of the volume to create.

=back

=head1 CONFIGURATION

=head2 General Settings

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

    our $VARIABLE = VALUE;

where C<$VARIABLE> is the configuration variable being set and C<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:

=over 4

=item $VOLCREATE_CUTOFF

The cutoff proportion of candidate partitions that will be considered for
placement of a read/write volume.  The default is 0.2 (20%).  This can be
overridden with the B<-p> flag.

=item $VOLCREATE_MOUNT_PREFIX

If set, the path at which the volume is created must start with this
string.  This can be used to ensure that all registered mount points (when
B<loadmtpt> support is enabled) use a consistent naming scheme.  (All of
them pointing to the read/write volume or using the fully-qualified cell
name, for example.)

If this prefix starts with F</afs/.> and the path starts with the same
prefix but without the leading period (indicating read/write paths), the
leading period will be quietly added.  Otherwise, invalid arguments will
be rejected.

=item $ACLS

The path to a file containing ACL rules for volumes.  See L<ACL Rules>
below for more information about its syntax.  The default value is
F</etc/afs-admin-tools/acl-rules>.

=item $SERVERS

The path to a file containing a list of current AFS servers and their
volume types.  See L<AFS Servers> below for more information about its
syntax.  The default value is F</etc/afs-admin-tools/servers>.

=item $LOADMTPT

The full path to the B<loadmtpt> utility from afs-mountpoints.  If this
variable is set, B<loadmtpt> will be invoked for each new volume created
to record its mount point in the mount point database.  The default is the
empty string, which says to not run B<loadmtpt>.

=item $FS

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

=item $VOS

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

=back

=head2 ACL Rules

The file pointed to by the $ACLS configuration variable
(F</etc/afs-admin-tools/acl-rules> by default) contains rules specifying
the default ACLs that should be set on different types of volumes.  The
format of this file should be a regular expression matching a class of
volumes, surrounded by C<//> and starting in the first column, and then
followed by whitespace-indented user/ACL pairs that apply to that class of
volumes, one per line.  All matching regular expressions will contribute
their set of ACL settings to the final ACL string.  Any ACLs given on the
command line of volcreate will take precedence over the ones in this file
(but the ones in this file will still be applied -- the ACLs will be
merged).

A sample entry would be:

    /^(group|dept)\./
        system:anyuser read
        system:dept-admin all

Note that the regex line must not be indented (must begin in column one),
and the ACL lines must be indented.  Think of it as Python.

=head2 AFS Servers

The file pointed to by the $SERVERS configuration variable
(F</etc/afs-admin-tools/servers> by default) contains a list of AFS
servers that B<volcreate> should consider as potential hosts for new
volumes.  Each line should start with an AFS server name, optionally a
location for that server in square brackets, and then optionally contain a
space-separated list of types of volumes handled by that server.  Those
volume types may begin with a single letter or range of letters and a
colon, indicating that only the partition or partitions named handle that
type of volume.

Blank lines and lines beginning with C<#> are ignored.

For non-replicated volumes, the type in this file should match the type
given to B<volcreate>.  For replicated volumes, the type suffixed with
C<-rw> will be used for the read/write volume and the type suffixed with
C<-ro> will be used for the replicas.

So, for example, a sample entry would be:

    afssvr11 [sweet] a-c:logs d:pubsw-ro d:web-ro

When creating replicated volumes, B<volcreate> will attempt to put at
least one replica in every distinct location that accepts the C<-ro>
version of that volume type.  The names of the locations are arbitrary;
they can be any label as long as servers in the same location use the same
label.

=head1 EXAMPLES

Create the volume ls.mail.logs on afssvr14 /vicepa with a quota of 20MB
and mount it on /afs/.ir/site/leland/mail/logs:

    volcreate afssvr14 a ls.mail.logs 20 /afs/.ir/site/leland/mail/logs

Create ls.trip.nntp on afssvr3 /vicepc with a quota of 5MB and mount it on
/afs/.ir/site/leland/tripwire/nntp.Stanford.EDU.  Set a default ACL only
giving system:localhosts read access and rra all access.

    volcreate 3 c ls.trip.nntp 5 \
        /afs/.ir/site/leland/tripwire/nntp.Stanford.EDU \
        -clear system:localhosts read rra all

(this should all be typed on one line).  Note that C<fs setacl> flags like
B<-clear> are allowed.

Create a replicated volume with three replicas of type pubsw named
pubsw.byacc19 with a quota of 20MB and mount it at
/afs/.ir/pubsw/Languages/byacc-1.9.

    volcreate -t pubsw -r 3 pubsw.byacc19 20 \
        /afs/.ir/pubsw/Langauges/byacc-1.9

The correct ACLs for a pubsw volume will be set based on the F<acl-rules>
file.

Clone ls.trip.nntp into a new ls.trip.news volume, which will be mounted
at /afs/.ir/site/leland/tripwire/news.Stanford.EDU:

    volcreate -t logs -c ls.trip.nntp ls.trip.news 0 \
        /afs/.ir/site/leland/tripwire/news.Stanford.EDU

Note that the meaningless 0 quota value is ignored.

=head1 FILES

=over 4

=item F</etc/afs-admin-tools/servers>

The default path to a file containing a list of current AFS servers and
their volume types.  The path to this file can be overridden with the
$SERVERS configuration variable.

=item F</etc/afs-admin-tools/acl-rules>

The default path to file contains rules specifying the default ACLs that
should be set on different types of volumes.  The path to this file can be
overridden with the $ACLS configuration variable.

=back

=head1 AUTHORS

Neil Crellin <neilc@stanford.edu> and Russ Allbery <eagle@eyrie.org>.
Updated with Auristor support by Bill MacAllister <bill@ca-zephyr.org>.

=head1 COPYRIGHT AND LICENSE

Copyright 1998, 1999, 2000, 2002, 2004, 2005, 2011 The Board of Trustees
of the Leland Stanford Junior University.

Copyright 2018 Bill MacAllister <bill@ca-zephyr.org>

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

=head1 SEE ALSO

L<fs_mkmount(1)>, L<fs_setquota(1)>, L<fs_setacl(1)>, L<loadmtpt(1)>,
L<vos_create(1)>, L<vos_dump(1)>, L<vos_restore(1)>

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

=cut