Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AFS(1)			     AFS Command Reference			AFS(1)

       afs - Introduction to AFS commands

       AFS provides many commands that enable users and	system administrators
       to use and customize its	features. Many of the commands belong to the
       following categories, called command suites.

	   Interface for configuring and operating the AFS Backup System.

       bos Interface to	the Basic Overseer (BOS) Server	for administering
	   server processes and	configuration files.

       fs  Interface for administering access control lists (ACLs), the	Cache
	   Manager, and	other miscellaneous file system	functions.

	   Interface for tracing Cache Manager operations when debugging

       kas Interface to	the Authentication Server for administering security
	   and authentication information. This	aspect of OpenAFS has been

       pts Interface to	the Protection Server for administering	AFS ID and
	   group membership information.

       uss Interface for automated administration of user accounts.
	   Deprecated, may be removed from a future version of OpenAFS.	See
	   uss man page	for more detail.

       vos Interface to	the Volume Server and Volume Location (VL) Server for
	   administering volumes.

       In addition, there are several commands that do not belong to suites.

   AFS Command Syntax
       AFS commands that belong	to suites have the following structure:

       command_suite operation_code -switch <value>[+] [-flag]

       Command Names

       Together, the command_suite and operation_code make up the command

       The command_suite specifies the group of	related	commands to which the
       command belongs,	and indicates which command interpreter	and server
       process perform the command.  AFS has several command suites, including
       bos, fs,	kas, package, pts, uss (deprecated) and	vos.  Some of these
       suites have an interactive mode in which	the issuer omits the
       operation_code portion of the command name.

       The operation_code tells	the command interpreter	and server process
       which action to perform.	Most command suites include several operation
       codes. The man pages for	each command name describe each	operation code
       in detail, and the OpenAFS Administration Guide describes how to	use
       them in the context of performing administrative	tasks.

       Several AFS commands do not belong to a suite and so their names	do not
       have a command_suite portion. Their structure is	otherwise similar to
       the commands in the suites.


       The term	option refers to both arguments	and flags, which are described
       in the following	sections.


       One or more arguments can follow	the command name. Arguments specify
       the entities on which to	act while performing the command (for example,
       which server machine, server process, or	file). To minimize the
       potential for error, provide a command's	arguments in the order
       prescribed in its syntax	definition.

       Each argument has two parts, which appear in the	indicated order:

       o   The switch specifies	the argument's type and	is preceded by a
	   hyphen (-). For instance, the switch	-server	usually	indicates that
	   the argument	names a	server machine.	Switches can often be omitted,
	   subject to the rules	outlined in "Conditions	for Omitting

       o   The value names a particular	entity of the type specified by	the
	   preceding switch. For example, the proper value for a -server
	   switch is a server machine name like	"". Unlike switches
	   (which have a required form), values	vary depending on what the
	   issuer wants	to accomplish. Values appear surrounded	by angle
	   brackets ("<>") in command descriptions and the online help to show
	   that	they are user-supplied variable	information.

       Some arguments accept multiple values, as indicated by trailing plus
       sign ("+") in the command descriptions and online help. How many	of a
       command's arguments take	multiple values, and their ordering with
       respect to other	arguments, determine when it is	acceptable to omit
       switches. See "Conditions for Omitting Switches".

       Some commands have optional as well as required arguments; the command
       descriptions and	online help show optional arguments in square brackets


       Some commands have one or more flags, which specify the manner in which
       the command interpreter and server process perform the command, or what
       kind of output it produces. Flags are preceded by hyphens like
       switches, but they take no values. Although the command descriptions
       and online help generally list a	command's flags	after its arguments,
       there is	no prescribed order for	flags. They can	appear anywhere	on the
       command line following the operation code, except in between the	parts
       of an argument. Flags are always	optional.

       An Example Command

       The following example illustrates the different parts of	a command that
       belongs to an AFS command suite.

	  % bos	getdate	-server -file ptserver kaserver


       o   bos is the command suite. The BOS Server executes most of the
	   commands in this suite.

       o   getdate is the operation code. It tells the BOS Server on the
	   specified server machine (in	this case "") to report the
	   modification	dates of binary	files in the local
	   /usr/local/libexec/openafs directory.

       o   "-server" is one	argument, with -server as the switch
	   and "" as	the value. This	argument specifies the server
	   machine on which BOS	Server is to collect and report	binary dates.

       o   "-file ptserver kaserver" is	an argument that takes multiple
	   values. The switch is -file and the values are "ptserver" and
	   "kaserver". This argument tells the BOS Server to report the
	   modification	dates on the files /usr/local/libexec/openafs/kaserver
	   and /usr/local/libexec/openafs/ptserver.

       Rules for Entering AFS Commands

       Enter each AFS command on a single line (press <Return> only at the end
       of the command).	Some commands in this document appear broken across
       multiple	lines, but that	is for legibility only.

       Use a space to separate each element on a command line from its
       neighbors. Spaces rather	than commas also separate multiple values of
       an argument.

       In many cases, the issuer of a command can reduce the amount of typing
       necessary by using one or both of the following methods:

       o   Omitting switches.

       o   Using accepted abbreviations	for operation codes, switches (if they
	   are included	at all), and some types	of values.

       The following sections explain the conditions for omitting or
       shortening parts	of the command line. It	is always acceptable to	type a
       command in full,	with all of its	switches and no	abbreviations.

       Conditions for Omitting Switches

       It is always acceptable to type the switch part of an argument, but in
       many cases it is	not necessary. Specifically, switches can be omitted
       if the following	conditions are met.

       o   All of the command's	required arguments appear in the order
	   prescribed by the syntax statement.

       o   No switch is	provided for any argument.

       o   There is only one value for each argument (but note the important
	   exception discussed in the following	paragraph).

       Omitting	switches is possible only because there	is a prescribed	order
       for each	command's arguments. When the issuer does not include
       switches, the command interpreter relies	instead	on the order of
       arguments; it assumes that the first element after the operation	code
       is the command's	first argument,	the next element is the	command's
       second argument,	and so on. The important exception is when a command's
       final required argument accepts multiple	values.	In this	case, the
       command interpreter assumes that	the issuer has correctly provided one
       value for each argument up through the final one, so any	additional
       values at the end belong	to the final argument.

       The following list describes the	rules for omitting switches from the
       opposite	perspective: an	argument's switch must be provided when	any of
       the following conditions	apply.

       o   The command's arguments do not appear in the	prescribed order.

       o   An optional argument	is omitted but a subsequent optional argument
	   is provided.

       o   A switch is provided	for a preceding	argument.

       o   More	than one value is supplied for a preceding argument (which
	   must	take multiple values, of course); without a switch on the
	   current argument, the command interpreter assumes that the current
	   argument is another value for the preceding argument.

       An Example of Omitting Switches

       Consider	again the example command from "An Example Command".

	  % bos	getdate	-server -file ptserver kaserver

       This command has	two required arguments:	the server machine name
       (identified by the -server switch) and binary file name (identified by
       the -file switch). The second argument accepts multiple values. By
       complying with all three	conditions, the	issuer can omit	the switches:

	  % bos	getdate ptserver kaserver

       Because there are no switches, the bos command interpreter relies on
       the order of arguments. It assumes that the first element following the
       operation code, "", is the server machine name, and that the
       next argument, "ptserver", is a binary file name. Then, because the
       command's second	(and last) argument accepts multiple values, the
       command interpreter correctly interprets	"kaserver" as an additional
       value for it.

       On the other hand, the following	is not acceptable because it violates
       the first two conditions	in "Conditions for Omitting Switches": even
       though there is only one	value per argument, the	arguments do not
       appear in the prescribed	order, and a switch is provided	for one
       argument	but not	the other.

	  % bos	getdate	ptserver -server

       Rules for Using Abbreviations and Aliases

       This section explains how to abbreviate operation codes,	option names,
       server machine names, partition names, and cell names. It is not
       possible	to abbreviate other types of values.

       Abbreviating Operation Codes

       It is acceptable	to abbreviate an operation code	to the shortest	form
       that still distinguishes	it from	the other operation codes in its

       For example, it is acceptable to	shorten	bos install to bos i because
       there are no other operation codes in the bos command suite that	begin
       with the	letter "i". In contrast, there are several bos operation codes
       that start with the letter "s", so the abbreviations must be longer to
       remain unambiguous:

       bos sa for bos salvage
       bos seta	for bos	setauth
       bos setc	for bos	setcellname
       bos setr	for bos	setrestart
       bos sh for bos shutdown
       bos start for bos start
       bos startu for bos startup
       bos stat	for bos	status
       bos sto for bos stop

       In addition to abbreviations, some operation codes have an alias, a
       short form that is not derived by abbreviating the operation code to
       its shortest unambiguous	form. For example, the alias for the fs	setacl
       command is fs sa, whereas the shortest unambiguous abbreviation is fs

       There are two usual reasons an operation	code has an alias:

       o   Because the command is frequently issued, it	is convenient to have
	   a form shorter than the one derived by abbreviating.	The fs setacl
	   command is an example.

       o   Because the command's name has changed, but users of	previous
	   versions of AFS know	the former name. For example, bos listhosts
	   has the alias bos getcell, its former name.	It is acceptable to
	   abbreviate aliases to their shortest	unambiguous form (for example,
	   bos getcell to bos getc).

       Even if an operation code has an	alias, it is still acceptable to use
       the shortest unambiguous	form. Thus, the	fs setacl command has three
       acceptable forms: fs setacl (the	full form), fs seta (the shortest
       abbreviation), and fs sa	(the alias).

       Abbreviating Switches and Flags

       It is acceptable	to shorten a switch or flag to the shortest form that
       distinguishes it	from the other switches	and flags for its operation
       code. It	is often possible to omit switches entirely, subject to	the
       conditions listed in "Conditions	for Omitting Switches".

       Abbreviating Server Machine Names

       AFS server machines must	have fully-qualified Internet-style host names
       (for example, ""), but it is not always necessary to type
       the full	name on	the command line. AFS commands accept unambiguous
       shortened forms,	but depend on the cell's name service (such as the
       Domain Name Service) or a local host table to resolve a shortened name
       to the fully-qualified equivalent when the command is issued.

       Most commands also accept the dotted decimal form of the	machine's IP
       address as an identifier.

       Abbreviating Partition Names

       Partitions that house AFS volumes must have names of the	form /vicepx
       or /vicepxx, where the variable final portion is	one or two lowercase
       letters.	By convention, the first server	partition created on a file
       server machine is called	/vicepa, the second /vicepb, and so on.	 The
       OpenAFS QuickStart Guide	explains how to	configure and name a file
       server machine's	partitions in preparation for storing AFS volumes on

       When issuing AFS	commands, you can abbreviate a partition name using
       any of the following forms:

	  /vicepa     =	    vicepa	=      a      =	     0
	  /vicepb     =	    vicepb	=      b      =	     1

       After /vicepz (for which	the index is 25) comes

	  /vicepaa    =	    vicepaa	=      aa     =	     26
	  /vicepab    =	    vicepab	=      ab     =	     27

       and so on through

	  /vicepiv    =	    vicepiv	=      iv     =	     255

       /vicepiv	is the last permissible	AFS partition name. In practice	it
       will not	work well; stopping with /vicepiu is highly recommended.

       Abbreviating Cell Names

       A cell's	full name usually matches its Internet domain name (such as for the State	University or ""	for ABC	Corporation).
       Some AFS	commands accept	unambiguous shortened forms, usually with
       respect to the local /usr/local/etc/openafs/CellServDB file but
       sometimes depending on the ability of the local name service to resolve
       the corresponding domain	name.

       Displaying Online Help for AFS Commands

       To display online help for AFS commands that belong to suites, use the
       help and	apropos	operation codes.  A -help flag is also available on
       every almost every AFS command.

       The online help entry for a command consists of two or three lines:

       o   The first line names	the command and	briefly	describes what it

       o   If the command has aliases, they appear on the next line.

       o   The final line, which begins	with the string	"Usage:", lists	the
	   command's options in	the prescribed order; online help entries use
	   the same typographical symbols (brackets and	so on) as this

       If no operation code is specified, the help operation code displays the
       first line (short description) for every	operation code in the suite:

	  % <command_suite> help

       If the issuer specifies one or more operation codes, the	help operation
       code displays each command's complete online entry (short description,
       alias if	any, and syntax):

	  % <command_suite> help <operation_code>+

       The -help flag displays a command's syntax but not the short
       description or alias:

	  % <command_name> -help

       The apropos operation code displays the short description of any
       command in a suite whose	operation code or short	description includes
       the specified keyword:

	  % <command_suite> apropos "<help string>"

       The following example command displays the complete online help entry
       for the fs setacl command:

	  % fs help setacl
	  fs setacl: set access	control	list
	  aliases: sa
	  Usage: fs setacl -dir	<directory>+ -acl <access list entries>+
	  [-clear] [-negative] [-id] [-if] [-help]

       To see only the syntax statement, use the -help flag:

	  % fs setacl -help
	  Usage: fs setacl -dir	<directory>+ -acl <access list entries>+
	  [-clear] [-negative] [-id] [-if] [-help]

       In the following	example, a user	wants to display the quota for her
       home volume. She	knows that the relevant	command	belongs	to the fs
       suite, but cannot remember the operation	code. She uses quota as	the

	  % fs apropos quota
	  listquota: list volume quota
	  quota: show volume quota usage
	  setquota: set	volume quota

       The following illustrates the error message that	results	if no command
       name or short description contains the keyword:

	  % fs apropos "list quota"
	  Sorry, no commands found

       Many AFS	commands require one or	more types of administrative
       privilege. See the reference page for each command.

       afsd(8),	afsmonitor(1), backup(8), bos(8), bosserver(8),	buserver(8),
       butc(8),	dlog(1), dpass(1), fileserver(8), fms(8), fs(1), fstrace(8),
       kadb_check(8), kas(8), kaserver(8), kdb(8), klog(1), knfs(1),
       kpasswd(1), kpwvalid(8),	package(1), pagsh(1), prdb_check(8), pts(1),
       ptserver(8), rxdebug(1),	salvager(8), scout(1), sys(1), tokens(1),
       translate_et(1),	unlog(1), up(1), upclient(8), upserver(8), uss(8),
       vldb_check(8), vlserver(8), volinfo(8), volscan(8), volserver(8),
       vos(1), xfs_size_check(8), xstat_cm_test(1), xstat_fs_test(1)

       IBM Corporation 2000. <> All Rights Reserved.

       This documentation is covered by	the IBM	Public License Version 1.0.
       It was converted	from HTML to POD by software written by	Chas Williams
       and Russ	Allbery, based on work by Alf Wachsmann	and Elizabeth Cassell.

OpenAFS				  2016-12-14				AFS(1)


Want to link to this manual page? Use this URL:

home | help