volcreate

(Create and mount a new AFS volume)

SYNOPSIS

volcreate [-hnqv] [-c clone-from] [-p cutoff] server part volume quota mount [acl ...]

volcreate [-hnqv] [-c clone-from] -t type [-p cutoff] [-r replicas] volume quota mount [acl ...]

DESCRIPTION

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.

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 afssvr prepended to them.

part is the partition on which to create that volume. 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 a random partition on that server in the top 20% in free space according to vos partinfo is chosen, or as a string of letters and letter ranges such as 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 -p option.

Alternately, rather than giving a server and partition, volcreate accepts the -t option to specify a volume type. If this option is given, no server or partition is necessary and 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 -p option. For more information on defining volume types and associating them with appropriate servers and partitions, see CONFIGURATION below.

When -t is given, -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 replicas partitions with the most free space.

volume is the name of the volume to create. quota is its quota in megabytes (not in kilobytes). mount is the full path to the intended mount location of the volume (this must begin with "/afs/.ir/" so that the mount point database remains consistent). acl is any normal ACL arguments to fs setacl.

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

OPTIONS

-c clone-from, --clone=clone-from

Rather than creating a new, empty volume, clone the newly created volume from the volume clone-from. This dumps the old volume into /tmp, so be careful to do this on a system with a lot of space in /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.)

-h, --help

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

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

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

-p cutoff, --proportion=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.

-q, --quiet

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

-r replicas, --replicas=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 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. -t must be given if this option is used.

-t type, --type=type

Create a volume of the specified type. When this option is used, no server or partition should be specified, and instead 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 -r.

-v, --version

Print out the version of volcreate and quit.

CONFIGURATION

General Settings

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

$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 -p flag.

$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 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 /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.

$ACLS

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

$SERVERS

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

$LOADMTPT

The full path to the loadmtpt utility from afs-mountpoints. If this variable is set, 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 loadmtpt.

$FS

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

$VOS

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

ACL Rules

The file pointed to by the $ACLS configuration variable (/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 // 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.

AFS Servers

The file pointed to by the $SERVERS configuration variable (/etc/afs-admin-tools/servers by default) contains a list of AFS servers that 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 # are ignored.

For non-replicated volumes, the type in this file should match the type given to volcreate. For replicated volumes, the type suffixed with -rw will be used for the read/write volume and the type suffixed with -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, volcreate will attempt to put at least one replica in every distinct location that accepts the -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.

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 fs setacl flags like -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 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.

FILES

/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.

/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.

AUTHORS

Neil Crellin <neilc@stanford.edu> and Russ Allbery <eagle@eyrie.org>.

COPYRIGHT AND LICENSE

Copyright 1998, 1999, 2000, 2002, 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

fs_mkmount(1), fs_setquota(1), fs_setacl(1), loadmtpt(1), vos_create(1), vos_dump(1), 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 <http://www.eyrie.org/~eagle/software/afs-admin-tools/>.

Last spun 2022-12-12 from POD modified 2014-09-06