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