vos - Introduction to the vos command suite
The commands in the vos command suite are the administrative interface to the Volume Server and Location Service. Cell administrators use vos commands to create, move, delete, replicate, back up and examine volumes, among other operations. The Location Service automatically records 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 due to network outage or server failure, then a subsequent attempt at the same operation continues from the interruption point, rather than starting over at the beginning of the operation. The vos command checks with the Volume Server and Location Service to verify the current state of the volumes and their location information.
If the volumes and associated location information 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 Ctrl-C or another interrupt signal. In that case, the volume is left locked and the cell administrator must use the vos_unlock(1) command to unlock it before proceeding.
It is important that the Location Service accurately indicate the status of the volumes on File Servers at all times. If a vos command changes volume status, it notifies the Location Service. The most common cause of discrepancies between the state of a volume as reported by the Location Service and the volume status known to the File Servers is interrupted operations. To restore consistency, use the vos_syncfs(1) and vos_syncloc(1) commands.
There are several categories of commands in the vos command suite:
Commands to create, move, rename and split volumes: vos_backup(1), vos_backupsys(1), vos_changeloc(1), vos_create(1), vos_move(1), vos_rename(1), and vos_splitvolume(1).
Commands to remove a volume from the Location Service or the Volume Server or both: vos_delentry(1), vos_remove(1), and vos_zap(1).
Commands to edit or display file server data managed by the Location Service: vos_listfs(1), and vos_removefs(1).
Commands to create, size, and restore dump files: vos_dump(1), vos_restore(1), and vos_size(1).
Commands to administer replicated volumes: vos_addsite(1), vos_copysite(1), vos_movesite(1), vos_release(1), vos_remove(1), and vos_remsite(1).
Commands to display volume state information as known to the Location Service, Volume Server, or both: vos_examine(1), vos_listloc(1), and vos_listvol(1).
Commands to display information about partitions that house volumes: vos_listpart(1) and vos_partinfo(1).
Command to query the Location Service for the list of registered file servers and generate formatted output: vos_eachfs(1).
Command to query the cell for the list of configured Location Service servers and generate formatted output: vos_eachvl(1).
Command to query the Location Service for a list of matching volumes and generate formatted output: vos_eachvol(1).
Commands to restore consistency between the Location Service and Volume Servers: vos_syncfs(1) and vos_syncloc(1).
Commands to lock and unlock volumes in the Location Service: vos_lock(1), vos_unlock(1), and vos_unlockall(1).
A command to report Volume Server status: vos_status(1).
A command to end Volume Server transactions: vos_endtrans(1).
Commands to change volume settings: vos_setaddrs(1), vos_setfields(1), vos_setmaxacl(1), vos_listmaxacl(1), vos_setrootacl(1), vos_listrootacl(1), vos_setquota(1).
Commands to view and set volume security levels: vos_listseclevels(1), vos_setseclevels(1).
Commands to run commands interactively: vos_interactive(1), vos_sleep(1), and vos_quit(1).
A command to run commands from a file: vos_source(1).
Commands to obtain help: vos_apropos(1) and vos_help(1).
Command to display the program version: vos_version(1).
Currently, the maximum partition size and volume quota is 16 zettabytes (2^74 bytes). Note that tools such as fs_listquota(1) can only report sizes up to 2 terabytes (2^41 bytes) when accessing a volume housed on an IBM AFS or OpenAFS File Server.
The following arguments and switches are common to many commands in the vos suite. The reference page for each command also lists them, but they are described here in greater detail.
Use the calling user's tokens from the kernel or as obtained using the active Kerberos ticket granting ticket to communicate with the Volume Server and Location Service. This is the default if neither -localauth nor -noauth is given.
Since this option is the default, it is usually not useful for running single command line operations. However, it can be useful when running commands via vos_interactive(1) or vos_source(1), since otherwise it would be impossible to switch from, for example, -localauth back to using regular tokens during a bulk operation.
Do not combine the -auth, -localauth and -noauth switches.
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 /etc/yfs/yfs-client.conf file.
If the -cell argument is omitted, the command interpreter determines the name of the local cell by reading the following in order:
The value of the AFSCELL environment variable.
The local cell as specified by the HKLM\SYSTEM\CurrentControlSet\Services\YourFileSystemClient\Parameters "Cell" registry value. (Microsoft Windows only)
Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the workstation cell.
Sets the location of the configuration file to be used. The default file is /etc/yfs/yfs-client.conf.
Enables or disables encrytion for the command so that the operation's results are not transmitted across the network in clear text. For Lvos_move(1)>, vos_copy(1), vos_release(1) and other commands that exchange volume data between File Servers, the -encrypt option controls whether or not that data is sent encrypted when the sender is a AuriStorFS File Server.
Prints the online help for this command. All other valid options are ignored.
Obtains an authentication token using the server encryption key with the highest key version number in the local /etc/yfs/server/KeyFileExt file. The resulting token never expires and has Super User privileges.
Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the workstation cell.
Use this flag only when issuing a command on a server machine; client machines do not usually have either a /etc/yfs/server/KeyFileExt file or a /etc/yfs/server/yfs-server.conf file.
The issuer of a command that includes this flag must be logged on to the server machine as the local superuser root or another account that has permission to read the /etc/yfs/server/KeyFileExt file.
The flag is useful for commands invoked by an unattended application program,
such as a process controlled by the UNIX cron utility.
It is also useful if an administrator is unable to authenticate to the cell but is logged in as the local superuser root.
Do not combine the -auth, -localauth and -noauth switches.
Establishes an unauthenticated connection to the Volume Server and Location Service,
in which the servers treat the issuer as the unprivileged user anonymous.
It is useful only when:
authorization checking is disabled (during installation or when the bos_setauth(8) command has been used). During normal operation, the servers permit only privileged users to issue commands that change the status of a volume, and refuses to perform such an action even if the -noauth flag is provided.
issuing commands such as vos_examine(1) that do not require privileges to complete. Specifying the -noauth flag can avoid warning messages.
Do not combine the -auth, -localauth and -noauth switches.
Shows all servers as IP addresses instead of the reverse DNS lookup hostname.
-noresolve useful when troubleshooting no such volume and volume moved errors.
Identifies the partition on a File Server 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
/vicepiu = vicepiu = iu = 254
The -frompartition and -topartition arguments to the vos_copy(1), vos_move(1) and vos_shadow(1) commands also accept this notation.
Identifies the File Server that houses, or is to house, the volumes or partitions of interest. Provide the machine's IP address in dotted decimal format, its fully qualified host name (for example, fs1.your-cell-name.com), or the File Server's universally unique identifier (UUID) as reported by vos_listfs(1).
The -fromserver and -toserver arguments to the vos_copy(1), vos_move(1) and vos_shadow(1) commands also accept this notation.
Produces on the standard output stream a detailed trace of the command's execution. If this argument is omitted, only warnings and error messages are reported.
To issue most vos commands, the issuer must be listed in the /etc/yfs/server/UserListExt file on each File Server that houses or is to house the volumes of interest, and on each Location Service instance. The most predictable performance results if all Location Servers and File Servers in the cell share a common /etc/yfs/server/UserListExt file.
To issue a vos command that only displays information, no privilege is required.
KeyFileExt(5), vos_addsite(1), vos_apropos(1), vos_backup(1), vos_backupsys(1), vos_changeloc(1), vos_convertROtoRW(1), vos_copy(1), vos_copysite(1), vos_create(1), vos_delentry(1), vos_dump(1), vos_eachfs(1), vos_eachvl(1), vos_eachvol(1), vos_endtrans(1), vos_examine(1), vos_help(1), vos_interactive(1), vos_listfs(1), vos_listloc(1) vos_listmaxacl(1), vos_listpart(1), vos_listrootacl(1), vos_listseclevels(1), vos_listvol(1), vos_lock(1), vos_move(1), vos_movesite(1), vos_offline(1), vos_online(1), vos_partinfo(1), vos_quit(1), vos_release(1), vos_remove(1), vos_removefs(1), vos_remsite(1), vos_rename(1), vos_restore(1), vos_setfields(1), vos_setmaxacl(1), vos_setquota(1), vos_setrootacl(1), vos_setseclevels(1), vos_size(1), vos_sleep(1), vos_source(1), vos_splitvolume(1), vos_status(1), vos_syncfs(1), vos_syncloc(1), vos_unlock(1), vos_unlockall(1), vos_version(1), vos_zap(1), UserListExt(5), yfs-client.conf(5), yfs-server.conf(5)
IBM Corporation 2000. http://www.ibm.com/ 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.
"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)
"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)
The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).
"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).
"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.