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