doc: Make all vos pages =include common options
[openafs.git] / doc / man-pages / pod1 / vos_delentry.pod.in
1 =head1 NAME
2
3 vos_delentry - Removes a volume entry from the VLDB.
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos delentry> S<<< [B<-id> <I<volume name or ID>>+] >>>
11    S<<< [B<-prefix> <I<prefix of volume whose VLDB entry is to be deleted>>] >>>
12     S<<< [B<-server> <I<machine name>>] >>>
13     S<<< [B<-partition> <I<partition name>>] >>>
14     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
15     [B<-dryrun>] [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
16     S<<< [B<-config> <I<config directory>>] >>>
17     [B<-help>]
18
19 B<vos de> S<<< [B<-i> <I<volume name or ID>>+] >>>
20     S<<< [B<-pr> <I<prefix of volume whose VLDB entry is to be deleted>>] >>>
21     S<<< [B<-s> <I<machine name>>] >>> S<<< [B<-pa> <I<partition name>>] >>>
22     S<<< [B<-c> <I<cell name>>] >>> [B<-noa>] [B<-l>]
23     [B<-d>] [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 delentry> command removes the Volume Location Database (VLDB)
33 entry for each specified volume. A specified volume can be any of the
34 three types (read/write, read-only, or backup), but the entire entry is
35 removed no matter which type is provided. The command has no effect on the
36 actual volumes on file server machines, if they exist.
37
38 This command is useful if a volume removal operation did not update the
39 VLDB (perhaps because the B<vos zap> command was used), but the system
40 administrator does not feel it is necessary to use the B<vos syncserv> and
41 B<vos syncvldb> commands to synchronize an entire file server machine.
42
43 To remove the VLDB entry for a single volume, use the B<-id> argument. To
44 remove groups of volumes, combine the B<-prefix>, B<-server>, and
45 B<-partition> arguments. The following list describes how to remove the
46 VLDB entry for the indicated group of volumes:
47
48 =over 4
49
50 =item *
51
52 For every volume whose name begins with a certain character string (for
53 example, C<sys.> or C<user.>): use the B<-prefix> argument.
54
55 =item *
56
57 Every volume for which the VLDB lists a site on a certain file server
58 machine: specify the file server name with the B<-server> argument.
59
60 =item *
61
62 Every volume for which the VLDB lists a site on a partition of the same
63 name (for instance, on the F</vicepa> partition on any file server
64 machine): specify the partition name with the B<-partition> argument.
65
66 =item *
67
68 Every volume for which the VLDB lists a site one a specific partition of a
69 file server machine: specify both the B<-server> and B<-partition>
70 arguments.
71
72 =item *
73
74 Every volume whose name begins with a certain prefix and for which the
75 VLDB lists a site on a file server machine: combine the B<-prefix> and
76 B<-server> arguments. Combine the B<-prefix> argument with the
77 B<-partition> argument, or both the B<-server> and B<-partition>
78 arguments, to remove a more specific group of volumes.
79
80 =back
81
82 =head1 CAUTIONS
83
84 Do not use this command to remove a volume in normal circumstances; it
85 does not remove a volume from the file server machine, and so is likely to
86 make the VLDB inconsistent with state of the volumes on server
87 machines. Use the B<vos remove> command to remove both the volume and its
88 VLDB entry.
89
90 =head1 OPTIONS
91
92 =over 4
93
94 =item B<-id> <I<volume name or ID>>+
95
96 Specifies the complete name or the volume ID number of each volume for
97 which to remove the VLDB entry. The entire entry is removed, regardless of
98 whether the read/write, read-only, or backup version is indicated.
99 Provide this argument or some combination of the B<-prefix>, B<-server>,
100 and B<-partition> arguments.
101
102 =item B<-prefix> <I<prefix of volume entry>
103
104 Specifies a character string of any length; the VLDB entry for a volume
105 whose name begins with the string is removed. Include field separators
106 (such as periods) if appropriate. Combine this argument with the
107 B<-server> argument, B<-partition> argument, or both.
108
109 =item B<-server> <I<server name>>
110
111 Identifies a file server machine; if a volume's VLDB entry lists a site on
112 the machine, the entry is removed. Provide the machine's IP address or its
113 host name (either fully qualified or using an unambiguous
114 abbreviation). For details, see L<vos(1)>.
115
116 Combine this argument with the B<-prefix> argument, the B<-partition>
117 argument, or both.
118
119 =item B<-partition> <I<partition name>>
120
121 Identifies a partition; if a volume's VLDB entry lists a site on the
122 partition, the entry is removed. Provide the partition's complete name
123 with preceding slash (for example, F</vicepa>) or use one of the three
124 acceptable abbreviated forms. For details, see L<vos(1)>.
125
126 Combine this argument with the B<-prefix> argument, the B<-server>
127 argument, or both.
128
129 =item B<-dryrun>
130
131 Show the actions which would be taken, but do not make changes.
132
133 =include fragments/vos-common.pod
134
135 =back
136
137 =head1 OUTPUT
138
139 The following message confirms the success of the command by indicating
140 how many VLDB entries were removed.
141
142    Deleted <number> VLDB entries
143
144 =head1 EXAMPLES
145
146 The following command removes the VLDB entry for the volume C<user.temp>.
147
148    % vos delentry user.temp
149
150 The following command removes the VLDB entry for every volume whose name
151 begins with the string C<test> and for which the VLDB lists a site on the
152 file server machine C<fs3.example.com>.
153
154    % vos delentry -prefix test -server fs3.example.com
155
156 =head1 PRIVILEGE REQUIRED
157
158 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
159 machine specified with the B<-server> argument and on each database server
160 machine. If the B<-localauth> flag is included, the issuer must instead be
161 logged on to a server machine as the local superuser C<root>.
162
163 =head1 SEE ALSO
164
165 L<vos(1)>,
166 L<vos_remove(1)>,
167 L<vos_syncserv(1)>,
168 L<vos_syncvldb(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.