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 =over 4
 508
 509 L<afsd(8)>,
 510 L<afsmonitor(1)>,
 511 L<backup(8)>,
 512 L<bos(8)>,
 513 L<bosserver(8)>,
 514 L<buserver(8)>,
 515 L<butc(8)>,
 516 L<dlog(1)>,
 517 L<dpass(1)>,
 518 L<fileserver(8)>,
 519 L<fms(8)>,
 520 L<fs(1)>,
 521 L<fstrace(8)>,
 522 L<kadb_check(8)>,
 523 L<kas(8)>,
 524 L<kaserver(8)>,
 525 L<kdb(8)>,
 526 L<klog(1)>,
 527 L<knfs(1)>,
 528 L<kpasswd(1)>,
 529 L<kpwvalid(8)>,
 530 L<package(1)>,
 531 L<pagsh(1)>,
 532 L<prdb_check(8)>,
 533 L<pts(1)>,
 534 L<ptserver(8)>,
 535 L<rxdebug(1)>,
 536 L<salvager(8)>,
 537 L<scout(1)>,
 538 L<sys(1)>,
 539 L<tokens(1)>,
 540 L<translate_et(1)>,
 541 L<unlog(1)>,
 542 L<up(1)>,
 543 L<upclient(8)>,
 544 L<upserver(8)>,
 545 L<uss(8)>,
 546 L<vldb_check(8)>,
 547 L<vlserver(8)>,
 548 L<volinfo(8)>,
 549 L<volserver(8)>,
 550 L<vos(1)>,
 551 L<xfs_size_check(8)>,
 552 L<xstat_cm_test(8)>,
 553 L<xstat_fs_test(8)>
 554
 555 =back
 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.