3 afs - Introduction to AFS commands
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>.
15 Interface for configuring and operating the AFS Backup System.
19 Interface to the Basic Overseer (BOS) Server for administering server
20 processes and configuration files.
24 Interface for administering access control lists (ACLs), the Cache
25 Manager, and other miscellaneous file system functions.
29 Interface for tracing Cache Manager operations when debugging problems.
33 Interface to the Authentication Server for administering security and
34 authentication information. This aspect of OpenAFS has been deprecated.
38 Interface to the Protection Server for administering AFS ID and group
39 membership information.
43 Interface for automated administration of user accounts.
47 Interface to the Volume Server and Volume Location (VL) Server for
48 administering volumes.
52 In addition, there are several commands that do not belong to
55 =head2 AFS Command Syntax
57 AFS commands that belong to suites have the following structure:
59 I<command_suite> I<operation_code> B<-switch> <I<value>>[+] [B<-flag>]
63 Together, the I<command_suite> and I<operation_code> make up the I<command
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.
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.
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.
85 The term I<option> refers to both arguments and flags, which are described
86 in the following sections.
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
96 Each argument has two parts, which appear in the indicated order:
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">.
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.
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">.
125 Some commands have optional as well as required arguments; the command
126 descriptions and online help show optional arguments in square brackets
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.
140 =head3 An Example Command
142 The following example illustrates the different parts of a command that
143 belongs to an AFS command suite.
145 % bos getdate -server fs1.abc.com -file ptserver kaserver
153 B<bos> is the command suite. The BOS Server executes most of the commands
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.
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.
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>.
177 =head3 Rules for Entering AFS Commands
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.
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
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:
198 Using accepted abbreviations for operation codes, switches (if they are
199 included at all), and some types of values.
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.
207 =head4 Conditions for Omitting Switches
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.
217 All of the command's required arguments appear in the order prescribed by
218 the syntax statement.
222 No switch is provided for any argument.
226 There is only one value for each argument (but note the important
227 exception discussed in the following paragraph).
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
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.
250 The command's arguments do not appear in the prescribed order.
254 An optional argument is omitted but a subsequent optional argument is
259 A switch is provided for a preceding argument.
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.
270 =head4 An Example of Omitting Switches
272 Consider again the example command from L<"An Example Command">.
274 % bos getdate -server fs1.abc.com -file ptserver kaserver
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:
281 % bos getdate fs1.abc.com ptserver kaserver
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
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
297 % bos getdate ptserver -server fs1.abc.com
299 =head3 Rules for Using Abbreviations and Aliases
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.
305 =head4 Abbreviating Operation Codes
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.
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:
318 =item B<bos sa> for bos salvage
320 =item B<bos seta> for bos setauth
322 =item B<bos setc> for bos setcellname
324 =item B<bos setr> for bos setrestart
326 =item B<bos sh> for bos shutdown
328 =item B<bos start> for bos start
330 =item B<bos startu> for bos startup
332 =item B<bos stat> for bos status
334 =item B<bos sto> for bos stop
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
344 There are two usual reasons an operation code has an alias:
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
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
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).
369 =head4 Abbreviating Switches and Flags
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">.
376 =head4 Abbreviating Server Machine Names
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.
385 Most commands also accept the dotted decimal form of the machine's IP
386 address as an identifier.
388 =head4 Abbreviating Partition Names
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<OpenAFS QuickStart Guide> explains how to
395 configure and name a file server machine's partitions in preparation for
396 storing AFS volumes on them.
398 When issuing AFS commands, you can abbreviate a partition name using any
399 of the following forms:
401 /vicepa = vicepa = a = 0
402 /vicepb = vicepb = b = 1
404 After /vicepz (for which the index is 25) comes
406 /vicepaa = vicepaa = aa = 26
407 /vicepab = vicepab = ab = 27
411 /vicepiv = vicepiv = iv = 255
413 F</vicepiv> is the last permissible AFS partition name. In practice it
414 will not work well; stopping with F</vicepiu> is highly recommended.
416 =head4 Abbreviating Cell Names
418 A cell's full name usually matches its Internet domain name (such as
419 B<stateu.edu> for the State University or C<abc.com> for ABC
420 Corporation). Some AFS commands accept unambiguous shortened forms,
421 usually with respect to the local F</usr/vice/etc/CellServDB file> but
422 sometimes depending on the ability of the local name service to resolve
423 the corresponding domain name.
425 =head3 Displaying Online Help for AFS Commands
427 To display online help for AFS commands that belong to suites, use the
428 B<help> and B<apropos> operation codes. A B<-help> flag is also available
429 on every almost every AFS command.
431 The online help entry for a command consists of two or three lines:
437 The first line names the command and briefly describes what it does.
441 If the command has aliases, they appear on the next line.
445 The final line, which begins with the string C<Usage:>, lists the
446 command's options in the prescribed order; online help entries use the
447 same typographical symbols (brackets and so on) as this documentation.
451 If no operation code is specified, the B<help> operation code displays the
452 first line (short description) for every operation code in the suite:
454 % <command_suite> help
456 If the issuer specifies one or more operation codes, the B<help> operation
457 code displays each command's complete online entry (short description,
458 alias if any, and syntax):
460 % <command_suite> help <operation_code>+
462 The B<-help> flag displays a command's syntax but not the short
463 description or alias:
465 % <command_name> -help
467 The apropos operation code displays the short description of any command
468 in a suite whose operation code or short description includes the
471 % <command_suite> apropos "<help string>"
473 The following example command displays the complete online help entry for
474 the B<fs setacl> command:
477 fs setacl: set access control list
479 Usage: fs setacl -dir <directory>+ -acl <access list entries>+
480 [-clear] [-negative] [-id] [-if] [-help]
482 To see only the syntax statement, use the B<-help> flag:
485 Usage: fs setacl -dir <directory>+ -acl <access list entries>+
486 [-clear] [-negative] [-id] [-if] [-help]
488 In the following example, a user wants to display the quota for her home
489 volume. She knows that the relevant command belongs to the B<fs> suite,
490 but cannot remember the operation code. She uses B<quota> as the keyword:
493 listquota: list volume quota
494 quota: show volume quota usage
495 setquota: set volume quota
497 The following illustrates the error message that results if no command
498 name or short description contains the keyword:
500 % fs apropos "list quota"
501 Sorry, no commands found
503 =head1 PRIVILEGE REQUIRED
505 Many AFS commands require one or more types of administrative
506 privilege. See the reference page for each command.
552 L<xfs_size_check(8)>,
558 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
560 This documentation is covered by the IBM Public License Version 1.0. It was
561 converted from HTML to POD by software written by Chas Williams and Russ
562 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.