1ac8640b39bbebfa449a523a2dae7be50d9ca8ac
[openafs.git] / doc / man-pages / pod1 / vos_remove.pod.in
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 =include fragments/vos-common.pod
121
122 =back
123
124 =head1 EXAMPLES
125
126 The following example removes the read/write volume C<user.terry> and its
127 backup version, if any.
128
129    % vos remove  -id user.terry
130
131 The following example removes the read-only volume C<root.afs.readonly>
132 from one of its sites, the F</vicepa> partition on the file server machine
133 C<fs1.example.com>.
134
135    % vos remove fs1.example.com  a  root.afs.readonly
136
137 =head1 PRIVILEGE REQUIRED
138
139 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
140 machine specified with the B<-server> argument and on each database server
141 machine. If the B<-localauth> flag is included, the issuer must instead be
142 logged on to a server machine as the local superuser C<root>.
143
144 =head1 SEE ALSO
145
146 L<vos(1)>,
147 L<vos_delentry(1)>,
148 L<vos_remsite(1)>,
149 L<vos_zap(1)>
150
151 =head1 COPYRIGHT
152
153 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
154
155 This documentation is covered by the IBM Public License Version 1.0.  It was
156 converted from HTML to POD by software written by Chas Williams and Russ
157 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.