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

FreeBSD Manual Pages


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

       vos - Introduction to the vos command suite

       The commands in the vos command suite are the administrative interface
       to the Volume Server and	Volume Location	(VL) Server. System
       administrators use vos commands to create, move,	delete,	replicate,
       back up and examine volumes, among other	operations. The	VL Server
       automatically records in	the Volume Location Database (VLDB) changes in
       volume status and location that result from vos commands.

       The operations invoked by most vos commands are idempotent, meaning
       that if an operation is interrupted by a	network, server	machine, or
       process outage, then a subsequent attempt at the	same operation
       continues from the interruption point, rather than starting over	at the
       beginning of the	operation. Before executing a command, the Volume and
       VL Servers check	the current state of the volumes and VLDB records to
       be altered by the command. If they are already in the desired end state
       (or a consistent	intermediate state), there is no need to repeat	the
       internal	steps that brought them	there. Idempotency does	not apply if
       the command issuer explicitly interrupts	the operation with the Ctrl-C
       command or another interrupt signal. In that case, the volume is	left
       locked and the administrator must use the vos unlock command to unlock
       it before proceeding.

       It is important that the	VLDB accurately	indicate the status of the
       volumes on file server machines at all times. vldb.DB0(5) and
       afs_volume_header(5) describe the information recorded in the VLDB and
       volume headers, respectively. If	a vos command changes volume status,
       it automatically	records	the change in the corresponding	VLDB entry.
       The most	common cause of	discrepancies between the VLDB and volume
       status on file server machines is interrupted operations; to restore
       consistency, use	the vos	syncserv and vos syncvldb commands.

       There are several categories of commands	in the vos command suite:

       o   Commands to create, move, and rename	volumes: vos backup, vos
	   backupsys, vos changeloc, vos create, vos move, and vos rename.

       o   Commands to remove VLDB volume records or volumes or	both: vos
	   delentry, vos remove, and vos zap.

       o   Commands to edit or display VLDB server entries: vos	changeaddr,
	   vos listaddrs vos setaddrs, and vos remaddrs.

       o   Commands to create, size, and restore dump files: vos dump, vos
	   restore, and	vos size.

       o   Commands to administer replicated volumes: vos addsite, vos
	   release, and	vos remsite.

       o   Commands to display VLDB records, volume headers, or	both: vos
	   examine, vos	listvldb, and vos listvol.

       o   Commands to display information about partitions that house
	   volumes: vos	listpart and vos partinfo.

       o   Commands to restore consistency between the VLDB and	volume
	   headers: vos	syncserv and vos syncvldb.

       o   Commands to lock and	unlock VLDB entries: vos lock, vos unlock, and
	   vos unlockvldb.

       o   A command to	report Volume Server status: vos status.

       o   A command to	end Volume Server transactions:	vos endtrans.

       o   A command to	change volume fields: vos setfields.

       o   Commands to obtain help: vos	apropos	and vos	help.

       Currently, the maximum quota for	a volume is 2 terabytes	(2^41 bytes).
       Note that this only affects the volume's	quota; a volume	may grow much
       larger if the volume quota is disabled. However,	volumes	over 2
       terabytes in size may be	impractical to move, and may have their	size
       incorrectly reported by some tools, such	as fs_listquota(1).

       The following arguments and flags are available on many commands	in the
       bos suite. The reference	page for each command also lists them, but
       they are	described here in greater detail.

       -cell <cell name>
	   Names the cell in which to run the command. It is acceptable	to
	   abbreviate the cell name to the shortest form that distinguishes it
	   from	the other entries in the /usr/local/etc/openafs/CellServDB
	   file	on the local machine. If the -cell argument is omitted,	the
	   command interpreter determines the name of the local	cell by
	   reading the following in order:

	   o   The value of the	AFSCELL	environment variable.

	   o   The local /usr/local/etc/openafs/ThisCell file.

	   Do not combine the -cell and	-localauth options. A command on which
	   the -localauth flag is included always runs in the local cell (as
	   defined in the server machine's local
	   /usr/local/etc/openafs/server/ThisCell file), whereas a command on
	   which the -cell argument is included	runs in	the specified foreign

	   Prints a command's online help message on the standard output
	   stream. Do not combine this flag with any of	the command's other
	   options; when it is provided, the command interpreter ignores all
	   other options, and only prints the help message.

	   Constructs a	server ticket using the	server encryption key with the
	   highest key version number in the local
	   /usr/local/etc/openafs/server/KeyFile file. The vos command
	   interpreter presents	the ticket, which never	expires, to the	Volume
	   Server and VL Server	during mutual authentication.

	   Use this flag only when issuing a command on	a server machine;
	   client machines do not usually have a
	   /usr/local/etc/openafs/server/KeyFile file.	The issuer of a
	   command that	includes this flag must	be logged on to	the server
	   machine as the local	superuser "root". The flag is useful for
	   commands invoked by an unattended application program, such as a
	   process controlled by the UNIX cron utility or by a cron entry in
	   the machine's /usr/local/etc/openafs/BosConfig file.	It is also
	   useful if an	administrator is unable	to authenticate	to AFS but is
	   logged in as	the local superuser root.

	   Do not combine the -cell and	-localauth options. A command on which
	   the -localauth flag is included always runs in the local cell (as
	   defined in the server machine's local
	   /usr/local/etc/openafs/server/ThisCell file), whereas a command on
	   which the -cell argument is included	runs in	the specified foreign
	   cell. Also, do not combine the -localauth and -noauth flags.

	   Establishes an unauthenticated connection to	the Volume Server and
	   VL Server, in which the servers treat the issuer as the
	   unprivileged	user "anonymous". It is	useful only when authorization
	   checking is disabled	on the server machine (during the installation
	   of a	file server machine or when the	bos setauth command has	been
	   used	during other unusual circumstances). In	normal circumstances,
	   the servers allow only privileged users to issue commands that
	   change the status of	a volume or VLDB record, and refuses to
	   perform such	an action even if the -noauth flag is provided.	Do not
	   combine the -noauth and -localauth flags.

       -partition <partition name>
	   Identifies the AFS server partition on a file server	machine	that
	   houses, or is to house, the volumes of interest, or about which to
	   list	information. The vos command interpreter accepts any of	the
	   following four name formats:

	      /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

	   The -frompartition and -topartition arguments to the	vos move
	   command also	accept this notation.

       -server <machine	name>
	   Identifies the file server machine that houses, or is to house, the
	   volumes or AFS server partitions of interest. Provide the machine's
	   IP address in dotted	decimal	format,	its fully qualified host name
	   (for	example, ""), or the	shortest abbreviated form of
	   its host name that distinguishes it from other machines. Successful
	   use of an abbreviated form depends on the availability of a name
	   resolution service (such as the Domain Name Service or a local host
	   table) at the time the command is issued.

	   The -fromserver and -toserver arguments to the vos move command
	   also	accept these name formats.

	   Shows all servers as	IP addresses instead of	the DNS	name. This is
	   very	useful when the	server address is registered as or
	   when	dealing	with multi-homed servers. The -noresolve option	is
	   available in	OpenAFS	versions 1.4.8 or later	and 1.5.35 or later.

	   Produces on the standard output stream a detailed trace of the
	   command's execution.	If this	argument is omitted, only warnings and
	   error messages appear.

       To issue	most vos commands, the issuer must be listed in	the
       /usr/local/etc/openafs/server/UserList file on each server machine that
       houses or is to house an	affected volume, and on	each database server
       machine.	The most predictable performance results if all	database
       server and file server machines in the cell share a common UserList
       file.  Alternatively, if	the -localauth flag is included, the issuer
       must be logged on to a server machine as	the local superuser "root".

       To issue	a vos command that only	displays information, no privilege is

       vos_addsite(1), vos_apropos(1), vos_backup(1), vos_backupsys(1),
       vos_changeaddr(1), vos_convertROtoRW(1),	vos_clone(1), vos_copy(1),
       vos_create(1), vos_delentry(1), vos_dump(1), vos_endtrans(1),
       vos_examine(1), vos_help(1), vos_listaddrs(1), vos_listpart(1),
       vos_listvldb(1),	vos_listvol(1),	vos_lock(1), vos_move(1),
       vos_partinfo(1),	vos_release(1),	vos_remove(1), vos_remsite(1),
       vos_rename(1), vos_restore(1), vos_setfields(1),	vos_shadow(1),
       vos_size(1), vos_status(1), vos_syncserv(1), vos_syncvldb(1),
       vos_unlock(1), vos_unlockvldb(1), vos_zap(1), CellServDB(5),

       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-15				VOS(1)


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

home | help