doc/man-pages/pod8/backup_addvolentry.pod

   1 =head1 NAME
   2
   3 backup addvolentry - Defines a volume entry in a volume set
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<backup addvolentry> S<<< B<-name> <I<volume set name>> >>>
  11     S<<< B<-server> <I<machine name>> >>> S<<< B<-partition> <I<partition name>> >>>
  12     S<<< B<-volumes> <I<volume name (regular expression)>> >>>
  13     [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
  14
  15 B<backup addvole> S<<< B<-n> <I<volume set name>> >>> S<<< B<-s> <I<machine name>> >>>
  16     S<<< B<-p> <I<partition name>> >>> S<<< B<-v> <I<volume name (regular expression)>> >>>
  17     [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
  18
  19 =for html
  20 </div>
  21
  22 =head1 DESCRIPTION
  23
  24 The B<backup addvolentry> command adds a volume entry definition to the
  25 existing volume set named by the B<-name> argument. A volume entry
  26 definition can match one or more volumes, depending on the combination of
  27 the B<-server>, B<-partition>, and B<-volumes> arguments.
  28
  29 For the B<-server> and B<-partition> arguments, provide either
  30
  31 =over 4
  32
  33 =item *
  34
  35 The name of one machine or partition.
  36
  37 =item *
  38
  39 The metacharacter expression .* (period and asterisk), which matches every
  40 machine name or partition name in the Volume Location Database (VLDB).
  41
  42 =back
  43
  44 For the B<-volumes> argument, specify a combination of alphanumeric
  45 characters and one or more metacharacters to wildcard part or all of the
  46 volume name. L<OPTIONS> lists the acceptable metacharacters.
  47
  48 =head1 CAUTIONS
  49
  50 It is best to issue this command in interactive mode. If issuing it at the
  51 shell prompt, enclose any strings containing metacharacters in double
  52 quotes, or escape the metacharacters with other delimiters, to prevent the
  53 shell from interpreting them. Adding volume entries to a temporary volume
  54 set is possible only within the interactive session in which the volume
  55 set was created.
  56
  57 =head1 OPTIONS
  58
  59 =over 4
  60
  61 =item B<-name> <I<volume set name>>
  62
  63 Names the volume set to which to add this volume entry definition.  The
  64 volume set must already exist (use the B<backup addvolset> command to
  65 create it).
  66
  67 =item B<-server> <I<machine name>>
  68
  69 Defines the set of one or more file server machines that house the volumes
  70 in the volume entry. Provide either one fully-qualified hostname (such as
  71 C<fs1.abc.com>) or the metacharacter expression C<.*> (period and
  72 asterisk), which matches all machine names in the VLDB.
  73
  74 =item B<-partition> <I<partition name>>
  75
  76 Defines the set of one or more partitions that house the volumes in the
  77 volume entry. Provide either one complete partition name (such as
  78 C</vicepa>) or the metacharacter expression C<.*> (period and asterisk),
  79 which matches all partition names.
  80
  81 =item B<-volumes> <I<volume name>>
  82
  83 Defines the set of one or more volumes included in the volume
  84 entry. Specify the volumes by name, by using any combination of regular
  85 alphanumeric characters and one or more of the following metacharacter
  86 expressions:
  87
  88 =over 4
  89
  90 =item .
  91
  92 The period matches any single character.
  93
  94 =item *
  95
  96 The asterisk matches zero or more instances of the preceding character.
  97 Combine it with any other alphanumeric character or metacharacter.
  98
  99 =item [ ]
 100
 101 Square brackets around a list of characters match a single instance of any
 102 of the characters, but no other characters; for example, C<[abc]> matches
 103 a single C<a> or C<b> or C<c>, but not C<d> or C<A>. This expression can
 104 be combined with the asterisk.
 105
 106 =item ^
 107
 108 The caret, when used as the first character in a square-bracketed set,
 109 designates a match with any single character I<except> the characters that
 110 follow it; for example, C<[^a]> matches any single character except
 111 lowercase C<a>. This expression can be combined with the asterisk.
 112
 113 =item \
 114
 115 A backslash preceding any of the metacharacters in this list makes it
 116 match its literal value only. For example, the expression C<\.> (backslash
 117 and period) matches a single period, C<\*> a single asterisk, and C<\\> a
 118 single backslash.  Such expressions can be combined with the asterisk (for
 119 example, C<\.*> matches any number of periods).
 120
 121 =back
 122
 123 Perhaps the most common metacharacter expression is the period followed by
 124 an asterisk (C<.*>). This expression matches any string of any length,
 125 because the period matches any character and the asterisk means any number
 126 of that character. As mentioned, it is the only acceptable metacharacter
 127 expression for the B<-server> and B<-partition> arguments. In a volume
 128 definition it can stand alone (in which case it matches every volume
 129 listed in the VLDB), or can combine with regular characters. The following
 130 example matches any volume name that begins with the string C<user> and
 131 ends with C<backup>:
 132
 133    user.*backup
 134
 135 =item B<-localauth>
 136
 137 Constructs a server ticket using a key from the local
 138 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
 139 it to the Backup Server, Volume Server and VL Server during mutual
 140 authentication. Do not combine this flag with the B<-cell> argument. For
 141 more details, see L<backup(8)>.
 142
 143 =item B<-cell> <I<cell name>>
 144
 145 Names the cell in which to run the command. Do not combine this argument
 146 with the B<-localauth> flag. For more details, see L<backup(8)>.
 147
 148 =item B<-help>
 149
 150 Prints the online help for this command. All other valid options are
 151 ignored.
 152
 153 =back
 154
 155 =head1 EXAMPLES
 156
 157 The following command adds a volume entry to the volume set called
 158 C<sys>. The entry matches all volumes on any machine or partition whose
 159 names begin with the string C<sun4x_56> followed by a period:
 160
 161    backup> addvolentry sys .* .* sun4x_56\..*
 162
 163 The following command adds a volume entry to the volume set called C<fs2>,
 164 to match all volumes on the F</vicepb> partition of file server machine
 165 C<fs2.abc.com>. Because it is issued at the shell prompt, double quotes
 166 surround the metacharacters in the B<-volumes> argument. (The command is
 167 shown here on two lines only for legibility reasons.)
 168
 169    % backup addvolentry -name fs2 -server fs2.abc.com \
 170                         -partition /vicepb -volumes ".*"
 171
 172 The chapter in the I<IBM AFS Administration Guide> about configuring the
 173 AFS Backup System presents additional examples as well as advice on
 174 grouping volumes.
 175
 176 =head1 PRIVILEGE REQUIRED
 177
 178 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 179 machine where the Backup Server is running, or must be logged onto a
 180 server machine as the local superuser C<root> if the B<-localauth> flag is
 181 included.
 182
 183 =head1 SEE ALSO
 184
 185 L<backup(8)>,
 186 L<backup_addvolset(8)>,
 187 L<backup_delvolentry(8)>,
 188 L<backup_delvolset(8)>,
 189 L<backup_listvolsets(8)>
 190
 191 =head1 COPYRIGHT
 192
 193 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 194
 195 This documentation is covered by the IBM Public License Version 1.0.  It was
 196 converted from HTML to POD by software written by Chas Williams and Russ
 197 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.