volume(1M) Volume Manager Utilities volume(1M)
NAME
volume - Performs Volume Manager operations on volumes
SYNOPSIS
volume [ -U usetype ] [ -o useopt ] [ -Vq ] init what vol [ arg ... ]
volume [ -U usetype ] [ -o useopt ] [ -Vq ] rdpol policy vol [ plex ]
volume [ -U usetype ] [ -o useopt ] [ -Vq ] start vol ...
volume [ -U usetype ] [ -o useopt ] [ -Vq ] startall
volume [ -U usetype ] [ -o useopt ] [ -Vq ] stop vol ...
volume [ -U usetype ] [ -o useopt ] [ -Vq ] stopall
volume [ -U usetype ] [ -o useopt ] [ -Vq ] maint vol ...
volume [ -U usetype ] [ -o useopt ] [ -Vq ] set var=value ... [ -- ]
vol ...
DESCRIPTION
The volume utility performs Volume Manager operations on
volumes. The first operand is a keyword that determines the
specific operation to perform. The remaining operands
specify configuration records to which the operation is to
be applied.
The recognized operation keywords are
init Perform an initialization action on a volume. The
action to perform is specified by the what operand,
which is usage-type-dependent. The vol operand
determines which usage-type to use for performing the
operation.
rdpol
Set the read policy for a volume based on the policy
operand. These are the recognized values for the what
operand:
round
Use a round-robin read order among the enabled,
readable plexes associated with the volume. A
plex operand should not be specified for the round
read-policy type.
prefer
Read preferentially from the plex named by the
plex operand. If the plex is enabled, readable,
and associated with the volume, then any read
operation on the volume results in a read from
that plex, if all blocks requested in the read are
contained in the plex. The plex operand is
required for the round read-policy type.
start
Enable the volumes named by the vol operands. The
process of enabling a volume is a highly usage-type-
Page 1 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
dependent operation and may result in transfers of data
between plexes associated with the volume. See the
volume man page for a specific usage-type for
information on how volumes are started and what usage-
type-specific options apply. By convention, the
following usage-type-specific options should be
implemented for all usage-types:
bg Perform any plex revives in a background process
after the volume and one or more plexes have been
enabled. For most usage-types that support
multiple-plex volumes, a volume can be used as
soon as one plex has been enabled. Other plexes
are then attached using an online operation that
can occur while the volume is in use. This option
is used by the default Volume Manager system
initialization script.
plexfork[=count]
Perform up to the specified number of plex revive
operations simultaneously. If no count is
specified, then use a suitable small number, such
as 10. The option plexfork=3 is used by the
default Volume Manager system initialization
script.
noattach
Do not perform any plex revives. Simply enable
any plexes that can be enabled, and leave all
plexes that would otherwise be revived in a state
where volplex att can be used to revive them.
slow[=iodelay]
Reduce the system performance impact of plex
revive operations. The plex-to-plex copies
required for plex revivals can have a serious
impact on I/O throughput of other processes using
the affected disk drives. To reduce this impact,
at the expense of the plex-to-plex copy speed, the
slow option should introduce a delay of
milliseconds between each individual I/O request.
Either an explicit number of milliseconds can be
given, or the usage type uses a system default.
startall
Attempt to start all volumes that are disabled. If a
-U usetype option is specified, then attempt to start
all disabled volumes with the indicated usage type.
stop Disable the volumes named by the vol operands.
The stop operation provides an interface to the usage-
Page 2 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
type of a volume for shutting down operations on a
volume in a clean manner. The specific method for
cleanly stopping a volume, and the precise meaning of
"clean" are both highly usage-type-dependent. See the
volume man page for a specific usage-type for
information on how volumes are stopped and what usage-
type-specific options apply. By convention, the
following usage-type-specific option should be
implemented by all usage-types:
force
Stop a volume even if the volume device is in use,
or an extended Volume Manager operation is being
performed on the volume. This option is used for
stopping all volumes before the system is shut
down.
stopall
Attempt to stop all volumes that are enabled. If a -U
usetype option is specified, then attempt to stop all
disabled volumes with the indicated usage type.
maint
Set the state for each volume named by the vol operands
to DETACHED and makes the plex devices associated with
those volumes accessible to regular system utilities.
When a volume is in the DETACHED state, normal read and
write to the volume fails, although all volume ioctl
operations can still be used. Normal read and writes
can be used on the plex devices for the associated
plexes. This operation could be used, for example,
before using the fsck utility to decide which of
several associated plexes should be used for reviving
other plexes in a volume.
set Change specific volume characteristics. The changes to
be made are given by arguments immediately after the
set keyword of the form variable_name=value. The set
of volumes affected by the operation are given after
these operands; thus the characteristic change operand
list ends before an operand that does not contain an
equal sign. To allow for volume names that contain an
equal sign, an operand of -- can be used to terminate
this list, without being interpreted as a volume name.
Each usage-type represented by the list of volume
operands is called once, with the set of all volumes
with that usage type.
The set of variable_name=value arguments that are
recognized depends upon the volume usage-type.
However, an argument of the form
Page 3 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
len=number
is expected to be interpreted (if at all) as requesting
a change in the length of a volume regardless of the
volume of usage-type. The number value should be
interpreted in the standard way, as a decimal, octal or
hexadecimal length followed by an optional multiplier
suffix of s, b, k, m or g to indicate sectors (the
default), 512-byte blocks, kilobytes, megabytes, or
gigabytes. See volsscan(3X) for more information on
conventions for numbers in the Volume Manager.
OPTIONS
The following options are recognized:
-U usetype
Force the operation to be performed by the usage-type
utility for this usage-type.
-o useopt
Give usage-type-specific options to the usage-type
specific form of the utility.
-V Write a list of utilities that would be called from
volume, along with the arguments that would be passed.
The -V performs a ``mock run'' so the utilities are not
actually called, and no changes are made to the volume
configuration database.
-q Normally the volume utility first checks for the
existence of the volume daemon, vold(1M), and exits
with a diagnostic message if the volume daemon does not
appear to be running. If the -q option is specified,
then this check is not performed, and volume waits
until the volume daemon starts, if it is not already
running. The primary purpose of this option is to
allow the start operation to be performed as soon as
vold starts up. If vold is started in the background,
then an immediate start operation might otherwise fail.
USAGE-TYPE INTERFACE
The usage-type-specific volume utilities perform the actions
that were requested by the user. Usage-type utilities are
called with the same options and keyword given to the volume
switchout utility. The list of additional operands passed
to the usage-type utilities vary depending upon the
operation. In all cases described below, except for start
and stop with no vol operands, if a usage-type is specified
using the -U option letter, then the utility for that
usage-type is called directly, as long as the operands
conform to the operation synopsis.
Page 4 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
volume init
The what, vol, and arg operands are passed to the
usage-type-specific utility for the usage type of the
named volume. Interpretation of the what and arg
operands depends entirely upon the usage-type.
volume rdpol
The policy, vol, and optional plex operands are passed
to the usage-type-specific utility for the usage type
of the named volume. It is the responsibility of the
usage-type utility to check the validity of the policy
keyword and to fail if the plex operand is
inappropriate.
volume start and volume stop
The start and stop operations operate by segregating
the vol operands by volume usage-type. For each
represented usage type, the volume utility for that
usage-type is invoked, with the vol operands associated
with that usage-type. The usage-type-specific
utilities are called one at a time, although some
usage-types may create background processes that
execute asynchronously. If one or more of the usage-
type-specific utilities exists with a nonzero status,
then the switchout volume utility exits with the same
status as the last usage-type utility to exit with a
nonzero status.
volume startall and volume stopall
A list of volume names is produced that names all
volumes with the following criteria:
1. For the startall operation the volumes must be
disabled. For the stopall operation the volumes
must be enabled.
2. If a usage-type was specified with the -U option
letter, then the usage-type of the volumes must
match the specified usage-type.
The volume names are then grouped by usage-type, and
the usage-type-specific utility for each usage-type
represented is called once, with the names of all
volumes with that usage-type. The keywords start and
stop are used when calling the usage-type-specific
utility, rather than startall and stopall.
An additional option letter, -Z, is passed to the
usage-type-specific volume utility to indicate that the
set of volumes was determined from the configuration
rather than specified by the user. In this case, the
usage-type is expected to ignore nonexistent volumes or
Page 5 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
volumes that have a different usage-type. Also, with
the -Z option the usage-type should not consider it an
error for a volume to be unstartable. A message can
still be printed for an unstartable volume, but the
exit status should not be changed from zero as a
result.
volume maint
The volume names specified by the vol operands are
grouped by volume usage-type. For each represented
usage type, the volume utility for that usage-type is
invoked, with the vol operands associated with that
usage-type. The usage-type-specific utilities are
called one at a time. If one or more of the usage-
type-specific utilities exists with a nonzero status,
then the switchout volume utility exits with the same
status as the last usage-type utility to exit with a
nonzero status.
The action, object, and arg operands are all passed to
the usage-type-specific utility, in the order
specified.
SYNOPSIS FOR FSGEN AND GEN USAGE-TYPES
volume [ -U usetype ] [ -o useopt ] init what vol [ arg ... ]
volume [ -U usetype ] [ -o useopt ] rdpol policy vol [ plex ]
volume [ -U usetype ] [ -o useopt ] start vol ...
volume [ -U usetype ] [ -o useopt ] stop vol ...
volume [ -U usetype ] [ -o useopt ] maint vol ...
volume [ -U usetype ] [ -o useopt ] set var=value ... vol ...
FSGEN AND GEN DESCRIPTION
The volume utility for the fsgen and gen volume usage-types
performs operations on volumes. The first operand is a
keyword that determines the specific operation to perform.
The remaining operands specify configuration objects to
which the operation is applied.
The recognized operation keywords are
init Perform various volume initialization operations. The
possible operations are specified by the what operand.
Volume initializations can be performed only on volumes
whose plexes are all in the EMPTY utility state. In
addition, volumes that have more than one sparse plex,
but do not have a complete plex, cannot be initialized.
The plexes of a volume are in the EMPTY state after
being created by the volmake utility, or after being
set to the empty state by the volmend fix empty
operation. A complete plex is defined as a plex that
is compact and that is at least as long as the volume
to which it is associated. In the context of the fsgen
Page 6 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
and gen utilities, a sparse plex is one that is not
complete.
These are the recognized uses of the init keyword:
init clean vol [ plex ]
Set the state for the specified plex to CLEAN, and
for all other plexes in the volume to STALE. The
volume start operation then starts the volume from
the CLEAN plex. This operation can be used only
on volumes that are not enabled.
If the specified volume has only one plex, then
the plex argument is not required and defaults to
that plex. If specified, then the plex argument
must represent a plex that is associated with the
volume.
init active vol
Set the state for all plexes associated with vol
to ACTIVE and enable the volume and its plexes.
This is used to initialize a single or multiple-
plex volume where all plexes are known to have
identical contents.
init enable vol
Enable the volume and its plexes but leave the
plex utility states as EMPTY.
This operation can be used only for non-enabled
volumes. It is used to temporarily enable a
volume so that data can be loaded onto it to make
it consistent. Once the data has been loaded,
init active should be used to fully enable the
volume. init active could be used, for example,
if a complete image of the volume is to be loaded
from a tape.
init zero vol
Write zero blocks to all plexes in the volume, up
to the length of the volume. After the writes
complete, the state of each plex is set to ACTIVE
and the volume and its plexes are enabled. init
zero vol could be used, for example, before
running mkfs to put a file system on the volume.
If this operation is interrupted by a signal, then
an attempt is made to restore all affected records
to their original state, or to a state that is
roughly equivalent to their original state. If
this attempt is interrupted, such as through
another signal, then the user many need to perform
Page 7 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
some cleanup. A set of commands to perform this
cleanup are written to the standard error before
the volume utility exits.
rdpol
Set the read policy for the volume. These are the
possible uses of the rdpol keyword:
rdpol prefer vol plex
Set the read policy for the specified volume to
VPREFER and set the preferred plex to plex. A
preferred plex is commonly used to indicate that
reads from the preferred plex are significantly
faster. For example, part of a volume image could
be kept in a RAM disk, as well as on a hard disk.
The hard disk provides permanent storage and the
RAM disk provides very fast read access. Setting
the volume read policy to prefer the RAM disk
prevents attempts to read from the hard disk for
blocks that could be read from the RAM disk.
rpol round vol
Set the read policy for the specified volume to
VROUND. This initiates a round-robin read policy
that evenly distributes read requests between all
plexes with an I/O mode that permits reads.
start
Enable a volume after a system restart or after a
volume init clean, volume stop, or volume maint
operation. An attempt is made to start each of the
volumes named in the vol operands. A failure to start
one volume does not prevent the other volumes from
being started. A volume cannot be started if it is
already enabled. Also, if the -Z option is specified,
then the volume utility ignores nonexistent volumes or
volumes with a kernel state of DETACHED.
The operations involved in starting a volume are
described in the ``Starting Volumes'' sections that
follow.
stop Stop one or more volumes, specified in the vol
operands. A failure in stopping one volume does not
prevent the volume utility from stopping the other
volumes specified in the argument list.
Stopping a volume disables the volume and its
associated plexes. In addition, the utility state for
each ACTIVE plex is changed as follows:
1. If the plex kernel state was DETACHED, then stop
Page 8 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
sets the plex utility state to STALE. If all
plexes are set to STALE, then the volume cannot be
started until volmend is used to change the plex
states. A plex normally becomes detached as a
result of an I/O error on the plex.
2. If the plex is volatile (i.e., the volatile flag is
set for one or more associated subdisks), then stop
sets the utility state to STALE.
3. If the volume kernel state was ENABLED and the plex
kernel state was also ENABLED, then the plex state
is set to CLEAN.
4. If the volume kernel state was DETACHED and the
plex kernel state was ENABLED, then the plex state
is left as ACTIVE. These states can occur either
as a result of calling volume maint to detach a
volume, or as a result of an I/O error on one of
the plexes associated with the volume. A volume is
detached by an I/O error only if one of the
associated, enabled plexes is sparse.
Normally, the stop operation fails if any extended
operations are using the volume or any of its
associated plexes. Such operations are detected as a
nonempty value for the tutil[0] field in a volume or
plex record. If the -o force option is specified, then
the stop operation ignores volume and plex tutil[0]
fields. Use of -o force is advisable when shutting
down the system from a script. Otherwise, a volume
with an outstanding operation does not shut down
cleanly.
The -o force option must also be given to force the
stopping of a volume that is open or mounted as a file
system. In this case, a warning message is still
written to the standard error, but the stop operation
is not otherwise affected.
maint
Set the kernel state for each volume specified by a vol
operand to DETACHED. This operation has no effect on
volumes that are already DETACHED. Use -o force to
change the state of an enabled volume; any associated
plexes that are disabled are enabled. No other changes
are made. Failure to change the state of one volume
does not prevent operation on the other volumes
specified in the argument list. A warning is written
to the standard error for volumes that are open or
mounted.
Page 9 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
set Change specific volume characteristics. The changes to
be made are given by arguments immediately after the
set keyword of the form variable_name=value. The set
of volumes affected by the operation are given after
these operands. The attribute change list ends with
the first argument that does not contain an equal sign.
To allow volume names to contain an equal sign, an
operand of -- also ends the list of attribute changes.
The -- argument is otherwise ignored.
The attributes that can be changed are
len=number
Change the length of each volume specified by the
vol operands to be number sectors. The number can
be specified using a C-style decimal, hexadecimal,
or octal number, and can be given a suffix of s,
b, k, m, or g to indicate sectors (the default),
512-byte blocks, kilobytes, megabytes, or
gigabytes. This suffix can be in upper or lower
case. See volsscan(3X) for more information.
Use -o force to decrease the length of a volume.
The following rules are used when increasing the
length of a volume:
1. If the volume is enabled, then count the
number of enabled, read-write plexes that
would remain compact after the length change.
The operation fails if this number would
become zero, but the number of sparse plexes
would become greater than 1. If the number of
complete plexes before the operation is 1, but
the number after the operation would be 0,
then -o force must be used to force the
operation.
2. If the volume is not enabled, then count the
number of CLEAN and ACTIVE plexes that would
remain compact after the length change. Then
use the same comparisons in rule 1 to
determine whether the operation is allowed or
requires -o force.
logtype=type
Set the type of logging to be used on the volume.
This change can be applied only to volumes that
are stopped and that have no ACTIVE plexes.
Allowed log types are BLKNO (logs the blocks
involved in all volume writes), none (never does
logging), and undef (never does logging). If the
logging type is set to undef, then a future volsd
Page 10 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
aslog or volplex att operation may change it to
BLKNO. See the fsgen and gen sections of
volsd(1M) and volplex(1M) for more information.
loglen=size
Set the size for logs used with the volume. If
the logging type is BLKNO, then this value must be
1 sector. Future logging types may allow larger
log sizes. The size value uses the same prefix
and suffix conventions described earilier in this
list for the len attribute.
startopts=volume-options
Set options that are applied to the volume every
time the volume is started, independently of
options specified with the volume start command.
This is a set of comma-separated options of the
same form used with the -o option letter. At the
present time, only the noattach and verbose
options can be applied to volumes in this manner.
Unrecognized or inappropriate options are ignored.
FSGEN AND GEN OPTIONS
The following options are recognized:
-U usetype
Regarding fsgen:
A usage-type name passed in from the switchout volsd
utility. If this option is specified, then the value
for usetype must be fsgen.
Regarding gen:
A usage-type name passed in from the switchout gen
usage-type volplex utility. The gen usage-type volplex
utility can be used by another usage-type that has
similar characteristics as long as the name of the
other usage-type is specified with this option. The
start operation can only be used for the gen usage-
type.
-o useopt
A list of options separated by commas and white space.
These options can be either a name, or a name and a
value separated by an equal sign. The recognized
usage-type options are
force
Force an operation that is considered an operation
not normally performed as part of the operational
model of the Volume Manager and may have adverse
effects on data.
Page 11 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
plexfork or plexfork=number
Execute more than one volplex utility
simultaneously for the start operation. If a
number is specified, then not allow more than this
number of volplex utilities to run simultaneously.
The default number is 10.
plexopt=opt
Pass -o opt to each invocation of the volplex
utility executed by the start operation.
bg With this option, the start operation exits
immediately after all startable volumes have been
started. STALE plexes are attached in an
asynchronous process operating in the background.
noattach
Do not revive plexes. The user must call volplex
att directly to attach all STALE plexes after the
volume has been started.
verbose
Print a message for each volume that is
successfully started. Without this option,
messages appear only for volumes that fail to
start.
iosize=size
Specify the number of sectors to copy or write in
one volume or plex I/O operation. This option is
used by the init zero operation. Also, this
option is passed to the volplex utility by the
start operation.
The default I/O size is 32 kilobytes. The I/O
size value is silently truncated to 128 kilobytes
which is the size of VOLMAXSPECIALIO in the
include file sys/vol.h. An I/O size must be an
even multiple of a disk block, which is 512 bytes
for the reference port of the Volume Manager. A
large I/O size generally increases the speed of
the operation at the expense of regular volume
I/O. Smaller I/O sizes decrease memory
requirements for the operation and have a smaller
impact on throughput of regular volume I/O.
An I/O size can be specified using a C-style
decimal, hexadecimal, or octal number, and can be
given a suffix of s, b, k, m, or g to indicate
sectors (the default), 512-byte blocks, kilobytes,
megabytes, or gigabytes. This suffix can be in
upper- or lowercase. See volsscan(3X) for more
Page 12 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
information.
slow[=iodelay]
Reduce the system performance impact of plex
revive operations. The plex-to-plex copies
required for plex revivals can have a serious
impact on I/O throughput of other processes using
the affected disk drives. To reduce this impact,
at the expense of the plex-to-plex copy speed, the
slow option introduces a delay of milliseconds
between each individual I/O request (iosize
defines the size of each I/O request). Either an
explicit number of milliseconds can be given, or a
system default is used.
norecov
Can only be used with the gen usage-type. Prevent
the start operation from recovering plexes through
the volplex utility. Instead, all STALE and
ACTIVE plexes are simply treated as equivalent to
CLEAN plexes, and are thus enabled without being
made consistent. This can be used for volumes
whose contents are recreated for each use.
An example of a possible use for this attribute is
a swap area and the /tmp file system. In the case
of /tmp, the model assumes that mkfs is used to
create an empty file system after the volume has
been started.
-Z The switchout volume utility sets the -Z option when no
volume arguments are given to the volume start or
volume stop operation. This indicates that the set of
volumes was derived from the list of all known volumes,
and that volumes which are in the DETACHED state should
not be started or stopped. Unstartable or nonexistent
volumes do not affect the exit status of the volume
start operation.
STARTING VOLUMES
Before a volume can be started, the volume utility must
select at least one associated plex to enable. The rules
used for selecting plexes differ depending upon the state of
plexes in the volume, and whether logging is enabled.
Plexes are selected from the set of CLEAN and ACTIVE plexes.
The selected plexes are enabled and are set to the ACTIVE
state. Non-selected ACTIVE plexes are moved to the STALE
state and are revived by a volplex att operation from the
selected plexes. This plex revival is not performed if the
noattach option is specified with the -o option letter.
Any volatile plex with a state of CLEAN or ACTIVE is
Page 13 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
considered equivalent to a plex with a state of STALE.
Thus, volatile plexes are not selected by volume start, and
must always be revived before use. A plex is considered
volatile if the volatile flag is set for any of its
associated subdisks.
If a plex does not contain either CLEAN or ACTIVE plexes,
then the volume cannot be started. This is the normal state
after a volume is created (all associated plexes are EMPTY).
This can also result from volmend off or volmend fix stale
operations, which leaves plexes OFFLINE or STALE. If all
plexes associated with a volume are OFFLINE or STALE, then a
combination of volmend on, volmend fix active, or volmend
fix clean operations must be used to make the volume
startable. See the fsgen and gen sections of volmend(1M)
for more information.
In addition to selecting initial plexes to be enabled, any
plexes with a utility state of TEMP are dissociated from the
volume, and any plexes with a utility state of TEMPRM are
dissociated and removed. Subdisks are dissociated from a
TEMPRM plex before the plex is removed.
Starting a volume may require two transactions with the
volume daemon. If so, a signal may leave some volumes
started and some unstarted, since volumes requiring only one
transaction are started in the first transaction. A signal
after the first transaction completes but before the second
transaction completes results in an attempt to clean up
after the start for all volumes that required two
transactions.
The following applies to gen usage-type volume start
operations only: If the norecov option is specified, with
the -o option letter, then all ACTIVE and STALE plexes,
including those that are volatile, are considered equivalent
to CLEAN plexes. Thus, with this option, a volume is
started by enabling all CLEAN, ACTIVE and STALE plexes
without doing any I/O to the volume or its plexes. If
logging is enabled for the volume, then logs will be cleared
before the volume is started.
Starting a Volume with CLEAN Plexes
If a volume has at least one plex that is in the CLEAN
state, and no plexes in the ACTIVE state, then all the CLEAN
plexes are selected for the start operation. It is an error
to have both CLEAN and ACTIVE plexes associated with a
volume. If any of these CLEAN plexes have log subdisks,
then the state in those logs is cleared before the volume is
started.
Selecting a Single Plex Marked ACTIVE
Page 14 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
If exactly one plex associated with a volume is marked
ACTIVE, then that plex is selected.
Selecting Plexes When Logs Can Be Used
If a volume has more than one associated ACTIVE plex, and at
least one complete ACTIVE plex has an associated log
subdisk, and at least two ACTIVE plexes have a log, then
logs are used for plex selection.
The log for each plex contains a magic number, a sequence
number, and a list of blocks that may have been in
transition at the time of a system failure. Under normal
operation of the virtual disk driver, a log is written to
all enabled log subdisks indicating the list of all blocks
that may not have been written yet to all plexes. A write
is not started before a log is written to all plexes which
lists the blocks in that write. Each time the log changes,
the sequence number in the log increases by 1.
The start operation uses the sequence number to detect
plexes that were detached by the kernel prior to system
failure: any plex with a log sequence more than one out-of-
date from the highest number is considered to be STALE. The
start operation also uses the set of blocks listed in the
logs to determine which blocks may not be consistent between
plexes. These blocks are copied from one up-to-date plex to
the others to ensure that all plexes have identical
contents.
All plexes with up-to-date logs are selected for enabling by
the start operation, after the blocks listed in the logs
have been made consistent.
Each log subdisk is read to ensure it has a valid magic
number, and plexes with invalid log magic numbers are
considered STALE. If up-to-date logs with the same sequence
numbers have differing contents, then the volume cannot be
started.
Selecting Plexes When Logs Cannot Be Used
If a volume has more than one associated ACTIVE plex, and
the logs cannot be used for plex selection, then one of the
ACTIVE plexes is selected. The plex to be made ACTIVE is
chosen from the set of complete ACTIVE plexes. A complete
plex is a plex that is compact (does not have any blocks
which do not map to a subdisk) and is at least as long as
the volume to which it is associated. If none of the ACTIVE
plexes is complete, then the volume is not startable.
The remainder of this section applies to the fsgen usage-
type only:
Page 15 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
The method used to choose between two or more complete,
ACTIVE plexes involves running a file system-type-dependent
utilty, called volverify, to determine which plex was
updated most recently. For the s5 and ufs file systems,
this determination is based on a timestamp from the
superblock. Because of this, there is a window of
vulnerability with the s5 and ufs file systems where a plex
can be detached because of an I/O failure, the system can go
down, and the plex that had the I/O failure can be selected
because the file system superblock was not written before
the system failure.
If the fstype field of the volume record is set, then this
field is used to determine the type of file system residing
on the volume; otherwise, the fstyp utility is run on each
of the selectable plexes to determine the file system type.
If the fstyp utility is used, it must return unambiguous
results. Errors from the fstyp utility are ignored, unless
it fails on all plexes.
The volverify utility is called with one argument, the path
to the plex device. Volverify should open this device,
verify the file system type, and print a set of numbers that
can be used to compare plexes. The output of volverify
should be the plex pathname, followed by one or more blanks,
followed by a colon-separated list of hexadecimal numbers
with 0x prefixes. These fields can be followed by
additional fields, as desired. The hexadecimal numbers
cannot exceed an unsigned long. The numbers for each plex
are compared in the order presented. One of the plexes with
the highest set will be selected for the start operation.
FILES
/usr/lib/VxVM/type/usetype/volume
Usage-type-specific utility for performing volume
operations.
/dev/rvol/vol
The device node that can be used for issuing ioctl
requests to the volume named vol.
/dev/plex/plex
The device node for accessing a plex named plex.
A plex device is accessible only if it is not
disabled and if it is associated with a volume
that is not disabled.
/usr/lib/VxVM/type/fsgen/fs/fstype/volverify plex
Path to file system-type-dependent utility (for
file system type fstype) that prints file system
modification times.
Page 16 (printed 1/21/92)
volume(1M) Volume Manager Utilities volume(1M)
EXIT CODES
The volume 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.
See volintro(1M) for a list of standard exit codes.
SEE ALSO
volintro(1M), volsscan(3X), vol(7), ioctl(2), fstyp(1M),
volplex(1M), and volmend(1M).
Page 17 (printed 1/21/92)