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