=head1 NAME

backup addvolentry - Defines a volume entry in a volume set

=head1 SYNOPSIS

backup addvolentry B<-name> I<volume set name>  B<-server> I<machine name>
B<-partition> I<partition name>
B<-volumes> I<volume name (regular expression)>
[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]

backup addvole B<-n> I<volume set name>  B<-s> I<machine name> B<-p> I<partition name>
B<-v> I<volume name (regular expression)>
[B<-l>]  [B<-c> I<cell name>]  [B<-h>]

=head1 DESCRIPTION

The C<backup addvolentry> command adds a volume entry definition to the
existing volume set named by the B<-name> argument. A volume entry
definition can match one or more volumes, depending on the combination
of the B<-server>, B<-partition>, and B<-volumes> arguments.

For the B<-server> and B<-partition> arguments, provide either

=over

=item *

The name of one machine or partition

=item *

The metacharacter expression B<.*> (period and asterisk), which
matches every machine name or partition name in the Volume
Location Database (VLDB).

=back

For the B<-volumes> argument, specify a combination of alphanumeric
characters and one or more metacharacters to wildcard part or all of
the volume name. The B<Options> section lists the acceptable
metacharacters.

=head1 OPTIONS

=over 4

=item B<-name>

Names the volume set to which to add this volume entry
definition. The volume set must already exist (use the C<backup
addvolset> command to create it).

=item B<-server>

Defines the set of one or more file server machines that house
the volumes in the volume entry. Provide either one
fully-qualified hostname (such as B<fs1.abc.com>) or the
metacharacter expression B<.*> (period and asterisk), which
matches all machine names in the VLDB.

=item B<-partition>

Defines the set of one or more partitions that house the
volumes in the volume entry. Provide either one complete
partition name (such as B</vicepa>) or the metacharacter
expression B<.*> (period and asterisk), which matches all
partition names.

=item B<-volumes>

Defines the set of one or more volumes included in the volume
entry. Specify the volumes by name, by using any combination of
regular alphanumeric characters and one or more of the
following metacharacter expressions:

=over

=item B<.>

The period matches any single character.

=item B<*>

The asterisk matches zero or more instances of the
preceding character. Combine it with any other
alphanumeric character or metacharacter.

=item B<[ ]>

Square brackets around a list of characters match a
single instance of any of the characters, but no other
characters; for example, B<[abc]> matches a single B<a> or B<b> or
B<c>, but not B<d> or B<A>. This expression can be combined with
the asterisk.

=item B<^>

The caret, when used as the first character in a
square-bracketed set, designates a match with any single
character I<except> the characters that follow it; for
example, B<[^a]> matches any single character except
lowercase B<a>. This expression can be combined with the
asterisk.

=item B<\>

A backslash preceding any of the metacharacters in this
list makes it match its literal value only. For example,
the expression B<\.> (backslash and period) matches a single
period, B<\*> a single asterisk, and B<\\> a single backslash.
Such expressions can be combined with the asterisk (for
example, B<\.*> matches any number of periods).

=back

Perhaps the most common metacharacter expression is the period
followed by an asterisk (B<.*>). This expression matches any
string of any length, because the period matches any character
and the asterisk means any number of that character. As
mentioned, it is the only acceptable metacharacter expression
for the B<-server> and B<-partition> arguments. In a volume
definition it can stand alone (in which case it matches every
volume listed in the VLDB), or can combine with regular
characters. The following example matches any volume name that
begins with the string B<user> and ends with B<backup>:

B<user.*backup>

=item B<-localauth>

Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.

=item B<-cell>

Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 EXAMPLES

The following command adds a volume entry to the volume set called
B<sys>. The entry matches all volumes on any machine or partition whose
names begin with the string B<sun4x_56> followed by a period:

  backup> addvolentry sys .* .* sun4x_56\..*

The following command adds a volume entry to the volume set called
fs2, to match all volumes on the /vicepb partition of file server
machine fs2.abc.com. Because it is issued at the shell prompt, double
quotes surround the metacharacters in the -volumes argument. (The
command is shown here on two lines only for legibility reasons.)

  backup addvolentry -name fs2 -server fs2.abc.com \
                     -partition /vicepb -volumes ".*"

The chapter in the IBM AFS Administration Guide about configuring the
AFS Backup System presents additional examples as well as advice on
grouping volumes.

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.

=head1 CAVEATS

It is best to issue this command in interactive mode. If issuing it at
the shell prompt, enclose any strings containing metacharacters in
double quotes, or escape the metacharacters with other delimiters, to
prevent the shell from interpreting them. Adding volume entries to a
temporary volume set is possible only within the interactive session
in which the volume set was created.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<backup(1)>,
L<backup_addvolset(1)>,
L<backup_delvolentry(1)>,
L<backup_delvolset(1)>,
L<backup_listvolsets(1)>

=cut
