Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | vos - Introduction to the vos command suite | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The commands in the B<vos> command suite are the administrative interface | |
8 | to the Volume Server and Volume Location (VL) Server. System | |
9 | administrators use B<vos> commands to create, move, delete, replicate, | |
10 | back up and examine volumes, among other operations. The VL Server | |
11 | automatically records in the Volume Location Database (VLDB) changes in | |
12 | volume status and location that result from B<vos> commands. | |
13 | ||
14 | The operations invoked by most B<vos> commands are idempotent, meaning | |
15 | that if an operation is interrupted by a network, server machine, or | |
16 | process outage, then a subsequent attempt at the same operation continues | |
17 | from the interruption point, rather than starting over at the beginning of | |
18 | the operation. Before executing a command, the Volume and VL Servers check | |
19 | the current state of the volumes and VLDB records to be altered by the | |
20 | command. If they are already in the desired end state (or a consistent | |
21 | intermediate state), there is no need to repeat the internal steps that | |
22 | brought them there. Idempotency does not apply if the command issuer | |
23 | explicitly interrupts the operation with the Ctrl-C command or another | |
24 | interrupt signal. In that case, the volume is left locked and the | |
25 | administrator must use the L<B<vos unlock>|vos_unlock(1)> command to | |
26 | unlock it before proceeding. | |
27 | ||
28 | It is important that the VLDB accurately indicate the status of the | |
29 | volumes on file server machines at all times. L<vldb.DB0(5)> and | |
30 | L<afs_volume_header(5)> describe the information recorded in the VLDB and | |
31 | volume headers, respectively. If a B<vos> command changes volume status, | |
32 | it automatically records the change in the corresponding VLDB entry. The | |
33 | most common cause of discrepancies between the VLDB and volume status on | |
34 | file server machines is interrupted operations; to restore consistency, | |
35 | use the L<B<vos syncserv>|vos_syncserv(1)> and | |
36 | L<B<vos syncvldb>|vos_syncvldb(1)> commands. | |
37 | ||
38 | There are several categories of commands in the vos command suite: | |
39 | ||
40 | =over 4 | |
41 | ||
42 | =item * | |
43 | ||
44 | Commands to create, move, and rename volumes: | |
45 | L<B<vos backup>|vos_backup(1)>, | |
46 | L<B<vos backupsys>|vos_backupsys(1)>, | |
47 | L<B<vos changeloc>|vos_changeloc(1)>, | |
48 | L<B<vos create>|vos_create(1)>, | |
49 | L<B<vos move>|vos_move(1)>, | |
50 | and L<B<vos rename>|vos_rename(1)>. | |
51 | ||
52 | =item * | |
53 | ||
54 | Commands to remove VLDB volume records or volumes or both: | |
55 | L<B<vos delentry>|vos_delentry(1)>, | |
56 | L<B<vos remove>|vos_remove(1)>, | |
57 | and L<B<vos zap>|vos_zap(1)>. | |
58 | ||
59 | =item * | |
60 | ||
61 | Commands to edit or display VLDB server entries: | |
62 | L<B<vos changeaddr>|vos_changeaddr(1)>, | |
63 | L<B<vos listaddrs>|vos_listaddrs(1)> | |
64 | L<B<vos setaddrs>|vos_setaddrs(1)>, | |
65 | and L<B<vos remaddrs>|vos_remaddrs(1)>. | |
66 | ||
67 | =item * | |
68 | ||
69 | Commands to create, size, and restore dump files: | |
70 | L<B<vos dump>|vos_dump(1)>, | |
71 | L<B<vos restore>|vos_restore(1)>, | |
72 | and L<B<vos size>|vos_size(1)>. | |
73 | ||
74 | =item * | |
75 | ||
76 | Commands to administer replicated volumes: | |
77 | L<B<vos addsite>|vos_addsite(1)>, | |
78 | L<B<vos release>|vos_release(1)>, | |
79 | and L<B<vos remsite>|vos_remsite(1)>. | |
80 | ||
81 | =item * | |
82 | ||
83 | Commands to display VLDB records, volume headers, or both: | |
84 | L<B<vos examine>|vos_examine(1)>, | |
85 | L<B<vos listvldb>|vos_listvldb(1)>, | |
86 | and L<B<vos listvol>|vos_listvol(1)>. | |
87 | ||
88 | =item * | |
89 | ||
90 | Commands to display information about partitions that house volumes: | |
91 | L<B<vos listpart>|vos_listpart(1)> | |
92 | and L<B<vos partinfo>|vos_partinfo(1)>. | |
93 | ||
94 | =item * | |
95 | ||
96 | Commands to restore consistency between the VLDB and volume headers: | |
97 | L<B<vos syncserv>|vos_syncserv(1)> | |
98 | and L<B<vos syncvldb>|vos_syncvldb(1)>. | |
99 | ||
100 | =item * | |
101 | ||
102 | Commands to lock and unlock VLDB entries: | |
103 | L<B<vos lock>|vos_lock(1)>, | |
104 | L<B<vos unlock>|vos_unlock(1)>, | |
105 | and L<B<vos unlockvldb>|vos_unlockvldb(1)>. | |
106 | ||
107 | =item * | |
108 | ||
109 | A command to report Volume Server status: | |
110 | L<B<vos status>|vos_status(1)>. | |
111 | ||
112 | =item * | |
113 | ||
114 | A command to end Volume Server transactions: | |
115 | L<B<vos endtrans>|vos_endtrans(1)>. | |
116 | ||
117 | =item * | |
118 | ||
119 | A command to change volume fields: | |
120 | L<B<vos setfields>|vos_setfields(1)>. | |
121 | ||
122 | =item * | |
123 | ||
124 | Commands to obtain help: | |
125 | L<B<vos apropos>|vos_apropos(1)> | |
126 | and L<B<vos help>|vos_help(1)>. | |
127 | ||
128 | =back | |
129 | ||
130 | =head1 CAUTIONS | |
131 | ||
132 | =include fragments/volsize-caution.pod | |
133 | ||
134 | =head1 OPTIONS | |
135 | ||
136 | The following arguments and flags are available on many commands in the | |
137 | B<vos> suite. The reference page for each command also lists them, but | |
138 | they are described here in greater detail. | |
139 | ||
140 | =over 4 | |
141 | ||
142 | =item B<-cell> <I<cell name>> | |
143 | ||
144 | Names the cell in which to run the command. It is acceptable to abbreviate | |
145 | the cell name to the shortest form that distinguishes it from the other | |
146 | entries in the F</usr/vice/etc/CellServDB> file on the local machine. If | |
147 | the B<-cell> argument is omitted, the command interpreter determines the | |
148 | name of the local cell by reading the following in order: | |
149 | ||
150 | =over 4 | |
151 | ||
152 | =item * | |
153 | ||
154 | The value of the AFSCELL environment variable. | |
155 | ||
156 | =item * | |
157 | ||
158 | The local F</usr/vice/etc/ThisCell> file. | |
159 | ||
160 | =back | |
161 | ||
162 | Do not combine the B<-cell> and B<-localauth> options. A command on which | |
163 | the B<-localauth> flag is included always runs in the local cell (as | |
164 | defined in the server machine's local F</usr/afs/etc/ThisCell> file), | |
165 | whereas a command on which the B<-cell> argument is included runs in the | |
166 | specified foreign cell. | |
167 | ||
168 | =item B<-config> <I<config directory>> | |
169 | ||
170 | The location of the directory to use to obtain configuration information, | |
171 | including the CellServDB. This is primarily provided for testing purposes. | |
172 | ||
173 | =item B<-help> | |
174 | ||
175 | Prints a command's online help message on the standard output stream. Do | |
176 | not combine this flag with any of the command's other options; when it is | |
177 | provided, the command interpreter ignores all other options, and only | |
178 | prints the help message. | |
179 | ||
180 | =item B<-localauth> | |
181 | ||
182 | Constructs a server ticket using the server encryption key with the | |
183 | highest key version number in the local F</usr/afs/etc/KeyFile> file. The | |
184 | B<vos> command interpreter presents the ticket, which never expires, to | |
185 | the Volume Server and VL Server during mutual authentication. | |
186 | ||
187 | Use this flag only when issuing a command on a server machine; client | |
188 | machines do not usually have a F</usr/afs/etc/KeyFile> file. The issuer | |
189 | of a command that includes this flag must be logged on to the server | |
190 | machine as the local superuser C<root>. The flag is useful for commands | |
191 | invoked by an unattended application program, such as a process controlled | |
192 | by the UNIX B<cron> utility or by a cron entry in the machine's | |
193 | F</usr/afs/local/BosConfig> file. It is also useful if an administrator is | |
194 | unable to authenticate to AFS but is logged in as the local superuser | |
195 | B<root>. | |
196 | ||
197 | Do not combine the B<-cell> and B<-localauth> options. A command on which | |
198 | the B<-localauth> flag is included always runs in the local cell (as | |
199 | defined in the server machine's local F</usr/afs/etc/ThisCell> file), | |
200 | whereas a command on which the B<-cell> argument is included runs in the | |
201 | specified foreign cell. Also, do not combine the B<-localauth> and | |
202 | B<-noauth> flags. | |
203 | ||
204 | =item B<-noauth> | |
205 | ||
206 | Establishes an unauthenticated connection to the Volume Server and VL | |
207 | Server, in which the servers treat the issuer as the unprivileged user | |
208 | C<anonymous>. It is useful only when authorization checking is disabled on | |
209 | the server machine (during the installation of a file server machine or | |
210 | when the L<B<bos setauth>|bos_setauth(8)> command has been used during | |
211 | other unusual circumstances). In normal circumstances, the servers allow | |
212 | only privileged users to issue commands that change the status of a volume | |
213 | or VLDB record, and refuses to perform such an action even if the | |
214 | B<-noauth> flag is provided. Do not combine the B<-noauth> and | |
215 | B<-localauth> flags. | |
216 | ||
217 | =item B<-partition> <I<partition name>> | |
218 | ||
219 | Identifies the AFS server partition on a file server machine that houses, | |
220 | or is to house, the volumes of interest, or about which to list | |
221 | information. The B<vos> command interpreter accepts any of the following | |
222 | four name formats: | |
223 | ||
224 | /vicepa = vicepa = a = 0 | |
225 | /vicepb = vicepb = b = 1 | |
226 | ||
227 | After /vicepz (for which the index is 25) comes | |
228 | ||
229 | /vicepaa = vicepaa = aa = 26 | |
230 | /vicepab = vicepab = ab = 27 | |
231 | ||
232 | and so on through | |
233 | ||
234 | /vicepiv = vicepiv = iv = 255 | |
235 | ||
236 | The B<-frompartition> and B<-topartition> arguments to the | |
237 | L<B<vos move>|vos_move(1)> command also accept this notation. | |
238 | ||
239 | =item B<-server> <I<machine name>> | |
240 | ||
241 | Identifies the file server machine that houses, or is to house, the | |
242 | volumes or AFS server partitions of interest. Provide the machine's IP | |
243 | address in dotted decimal format, its fully qualified host name (for | |
244 | example, C<fs1.example.com>), or the shortest abbreviated form of its host | |
245 | name that distinguishes it from other machines. Successful use of an | |
246 | abbreviated form depends on the availability of a name resolution service | |
247 | (such as the Domain Name Service or a local host table) at the time the | |
248 | command is issued. | |
249 | ||
250 | The B<-fromserver> and B<-toserver> arguments to the | |
251 | L<B<vos move>|vos_move(1)> command also accept these name formats. | |
252 | ||
253 | =item B<-noresolve> | |
254 | ||
255 | Shows all servers as IP addresses instead of the DNS name. This is very | |
256 | useful when the server address is registered as 127.0.0.1 or when dealing | |
257 | with multi-homed servers. The B<-noresolve> option is available in OpenAFS | |
258 | versions 1.4.8 or later and 1.5.35 or later. | |
259 | ||
260 | =item B<-verbose> | |
261 | ||
262 | Produces on the standard output stream a detailed trace of the command's | |
263 | execution. If this argument is omitted, only warnings and error messages | |
264 | appear. | |
265 | ||
266 | =back | |
267 | ||
268 | =head1 PRIVILEGE REQUIRED | |
269 | ||
270 | To issue most vos commands, the issuer must be listed in the | |
271 | F</usr/afs/etc/UserList> file on each server machine that houses or is to | |
272 | house an affected volume, and on each database server machine. The most | |
273 | predictable performance results if all database server and file server | |
274 | machines in the cell share a common F<UserList> file. Alternatively, if | |
275 | the B<-localauth> flag is included, the issuer must be logged on to a | |
276 | server machine as the local superuser C<root>. | |
277 | ||
278 | To issue a vos command that only displays information, no privilege is | |
279 | required. | |
280 | ||
281 | =head1 SEE ALSO | |
282 | ||
283 | L<vos_addsite(1)>, | |
284 | L<vos_apropos(1)>, | |
285 | L<vos_backup(1)>, | |
286 | L<vos_backupsys(1)>, | |
287 | L<vos_changeaddr(1)>, | |
288 | L<vos_convertROtoRW(1)>, | |
289 | L<vos_clone(1)>, | |
290 | L<vos_copy(1)>, | |
291 | L<vos_create(1)>, | |
292 | L<vos_delentry(1)>, | |
293 | L<vos_dump(1)>, | |
294 | L<vos_endtrans(1)>, | |
295 | L<vos_examine(1)>, | |
296 | L<vos_help(1)>, | |
297 | L<vos_listaddrs(1)>, | |
298 | L<vos_listpart(1)>, | |
299 | L<vos_listvldb(1)>, | |
300 | L<vos_listvol(1)>, | |
301 | L<vos_lock(1)>, | |
302 | L<vos_move(1)>, | |
303 | L<vos_partinfo(1)>, | |
304 | L<vos_release(1)>, | |
305 | L<vos_remove(1)>, | |
306 | L<vos_remsite(1)>, | |
307 | L<vos_rename(1)>, | |
308 | L<vos_restore(1)>, | |
309 | L<vos_setfields(1)>, | |
310 | L<vos_shadow(1)>, | |
311 | L<vos_size(1)>, | |
312 | L<vos_status(1)>, | |
313 | L<vos_syncserv(1)>, | |
314 | L<vos_syncvldb(1)>, | |
315 | L<vos_unlock(1)>, | |
316 | L<vos_unlockvldb(1)>, | |
317 | L<vos_zap(1)>, | |
318 | L<CellServDB(5)>, | |
319 | L<UserList(5)> | |
320 | ||
321 | =head1 COPYRIGHT | |
322 | ||
323 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
324 | ||
325 | This documentation is covered by the IBM Public License Version 1.0. It was | |
326 | converted from HTML to POD by software written by Chas Williams and Russ | |
327 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |