doc/man-pages/pod1/vos_remove.pod

   1 =head1 NAME
   2
   3 vos_remove - Removes a volume from a site
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<vos remove> S<<< [B<-server> <I<machine name>>] >>>
  11     S<<< [B<-partition> <I<partition name>>] >>>
  12     S<<< B<-id> <I<volume name or ID>> >>>
  13     S<<< [B<-cell> <I<cell name>>] >>>
  14     [B<-noauth>] [B<-localauth>]
  15     [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>]
  16
  17 B<vos remo> S<<< [B<-s> <I<machine name>>] >>>
  18     S<<< [B<-p> <I<partition name>>] >>>
  19     S<<< B<-i> <I<volume name or ID>> >>>
  20     S<<< [B<-c> <I<cell name>>] >>>
  21     [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>]
  22
  23 =for html
  24 </div>
  25
  26 =head1 DESCRIPTION
  27
  28 The B<vos remove> command removes the indicated volume from the partition
  29 on which it resides. The Volume Location Database (VLDB) record is altered
  30 appropriately, as described in the following paragraphs. Use this command
  31 to remove any of the three types of volumes; the effect depends on the
  32 type.
  33
  34 =over 4
  35
  36 =item *
  37
  38 If the B<-id> argument names the read/write volume (that is, specifies the
  39 volume's base name), both it and the associated backup volume are removed
  40 from the partition that houses them. The B<-server> and B<-partition>
  41 arguments are optional, because there can be only one read/write
  42 site. When the volume is removed, the site information is also removed
  43 from the VLDB entry. The read/write and backup volume ID numbers no longer
  44 appear in the output from the B<vos listvldb> or B<vos examine> commands,
  45 but they are preserved internally. Read-only sites, if any, are not
  46 affected, but cannot be changed unless a read/write site is again
  47 defined. The site count reported by the B<vos examine> and B<vos listvldb>
  48 commands as C<number of sites> decrements by one. The entire VLDB entry is
  49 removed if there are no read-only sites.
  50
  51 =item *
  52
  53 If the B<-id> argument names a read-only volume, it is removed from the
  54 partition that houses it, and the corresponding site information is
  55 removed from the VLDB entry. The site count reported by the B<vos examine>
  56 and B<vos listvldb> commands as C<number of sites> decrements by one for
  57 each volume you remove. If there is more than one read-only site, the
  58 B<-server> argument (and optionally B<-partition> argument) must be used
  59 to specify the site from which to remove the volume. If there is only one
  60 read-only site, the B<-id> argument is sufficient; if there is also no
  61 read/write volume in this case, the entire VLDB entry is removed.
  62
  63 =item *
  64
  65 If the B<-id> argument names a backup volume, it is removed from the
  66 partition that houses it. The B<-server> and B<-partition> arguments are
  67 optional, because there can be only one backup site. The backup volume ID
  68 number no longer appears in the output from the B<vos listvldb> command or
  69 in the corresponding portion of the output from the B<vos examine>
  70 command, but is preserved internally.
  71
  72 =back
  73
  74 This command is the most appropriate one for removing volumes in almost
  75 all cases. Other commands that remove only volumes or only VLDB entries
  76 (such as the B<vos delentry>, B<vos remsite> and B<vos zap> commands) by
  77 definition can put the volumes and VLDB out of sync. Use them only in the
  78 special circumstances mentioned on their reference pages. Like the B<vos
  79 delentry> command, this command can remove a VLDB entry when no
  80 corresponding volumes exist on the file server machine. Like the B<vos
  81 zap> command, this command can remove a volume that does not have a VLDB
  82 entry, as long as the volume is online, B<-server> and B<-partition>
  83 arguments are provided, and the B<-id> argument specifies the volume's ID
  84 number.
  85
  86 =head1 OPTIONS
  87
  88 =over 4
  89
  90 =item B<-server> <I<server name>>
  91
  92 Identifies the file server machine that houses the volume to remove. It is
  93 necessary only when the B<-id> argument names a read-only volume that
  94 exists at multiple sites. Provide the machine's IP address or its host
  95 name (either fully qualified or using an unambiguous abbreviation). For
  96 details, see L<vos(1)>.
  97
  98 =item B<-partition> <I<partition name>>
  99
 100 Identifies the partition (on the file server machine specified by the
 101 B<-server> argument) that houses the volume to remove. Provide the
 102 partition's complete name with preceding slash (for example, C</vicepa>)
 103 or use one of the three acceptable abbreviated forms. For details, see
 104 L<vos(1)>.
 105
 106 Including this argument is necessary only when the B<-id> argument names a
 107 read-only volume that exists at multiple sites. Provide the B<-server>
 108 argument along with this one.
 109
 110 =item B<-id> <I<volume name or id>>
 111
 112 Identifies the volume to remove, either by its complete name or volume ID
 113 number. If identifying a read-only or backup volume by name, include the
 114 appropriate extension (C<.readonly> or C<.backup>).
 115
 116 =item B<-cell> <I<cell name>>
 117
 118 Names the cell in which to run the command. Do not combine this argument
 119 with the B<-localauth> flag. For more details, see L<vos(1)>.
 120
 121 =item B<-noauth>
 122
 123 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 124 combine this flag with the B<-localauth> flag. For more details, see
 125 L<vos(1)>.
 126
 127 =item B<-localauth>
 128
 129 Constructs a server ticket using a key from the local
 130 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
 131 to the Volume Server and Volume Location Server during mutual
 132 authentication. Do not combine this flag with the B<-cell> argument or
 133 B<-noauth> flag. For more details, see L<vos(1)>.
 134
 135 =item B<-verbose>
 136
 137 Produces on the standard output stream a detailed trace of the command's
 138 execution. If this argument is omitted, only warnings and error messages
 139 appear.
 140
 141 =item B<-encrypt>
 142
 143 Encrypts the command so that the operation's results are not transmitted
 144 across the network in clear text. This option is available in OpenAFS
 145 versions 1.4.11 or later and 1.5.60 or later.
 146
 147 =item B<-noresolve>
 148
 149 Shows all servers as IP addresses instead of the DNS name. This is very
 150 useful when the server address is registered as 127.0.0.1 or when dealing
 151 with multi-homed servers. This option is available in OpenAFS
 152 versions 1.4.8 or later and 1.5.35 or later.
 153
 154 =item B<-help>
 155
 156 Prints the online help for this command. All other valid options are
 157 ignored.
 158
 159 =back
 160
 161 =head1 EXAMPLES
 162
 163 The following example removes the read/write volume C<user.terry> and its
 164 backup version, if any.
 165
 166    % vos remove  -id user.terry
 167
 168 The following example removes the read-only volume C<root.afs.readonly>
 169 from one of its sites, the F</vicepa> partition on the file server machine
 170 C<fs1.example.com>.
 171
 172    % vos remove fs1.example.com  a  root.afs.readonly
 173
 174 =head1 PRIVILEGE REQUIRED
 175
 176 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 177 machine specified with the B<-server> argument and on each database server
 178 machine. If the B<-localauth> flag is included, the issuer must instead be
 179 logged on to a server machine as the local superuser C<root>.
 180
 181 =head1 SEE ALSO
 182
 183 L<vos(1)>,
 184 L<vos_delentry(1)>,
 185 L<vos_remsite(1)>,
 186 L<vos_zap(1)>
 187
 188 =head1 COPYRIGHT
 189
 190 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 191
 192 This documentation is covered by the IBM Public License Version 1.0.  It was
 193 converted from HTML to POD by software written by Chas Williams and Russ
 194 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.