NAME

vos - Introduction to the vos command suite

DESCRIPTION

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 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 and vos syncloc commands.

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

CAUTIONS

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.

OPTIONS

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.

-auth

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 or vos source, 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.

-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 /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:

Do not combine the -cell and -localauth options. A command on which the -localauth flag is included always runs in the workstation cell.

-config <configuration file>

Sets the location of the configuration file to be used. The default file is /etc/yfs/yfs-client.conf.

-encrypt [<yes|no>]

Enables or disables encrytion for the command so that the operation's results are not transmitted across the network in clear text. For vos move, vos copy, vos release 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.

-help

Prints the online help for this command. All other valid options are ignored.

-localauth

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.

-noauth

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:

Do not combine the -auth, -localauth and -noauth switches.

-noresolve

Shows all servers as IP addresses instead of the reverse DNS lookup hostname. -noresolve useful when troubleshooting no such volume and volume moved errors.

-partition <partition name>

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, vos move and vos shadow commands also accept this notation.

-server <hostname, IP address or UUID>

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.

The -fromserver and -toserver arguments to the vos copy, vos move and vos shadow commands also accept this notation.

-verbose

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.

PRIVILEGE REQUIRED

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.

SEE ALSO

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_zap(1), UserListExt(5), yfs-client.conf(5), yfs-server.conf(5)

COPYRIGHT

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.

ACKNOWLEDGEMENTS

"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.