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