mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
923721f839
Reviewed-on: http://gerrit.openafs.org/615 Tested-by: Jeffrey Altman <jaltman@openafs.org> Reviewed-by: Jeffrey Altman <jaltman@openafs.org>
315 lines
10 KiB
Plaintext
315 lines
10 KiB
Plaintext
=head1 NAME
|
|
|
|
vos - Introduction to the vos command suite
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The commands in the B<vos> command suite are the administrative interface
|
|
to the Volume Server and Volume Location (VL) Server. System
|
|
administrators use B<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 B<vos> commands.
|
|
|
|
The operations invoked by most B<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 L<B<vos unlock>|vos_unlock(1)> 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. L<vldb.DB0(5)> and
|
|
L<afs_volume_header(5)> describe the information recorded in the VLDB and
|
|
volume headers, respectively. If a B<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 L<B<vos syncserv>|vos_syncserv(1)> and
|
|
L<B<vos syncvldb>|vos_syncvldb(1)> commands.
|
|
|
|
There are several categories of commands in the vos command suite:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
Commands to create, move, and rename volumes:
|
|
L<B<vos backup>|vos_backup(1)>,
|
|
L<B<vos backupsys>|vos_backupsys(1)>,
|
|
L<B<vos changeloc>|vos_changeloc(1)>,
|
|
L<B<vos create>|vos_create(1)>,
|
|
L<B<vos move>|vos_move(1)>,
|
|
and L<B<vos rename>|vos_rename(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to remove VLDB volume records or volumes or both:
|
|
L<B<vos delentry>|vos_delentry(1)>,
|
|
L<B<vos remove>|vos_remove(1)>,
|
|
and L<B<vos zap>|vos_zap(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to edit or display VLDB server entries:
|
|
L<B<vos changeaddr>|vos_changeaddr(1)>
|
|
and L<B<vos listaddrs>|vos_listaddrs(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to create, size, and restore dump files:
|
|
L<B<vos dump>|vos_dump(1)>,
|
|
L<B<vos restore>|vos_restore(1)>,
|
|
and L<B<vos size>|vos_size(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to administer replicated volumes:
|
|
L<B<vos addsite>|vos_addsite(1)>,
|
|
L<B<vos release>|vos_release(1)>,
|
|
and L<B<vos remsite>|vos_remsite(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to display VLDB records, volume headers, or both:
|
|
L<B<vos examine>|vos_examine(1)>,
|
|
L<B<vos listvldb>|vos_listvldb(1)>,
|
|
and L<B<vos listvol>|vos_listvol(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to display information about partitions that house volumes:
|
|
L<B<vos listpart>|vos_listpart(1)>
|
|
and L<B<vos partinfo>|vos_partinfo(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to restore consistency between the VLDB and volume headers:
|
|
L<B<vos syncserv>|vos_syncserv(1)>
|
|
and L<B<vos syncvldb>|vos_syncvldb(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to lock and unlock VLDB entries:
|
|
L<B<vos lock>|vos_lock(1)>,
|
|
L<B<vos unlock>|vos_unlock(1)>,
|
|
and L<B<vos unlockvldb>|vos_unlockvldb(1)>.
|
|
|
|
=item *
|
|
|
|
A command to report Volume Server status:
|
|
L<B<vos status>|vos_status(1)>.
|
|
|
|
=item *
|
|
|
|
A command to change volume fields:
|
|
L<B<vos setfields>|vos_setfields(1)>.
|
|
|
|
=item *
|
|
|
|
Commands to obtain help:
|
|
L<B<vos apropos>|vos_apropos(1)>
|
|
and L<B<vos help>|vos_help(1)>.
|
|
|
|
=back
|
|
|
|
=head1 CAUTIONS
|
|
|
|
Currently, the maximum size of a volume is 2 terabytes (2^31 bytes).
|
|
|
|
=head1 OPTIONS
|
|
|
|
The following arguments and flags are available on many commands in the
|
|
B<bos> suite. The reference page for each command also lists them, but
|
|
they are described here in greater detail.
|
|
|
|
=over 4
|
|
|
|
=item B<-cell> <I<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 F</usr/vice/etc/CellServDB> file on the local machine. If
|
|
the B<-cell> argument is omitted, the command interpreter determines the
|
|
name of the local cell by reading the following in order:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
The value of the AFSCELL environment variable.
|
|
|
|
=item *
|
|
|
|
The local F</usr/vice/etc/ThisCell> file.
|
|
|
|
=back
|
|
|
|
Do not combine the B<-cell> and B<-localauth> options. A command on which
|
|
the B<-localauth> flag is included always runs in the local cell (as
|
|
defined in the server machine's local F</usr/afs/etc/ThisCell> file),
|
|
whereas a command on which the B<-cell> argument is included runs in the
|
|
specified foreign cell.
|
|
|
|
=item B<-help>
|
|
|
|
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.
|
|
|
|
=item B<-localauth>
|
|
|
|
Constructs a server ticket using the server encryption key with the
|
|
highest key version number in the local F</usr/afs/etc/KeyFile> file. The
|
|
B<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 F</usr/afs/etc/KeyFile> file. The issuer
|
|
of a command that includes this flag must be logged on to the server
|
|
machine as the local superuser C<root>. The flag is useful for commands
|
|
invoked by an unattended application program, such as a process controlled
|
|
by the UNIX B<cron> utility or by a cron entry in the machine's
|
|
F</usr/afs/local/BosConfig> file. It is also useful if an administrator is
|
|
unable to authenticate to AFS but is logged in as the local superuser
|
|
B<root>.
|
|
|
|
Do not combine the B<-cell> and B<-localauth> options. A command on which
|
|
the B<-localauth> flag is included always runs in the local cell (as
|
|
defined in the server machine's local F</usr/afs/etc/ThisCell> file),
|
|
whereas a command on which the B<-cell> argument is included runs in the
|
|
specified foreign cell. Also, do not combine the B<-localauth> and
|
|
B<-noauth> flags.
|
|
|
|
=item B<-noauth>
|
|
|
|
Establishes an unauthenticated connection to the Volume Server and VL
|
|
Server, in which the servers treat the issuer as the unprivileged user
|
|
C<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 L<B<bos setauth>|bos_setauth(8)> 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
|
|
B<-noauth> flag is provided. Do not combine the B<-noauth> and
|
|
B<-localauth> flags.
|
|
|
|
=item B<-partition> <I<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 B<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 B<-frompartition> and B<-topartition> arguments to the
|
|
L<B<vos move>|vos_move(1)> command also accept this notation.
|
|
|
|
=item B<-server> <I<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, C<fs1.abc.com>), 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 B<-fromserver> and B<-toserver> arguments to the
|
|
L<B<vos move>|vos_move(1)> command also accept these name formats.
|
|
|
|
=item B<-noresolve>
|
|
|
|
Shows all servers as IP addresses instead of the DNS name. This is very
|
|
useful when the server address is registered as 127.0.0.1 or when dealing
|
|
with multi-homed servers. The B<-noresolve> option is available in OpenAFS
|
|
versions 1.4.8 or later and 1.5.35 or later.
|
|
|
|
=item B<-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
|
|
appear.
|
|
|
|
=back
|
|
|
|
=head1 PRIVILEGE REQUIRED
|
|
|
|
To issue most vos commands, the issuer must be listed in the
|
|
F</usr/afs/etc/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 F<UserList> file. Alternatively, if
|
|
the B<-localauth> flag is included, the issuer must be logged on to a
|
|
server machine as the local superuser C<root>.
|
|
|
|
To issue a vos command that only displays information, no privilege is
|
|
required.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<vos_addsite(1)>,
|
|
L<vos_apropos(1)>,
|
|
L<vos_backup(1)>,
|
|
L<vos_backupsys(1)>,
|
|
L<vos_changeaddr(1)>,
|
|
L<vos_convertROtoRW(1)>,
|
|
L<vos_clone(1)>,
|
|
L<vos_copy(1)>,
|
|
L<vos_create(1)>,
|
|
L<vos_delentry(1)>,
|
|
L<vos_dump(1)>,
|
|
L<vos_examine(1)>,
|
|
L<vos_help(1)>,
|
|
L<vos_listaddrs(1)>,
|
|
L<vos_listpart(1)>,
|
|
L<vos_listvldb(1)>,
|
|
L<vos_listvol(1)>,
|
|
L<vos_lock(1)>,
|
|
L<vos_move(1)>,
|
|
L<vos_partinfo(1)>,
|
|
L<vos_release(1)>,
|
|
L<vos_remove(1)>,
|
|
L<vos_remsite(1)>,
|
|
L<vos_rename(1)>,
|
|
L<vos_restore(1)>,
|
|
L<vos_setfields(1)>,
|
|
L<vos_shadow(1)>,
|
|
L<vos_size(1)>,
|
|
L<vos_status(1)>,
|
|
L<vos_syncserv(1)>,
|
|
L<vos_syncvldb(1)>,
|
|
L<vos_unlock(1)>,
|
|
L<vos_unlockvldb(1)>,
|
|
L<vos_zap(1)>,
|
|
L<CellServDB(5)>,
|
|
L<UserList(5)>
|
|
|
|
=head1 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.
|