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