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