doc: the last partition name is /vicepiu
[openafs.git] / doc / man-pages / pod1 / afs.pod
1 =head1 NAME
2
3 afs - Introduction to AFS commands
4
5 =head1 DESCRIPTION
6
7 AFS provides many commands that enable users and system administrators to
8 use and customize its features. Many of the commands belong to the
9 following categories, called I<command suites>.
10
11 =over 4
12
13 =item backup
14
15 Interface for configuring and operating the AFS Backup System.
16
17 =item bos
18
19 Interface to the Basic Overseer (BOS) Server for administering server
20 processes and configuration files.
21
22 =item fs
23
24 Interface for administering access control lists (ACLs), the Cache
25 Manager, and other miscellaneous file system functions.
26
27 =item fstrace
28
29 Interface for tracing Cache Manager operations when debugging problems.
30
31 =item kas
32
33 Interface to the Authentication Server for administering security and
34 authentication information. This aspect of OpenAFS has been deprecated.
35
36 =item pts
37
38 Interface to the Protection Server for administering AFS ID and group
39 membership information.
40
41 =item uss
42
43 Interface for automated administration of user accounts. Deprecated, may
44 be removed from a future version of OpenAFS. See B<uss> man page for more
45 detail.
46
47 =item vos
48
49 Interface to the Volume Server and Volume Location (VL) Server for
50 administering volumes.
51
52 =back
53
54 In addition, there are several commands that do not belong to
55 suites.
56
57 =head2 AFS Command Syntax
58
59 AFS commands that belong to suites have the following structure:
60
61 I<command_suite> I<operation_code> B<-switch> <I<value>>[+] [B<-flag>]
62
63 =head3 Command Names
64
65 Together, the I<command_suite> and I<operation_code> make up the I<command
66 name>.
67
68 The I<command_suite> specifies the group of related commands to which the
69 command belongs, and indicates which command interpreter and server
70 process perform the command.  AFS has several command suites, including
71 B<bos>, B<fs>, B<kas>, B<pts>, B<uss> (deprecated) and B<vos>.
72 Some of these suites have an interactive mode in which the issuer omits the
73 I<operation_code> portion of the command name.
74
75 The I<operation_code> tells the command interpreter and server process
76 which action to perform. Most command suites include several operation
77 codes. The man pages for each command name describe each operation code in
78 detail, and the I<OpenAFS Administration Guide> describes how to use them
79 in the context of performing administrative tasks.
80
81 Several AFS commands do not belong to a suite and so their names do not
82 have a I<command_suite> portion. Their structure is otherwise similar to
83 the commands in the suites.
84
85 =head3 Options
86
87 The term I<option> refers to both arguments and flags, which are described
88 in the following sections.
89
90 =head3 Arguments
91
92 One or more arguments can follow the command name. Arguments specify the
93 entities on which to act while performing the command (for example, which
94 server machine, server process, or file). To minimize the potential for
95 error, provide a command's arguments in the order prescribed in its syntax
96 definition.
97
98 Each argument has two parts, which appear in the indicated order:
99
100 =over 4
101
102 =item *
103
104 The I<switch> specifies the argument's type and is preceded by a hyphen
105 (B<->). For instance, the switch B<-server> usually indicates that the
106 argument names a server machine. Switches can often be omitted, subject to
107 the rules outlined in L<"Conditions for Omitting Switches">.
108
109 =item *
110
111 The I<value> names a particular entity of the type specified by the
112 preceding switch. For example, the proper value for a B<-server> switch is
113 a server machine name like C<fs3.example.com>. Unlike switches (which have a
114 required form), values vary depending on what the issuer wants to
115 accomplish. Values appear surrounded by angle brackets (C<< <> >>) in
116 command descriptions and the online help to show that they are
117 user-supplied variable information.
118
119 =back
120
121 Some arguments accept multiple values, as indicated by trailing plus sign
122 (C<+>) in the command descriptions and online help. How many of a
123 command's arguments take multiple values, and their ordering with respect
124 to other arguments, determine when it is acceptable to omit switches. See
125 L<"Conditions for Omitting Switches">.
126
127 Some commands have optional as well as required arguments; the command
128 descriptions and online help show optional arguments in square brackets
129 (C<[]>).
130
131 =head3 Flags
132
133 Some commands have one or more flags, which specify the manner in which
134 the command interpreter and server process perform the command, or what
135 kind of output it produces. Flags are preceded by hyphens like switches,
136 but they take no values. Although the command descriptions and online help
137 generally list a command's flags after its arguments, there is no
138 prescribed order for flags. They can appear anywhere on the command line
139 following the operation code, except in between the parts of an
140 argument. Flags are always optional.
141
142 =head3 An Example Command
143
144 The following example illustrates the different parts of a command that
145 belongs to an AFS command suite.
146
147    % bos getdate -server fs1.example.com -file ptserver kaserver
148
149 where
150
151 =over 4
152
153 =item *
154
155 B<bos> is the command suite. The BOS Server executes most of the commands
156 in this suite.
157
158 =item *
159
160 B<getdate> is the operation code. It tells the BOS Server on the specified
161 server machine (in this case C<fs1.example.com>) to report the modification
162 dates of binary files in the local F</usr/afs/bin> directory.
163
164 =item *
165
166 C<-server fs1.example.com> is one argument, with B<-server> as the switch and
167 C<fs1.example.com> as the value. This argument specifies the server machine on
168 which BOS Server is to collect and report binary dates.
169
170 =item *
171
172 C<-file ptserver kaserver> is an argument that takes multiple values. The
173 switch is B<-file> and the values are C<ptserver> and C<kaserver>. This
174 argument tells the BOS Server to report the modification dates on the
175 files F</usr/afs/bin/kaserver> and F</usr/afs/bin/ptserver>.
176
177 =back
178
179 =head3 Rules for Entering AFS Commands
180
181 Enter each AFS command on a single line (press <Return> only at the end of
182 the command). Some commands in this document appear broken across multiple
183 lines, but that is for legibility only.
184
185 Use a space to separate each element on a command line from its
186 neighbors. Spaces rather than commas also separate multiple values of an
187 argument.
188
189 In many cases, the issuer of a command can reduce the amount of typing
190 necessary by using one or both of the following methods:
191
192 =over 4
193
194 =item *
195
196 Omitting switches.
197
198 =item *
199
200 Using accepted abbreviations for operation codes, switches (if they are
201 included at all), and some types of values.
202
203 =back
204
205 The following sections explain the conditions for omitting or shortening
206 parts of the command line. It is always acceptable to type a command in
207 full, with all of its switches and no abbreviations.
208
209 =head4 Conditions for Omitting Switches
210
211 It is always acceptable to type the switch part of an argument, but in
212 many cases it is not necessary. Specifically, switches can be omitted if
213 the following conditions are met.
214
215 =over 4
216
217 =item *
218
219 All of the command's required arguments appear in the order prescribed by
220 the syntax statement.
221
222 =item *
223
224 No switch is provided for any argument.
225
226 =item *
227
228 There is only one value for each argument (but note the important
229 exception discussed in the following paragraph).
230
231 =back
232
233 Omitting switches is possible only because there is a prescribed order for
234 each command's arguments. When the issuer does not include switches, the
235 command interpreter relies instead on the order of arguments; it assumes
236 that the first element after the operation code is the command's first
237 argument, the next element is the command's second argument, and so
238 on. The important exception is when a command's final required argument
239 accepts multiple values. In this case, the command interpreter assumes
240 that the issuer has correctly provided one value for each argument up
241 through the final one, so any additional values at the end belong to the
242 final argument.
243
244 The following list describes the rules for omitting switches from the
245 opposite perspective: an argument's switch must be provided when any of
246 the following conditions apply.
247
248 =over 4
249
250 =item *
251
252 The command's arguments do not appear in the prescribed order.
253
254 =item *
255
256 An optional argument is omitted but a subsequent optional argument is
257 provided.
258
259 =item *
260
261 A switch is provided for a preceding argument.
262
263 =item *
264
265 More than one value is supplied for a preceding argument (which must take
266 multiple values, of course); without a switch on the current argument, the
267 command interpreter assumes that the current argument is another value for
268 the preceding argument.
269
270 =back
271
272 =head4 An Example of Omitting Switches
273
274 Consider again the example command from L<"An Example Command">.
275
276    % bos getdate -server fs1.example.com -file ptserver kaserver
277
278 This command has two required arguments: the server machine name
279 (identified by the B<-server> switch) and binary file name (identified by
280 the B<-file> switch). The second argument accepts multiple values. By
281 complying with all three conditions, the issuer can omit the switches:
282
283    % bos getdate fs1.example.com ptserver kaserver
284
285 Because there are no switches, the bos command interpreter relies on the
286 order of arguments. It assumes that the first element following the
287 operation code, C<fs1.example.com>, is the server machine name, and that the
288 next argument, C<ptserver>, is a binary file name. Then, because the
289 command's second (and last) argument accepts multiple values, the command
290 interpreter correctly interprets C<kaserver> as an additional value for
291 it.
292
293 On the other hand, the following is not acceptable because it violates the
294 first two conditions in L<"Conditions for Omitting Switches">: even though
295 there is only one value per argument, the arguments do not appear in the
296 prescribed order, and a switch is provided for one argument but not the
297 other.
298
299    % bos getdate ptserver -server fs1.example.com
300
301 =head3 Rules for Using Abbreviations and Aliases
302
303 This section explains how to abbreviate operation codes, option names,
304 server machine names, partition names, and cell names. It is not possible
305 to abbreviate other types of values.
306
307 =head4 Abbreviating Operation Codes
308
309 It is acceptable to abbreviate an operation code to the shortest form that
310 still distinguishes it from the other operation codes in its suite.
311
312 For example, it is acceptable to shorten B<bos install> to B<bos i>
313 because there are no other operation codes in the B<bos> command suite
314 that begin with the letter C<i>. In contrast, there are several B<bos>
315 operation codes that start with the letter C<s>, so the abbreviations must
316 be longer to remain unambiguous:
317
318 =over 4
319
320 =item B<bos sa> for bos salvage
321
322 =item B<bos seta> for bos setauth
323
324 =item B<bos setc> for bos setcellname
325
326 =item B<bos setr> for bos setrestart
327
328 =item B<bos sh> for bos shutdown
329
330 =item B<bos start> for bos start
331
332 =item B<bos startu> for bos startup
333
334 =item B<bos stat> for bos status
335
336 =item B<bos sto> for bos stop
337
338 =back
339
340 In addition to abbreviations, some operation codes have an I<alias>, a
341 short form that is not derived by abbreviating the operation code to its
342 shortest unambiguous form. For example, the alias for the B<fs setacl>
343 command is B<fs sa>, whereas the shortest unambiguous abbreviation is B<fs
344 seta>.
345
346 There are two usual reasons an operation code has an alias:
347
348 =over 4
349
350 =item *
351
352 Because the command is frequently issued, it is convenient to have a form
353 shorter than the one derived by abbreviating. The B<fs setacl> command is
354 an example.
355
356 =item *
357
358 Because the command's name has changed, but users of previous versions of
359 AFS know the former name. For example, B<bos listhosts> has the alias
360 B<bos getcell>, its former name.  It is acceptable to abbreviate aliases
361 to their shortest unambiguous form (for example, B<bos getcell> to B<bos
362 getc>).
363
364 =back
365
366 Even if an operation code has an alias, it is still acceptable to use the
367 shortest unambiguous form. Thus, the B<fs setacl> command has three
368 acceptable forms: B<fs setacl> (the full form), B<fs seta> (the shortest
369 abbreviation), and B<fs sa> (the alias).
370
371 =head4 Abbreviating Switches and Flags
372
373 It is acceptable to shorten a switch or flag to the shortest form that
374 distinguishes it from the other switches and flags for its operation
375 code. It is often possible to omit switches entirely, subject to the
376 conditions listed in L<"Conditions for Omitting Switches">.
377
378 =head4 Abbreviating Server Machine Names
379
380 AFS server machines must have fully-qualified Internet-style host names
381 (for example, C<fs1.example.com>), but it is not always necessary to type the
382 full name on the command line. AFS commands accept unambiguous shortened
383 forms, but depend on the cell's name service (such as the Domain Name
384 Service) or a local host table to resolve a shortened name to the
385 fully-qualified equivalent when the command is issued.
386
387 Most commands also accept the dotted decimal form of the machine's IP
388 address as an identifier.
389
390 =head4 Abbreviating Partition Names
391
392 Partitions that house AFS volumes must have names of the form
393 F</vicepI<x>> or F</vicepI<xx>>, where the variable final portion is one
394 or two lowercase letters. By convention, the first server partition
395 created on a file server machine is called F</vicepa>, the second
396 F</vicepb>, and so on.  The I<OpenAFS QuickStart Guide> explains how to
397 configure and name a file server machine's partitions in preparation for
398 storing AFS volumes on them.
399
400 When issuing AFS commands, you can abbreviate a partition name using any
401 of the following forms:
402
403    /vicepa     =     vicepa      =      a      =      0
404    /vicepb     =     vicepb      =      b      =      1
405
406 After /vicepz (for which the index is 25) comes
407
408    /vicepaa    =     vicepaa     =      aa     =      26
409    /vicepab    =     vicepab     =      ab     =      27
410
411 and so on through
412
413    /vicepiu    =     vicepiu     =      iu     =      254
414
415 F</vicepiu> is the last permissible OpenAFS partition name.
416
417 =head4 Abbreviating Cell Names
418
419 A cell's full name usually matches its Internet domain name (such as
420 B<example.org> for the Example Organization or C<example.com> for Example
421 Corporation). Some AFS commands accept unambiguous shortened forms,
422 usually with respect to the local F</usr/vice/etc/CellServDB file> but
423 sometimes depending on the ability of the local name service to resolve
424 the corresponding domain name.
425
426 =head3 Displaying Online Help for AFS Commands
427
428 To display online help for AFS commands that belong to suites, use the
429 B<help> and B<apropos> operation codes.  A B<-help> flag is also available
430 on every almost every AFS command.
431
432 The online help entry for a command consists of two or three lines:
433
434 =over 4
435
436 =item *
437
438 The first line names the command and briefly describes what it does.
439
440 =item *
441
442 If the command has aliases, they appear on the next line.
443
444 =item *
445
446 The final line, which begins with the string C<Usage:>, lists the
447 command's options in the prescribed order; online help entries use the
448 same typographical symbols (brackets and so on) as this documentation.
449
450 =back
451
452 If no operation code is specified, the B<help> operation code displays the
453 first line (short description) for every operation code in the suite:
454
455    % <command_suite> help
456
457 If the issuer specifies one or more operation codes, the B<help> operation
458 code displays each command's complete online entry (short description,
459 alias if any, and syntax):
460
461    % <command_suite> help <operation_code>+
462
463 The B<-help> flag displays a command's syntax but not the short
464 description or alias:
465
466    % <command_name> -help
467
468 The apropos operation code displays the short description of any command
469 in a suite whose operation code or short description includes the
470 specified keyword:
471
472    % <command_suite> apropos "<help string>"
473
474 The following example command displays the complete online help entry for
475 the B<fs setacl> command:
476
477    % fs help setacl
478    fs setacl: set access control list
479    aliases: sa
480    Usage: fs setacl -dir <directory>+ -acl <access list entries>+
481    [-clear] [-negative] [-id] [-if] [-help]
482
483 To see only the syntax statement, use the B<-help> flag:
484
485    % fs setacl -help
486    Usage: fs setacl -dir <directory>+ -acl <access list entries>+
487    [-clear] [-negative] [-id] [-if] [-help]
488
489 In the following example, a user wants to display the quota for her home
490 volume. She knows that the relevant command belongs to the B<fs> suite,
491 but cannot remember the operation code. She uses B<quota> as the keyword:
492
493    % fs apropos quota
494    listquota: list volume quota
495    quota: show volume quota usage
496    setquota: set volume quota
497
498 The following illustrates the error message that results if no command
499 name or short description contains the keyword:
500
501    % fs apropos "list quota"
502    Sorry, no commands found
503
504 =head1 PRIVILEGE REQUIRED
505
506 Many AFS commands require one or more types of administrative
507 privilege. See the reference page for each command.
508
509 =head1 SEE ALSO
510
511 L<afsd(8)>,
512 L<afsmonitor(1)>,
513 L<backup(8)>,
514 L<bos(8)>,
515 L<bosserver(8)>,
516 L<buserver(8)>,
517 L<butc(8)>,
518 L<dlog(1)>,
519 L<dpass(1)>,
520 L<fileserver(8)>,
521 L<fms(8)>,
522 L<fs(1)>,
523 L<fstrace(8)>,
524 L<kadb_check(8)>,
525 L<kas(8)>,
526 L<kaserver(8)>,
527 L<kdb(8)>,
528 L<klog(1)>,
529 L<knfs(1)>,
530 L<kpasswd(1)>,
531 L<kpwvalid(8)>,
532 L<pagsh(1)>,
533 L<prdb_check(8)>,
534 L<pts(1)>,
535 L<ptserver(8)>,
536 L<rxdebug(1)>,
537 L<salvager(8)>,
538 L<scout(1)>,
539 L<sys(1)>,
540 L<tokens(1)>,
541 L<translate_et(1)>,
542 L<unlog(1)>,
543 L<up(1)>,
544 L<upclient(8)>,
545 L<upserver(8)>,
546 L<uss(8)>,
547 L<vldb_check(8)>,
548 L<vlserver(8)>,
549 L<volinfo(8)>,
550 L<volscan(8)>,
551 L<volserver(8)>,
552 L<vos(1)>,
553 L<xfs_size_check(8)>,
554 L<xstat_cm_test(1)>,
555 L<xstat_fs_test(1)>
556
557 =head1 COPYRIGHT
558
559 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
560
561 This documentation is covered by the IBM Public License Version 1.0.  It was
562 converted from HTML to POD by software written by Chas Williams and Russ
563 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.