voladm(1M) Volume Manager Utilities voladm(1M)
NAME
voladm - Operates on volume daemon and configuration
databases
SYNOPSIS
voladm init voldesc-name [ database-spec ... ]
voladm add database-spec
voladm rm database-spec
voladm cp [ kernel | source-spec ] database-spec
voladm [ -nl ] [ voldesc | kernel ]
voladm enable
voladm disable
voladm sync
voladm check
voladm halt
DESCRIPTION
The voladm utility is the interface to the Volume Manager
configuration daemon (vold) for performing administrative
tasks related to the state of vold and to the set of on-disk
configuration databases that vold uses for permanent,
redundant storage of the Volume Manager configuration.
The voladm utility is used to manipulate the contents of a
voldesc file, which contains a list of all on-disk
configuration copies. This file can be initialized or
reinitialized; configuration copies can be added or removed;
and the set of configuration copies can be listed in various
ways. Other operations can be performed on the
configurations that do not affect the voldesc file. These
are: copying configurations for backup purposes and
synchronizing the configuration copies.
Several of the voladm operations use database-spec operands.
These operands name regions of raw disk or regular files
that can be used to store a copy of the configuration. A
database-spec has the following form:
path,offset,size
Here, path is the path to a file or raw device, offset
specifies the sector offset to the beginning of the region
to be used, and size specifies the size of the region in
sectors. If the path does not begin with a slash character
(/), then the current directory is prepended.
The offset and length must be a multiple of the system
sector size (commonly 512 bytes). A suffix of b specifies a
size or offset in 512-byte blocks; a suffix of k specifies a
size or offset in 1024-byte blocks; a suffix of m specifies
1024K blocks; and a suffix of s specifies the default 1
sector blocks. These suffixes can be either upper- or
Page 1 (printed 1/21/92)
voladm(1M) Volume Manager Utilities voladm(1M)
lowercase letters. The numbers that define the offset and
length are normally specified in decimal. However, the
number can be specified in hexadecimal using a prefix of 0x
and can be specified in octal using a prefix of 0. To
resolve ambiguity, a space must separate a hexadecimal
number from a b suffix. Use of a space requires quoting
from the shell.
In some cases, which are indicated, the size part of the
specification is optional. You can omit the size part when
referring to a configuration that is in the voldesc file.
In such cases, the size is not needed to determine which
entry is being referenced in the voldesc.
The first operand is a keyword that determines the specific
operation to perform. Interpretation of the remaining
operands depends on that operation keyword.
The following operation keywords are recognized:
init voldesc-name [ database-spec ... ]
Initialize the voldesc file. The voldesc-name operand
defines a name that will be stored in the copies of the
on-disk configurations. This name is used as a sanity
check when reading configurations from disk.
Configurations that have a different stored name will
not be used. As a general rule, name should be a
unique machine identifier, such as the output of uname
-n.
If database-spec operands are given, then they specify
existing configurations that will not be modified,
except that their stored voldesc name field will be
changed to voldesc-name. A future attempt to enable
vold or to synchronize the configuration copies will
try to reconcile these copies.
As an alternate usage, if an operand of - is used in
place of any database-spec operands, then lines are
read from the standard input until end-of-file. These
lines are interpreted as database-spec strings. This
is a convenient method for taking the output of a
previous list operation and reinitializing the voldesc
from that saved list.
There is a limit of eight configuration copies, and the
absolute pathname for each copy must fit within 31
bytes.
The init operation can be performed only when vold is
disabled for transactions. On a system without a
voldesc, the vold utility automatically starts in
Page 2 (printed 1/21/92)
voladm(1M) Volume Manager Utilities voladm(1M)
disabled mode.
add database-spec
Add a new copy of the configuration, or rewrite an
existing copy. When a new configuration copy is
specified, the size part of the database-spec is
required; otherwise, it is optional but, if given, the
database size must match the original configuration.
New configuration copies are not allowed to overlap
existing copies. In addition, the new configuration
must be large enough to store the existing record with
the highest block number.
Naming an existing configuration copy causes that copy
to be rewritten, if it has been disabled due to an
error. If the configuration copy is not disabled, then
the operation fails.
If vold is disabled for transactions, then the
configuration is written from a selected configuration.
If the kernel is loaded with a configuration, then that
configuration is used; otherwise, the most recent
configuration copy with no errors is used. The set of
configuration copies must be consistent or the
operation will fail.
rm database-spec
Remove a copy of the configuration from active use.
The size part of the database-spec is optional but, if
given, the size must match the original configuration.
A copy cannot be removed if it is free of errors and
there are not more than two copies that are free of
errors.
cp [ kernel | source-spec ] dest-spec
Copy a configuration to a file, identified by the
dest-spec configuration specification. If the first
operand after the cp keyword is kernel, then the
configuration residing in the kernel is used;
otherwise, if two operands follow the cp keyword, then
the first is used as a source database specification,
and the second is used as the destination database
specification.
If only a single dest-spec operand is given after the
cp keyword, then the active configuration is copied.
If vold is enabled for transactions, then this is
equivalent to copying the kernel configuration;
otherwise, this differs because it is the configuration
formed from the on-disk and kernel configuration, if
Page 3 (printed 1/21/92)
voladm(1M) Volume Manager Utilities voladm(1M)
any, which must be consistent for the operation to
succeed.
If transactions are disabled and the kernel
configuration is used, then the mapping between
configuration records and blocks will not necessarily
be consistent with other on-disk databases. In this
case, the new copy is prevented from being considered
consistent with the existing configuration copies.
A source-spec operand can identify a configuration copy
kept by vold or it can identify an unrelated
configuration. The dest-spec is not allowed to name or
to overlap with a configuration copy kept by vold.
[ -nl ] list [ voldesc | kernel ]
List all copies of the configuration kept by vold.
Each database is listed on a separate line with the
pathname, and the offset and size (in blocks) separated
by commas. The -n and -l options can be used to list
state, ID, and error information. The difference
between these two options is apparent only when vold is
disabled for transactions. In this state, the -n
option only detects open errors and errors in the
database header blocks. The -l option, causes vold to
check the configuration copies for consistency among
themselves and with any database residing in the
kernel. This option allows additional errors to be
reported.
If an additional keyword follows the list keyword, then
voladm lists the contents of a voldesc. If this
keyword is kernel, then voladm uses the voldesc stored
in the kernel; otherwise, voladm uses the permanent
voldesc. The kernel voldesc does not exist if vold has
not yet been enabled since the machine was last
rebooted. The following information is listed from the
voldesc: a header line specifying the format version;
the default database I/O size; the voldesc name; the
count of databases referenced in the voldesc; and
database-spec listings of the configurations referenced
in the voldesc, one per line.
enable
Tell vold to enable transactions. This process
synchronizes the on-disk configurations and the kernel,
and then enables connections from utilities to the
regular request rendezvous point. If the configuration
is not consistent, then the operation fails and the
offending databases are written to the standard error.
If the configuration is consistent, but some
configuration copies contain failures, then the copies
Page 4 (printed 1/21/92)
voladm(1M) Volume Manager Utilities voladm(1M)
with failures are listed to the standard error.
Transactions cannot be enabled if there are not at
least two error-free on-disk configuration copies. See
vold(1M) for more information.
disable
Tell vold to disable transactions. This process aborts
any pending client utility transactions and closes all
non-diagnostic connections with vold. Until vold is
re-enabled, only diagnostic operations are allowed, and
only the diagnostic rendezvous point is accessible.
sync The configuration is evaluated for consistency. If
possible, all inconsistencies are resolved and the
configuration copies are synchronized. If there is a
problem that prevents full synchronization, then the
error is reported. If the process succeeds, but some
configuration copies still have failures, those
failures are listed on the standard error.
check
Determine whether transactions are enabled or disabled.
If enabled, prints
vold is ENABLED for transactions
If disabled, prints
vold is DISABLED for transactions
This operation also exits with status 0 if transactions
are enabled, or 2 if transactions are disabled.
halt Stop vold. This operation is used during system
shutdown, to cause vold to exit. It can also be used
to make the /dev/volconfig device accessible to other
utilities.
OPTIONS
The following options are recognized:
-n List more information about each copy of the
configuration. This format lists the state,
configuration ID, and epoch of each configuration, and
any errors that can be determined without reading the
configuration. This option is only valid with the list
keyword.
-l List all information about each copy of the
configuration, as with the -n option, but also reads
the configurations (if transactions are disabled), so
Page 5 (printed 1/21/92)
voladm(1M) Volume Manager Utilities voladm(1M)
consistency errors can be detected. This option is
only valid with the list keyword.
EXIT CODES
The voladm utility exits with a nonzero status if the
attempted operation fails. A nonzero exit code is not a
complete indicator of the problems encountered, but rather
denotes the first condition that prevented further execution
of the utility.
These are the possible exit codes:
0 Success, or, in the case of the check operation, vold
is enabled for transactions.
1 A usage error, or a malformed database-spec.
2 In the case of the check operation, vold is disabled
for transactions.
3 vold reported a failure.
4 vold is not running.
5 An operation failed because vold is in the wrong state
(enabled or disabled).
6 A system error prevented operation of voladm.
FILES
/usr/lib/VxVM/voldesc
The file containing the permanent voldesc
information.
/usr/lib/VxVM/volddiag
The rendezvous point used by voladm to connect to
vold. This is an attached STREAMS file that can
be used only when connecting to vold for
diagnostic operations.
SEE ALSO
vold(1M), volintro(1M).
Page 6 (printed 1/21/92)