vxsd(ADM)

vxsd - perform Volume Manager operations on subdisks

Synopsis

vxsd [ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] [ -l offset ] assoc plex subdisk ...
vxsd [ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] [ -l column[/offset] ] assoc
plex subdisk[:column[/offset]] ...

vxsd[ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] aslog plex subdisk
vxsd [ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] [ -p plex ] dis subdisk ...
vxsd [ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] [ -p plex ] -s size split subdisk newsd
[ newsd2 ]
vxsd [ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] [ -p plex ] join sd1 sd2 ... newsd
vxsd [ -Vf ] [ -g diskgroup ] [ -U usetype ] [ -o useopt ] [ -v volume ] [ -p plex ] mv oldsd newsd [ newsd ... ]

Description

The vxsd utility performs Volume Manager operations on subdisks and on plex-and-subdisk combinations. The first operand is a keyword that determines the specific operation to perform. The remaining operands specify the configuration objects to which the operation is to be applied.

Each operation can be applied to only one disk group at a time, due to internal implementation constraints. Any plex or subdisk name operands will be used to determine a default disk group, according to the standard disk group selection rules described in vxintro(ADM). A specific disk group can be selected with -g diskgroup.

If a vxsd operation is interrupted by a signal, then an attempt is made to restore the disk group configuration to a state that is roughly equivalent to its original state. If this attempt is interrupted, such as through another signal, then the user may need to perform some cleanup. The specific cleanup actions that are needed are written to the standard error before vxsd exits.

These are the recognized operation keywords:

assoc: Associate each named subdisk operand with the specified plex. The first form applies to concatenated plexes (i.e., with a layout of concat). The offset within the plex for the association can be specified with -l, which takes a standard Volume Manager length number (see vxintro(ADM)). If no offset is specified, then the default is to associate the subdisk at the end of the plex, thus extending the length of the plex by the length of the new subdisk.; For striped plexes, a column number for the subdisk association may be specified. The offset is interpreted as the column offset for the subdisk. If only one number is specified with -l for striped plexes, the number is interpreted as a column number and the subdisk is associated at the end of the column.; The column or column/offset at which a subdisk is to be associated can also be specified as part of the subdisk name in the same manner as subdisks associations are specified for plex creations in vxmake (see vxmake(F)). When specifying multiple subdisks, if no column or column/offset is specified for a subdisk, it is associated after the previous subdisk.; A subdisk cannot be associated to overlap with an another associated subdisk in the same plex.; If the named plex is associated with a volume, then the rules for performing the operation depend upon the usage type of the volume. A subdisk cannot be associated to a plex if the putil0 field for the subdisk is not empty. Creating a subdisk with the putil0 field set to a non- empty value is a sufficient means of ensuring that no Volume Manager operation will write to the region of disk blocks allocated to the subdisk because the subdisk cannot be associated through any means to a plex, and because subdisks cannot be used directly to read from or write to a disk.
aslog: Associate the named subdisk with the named plex as a log area for the plex. At most, one log subdisk can be associated with a plex at any given time. Currently, log subdisks can be used only with the dirty region logging feature, as defined by the DRL volume logging type. If the named plex is associated with a volume, then the rules for performing the operation depend upon the usage type of the volume. A subdisk cannot be associated if the putil0 field is set on the subdisk, just as with vxsd assoc.
dis: Dissociate each specified subdisk from the plex that it is associated with. If a subdisk is associated (through its plex) with a volume, then the rules for performing the operation depend upon the usage type of the volume.; Subdisk dissociation can be used as part of tearing down a plex, or as part of reorganization of disk space usage. Typically, the subdisk is no longer needed after dissociation. To support this type of use, -o rm can be specified to remove the named subdisks after successful dissociation.
split: Split the subdisk subdisk into two subdisks that reside on the same section of the same device, and that have contiguous plex associations (if the named subdisk is associated). The first of the two resultant subdisks will have a length of size, and the second will take up the remainder of the space used by the original subdisk. If both newsd and newsd2 are specified, then the resultant subdisks are newsd and newsd2. If no newsd2 operand was specified, then the resultant subdisks are named subdisk and newsd.; If the named subdisk is associated with an associated plex, then the rules for performing the operation depend upon the usage type of the volume. Log subdisks cannot be split.
join: Join the subdisks named by the sd operands to form a new subdisk named newsd. The sd operands must specify subdisks that represent contiguous sections of the same device, and of the same plex (if they are associated). For a striped plex, the sd operands must be in the same column. At least two sd operands are required. At the end of the operation, the sd configuration objects are removed. The newsd operand can have the same name as one of the sd operands, or it can have a different name.; If the sd operands are associated with an associated plex, then the rules for performing the operation depend upon the usage type of the volume.
mv: Move the contents of oldsd onto the new subdisks and replace oldsd with the new subdisks for any associations. If multiple new subdisks are specified, they are associated starting where the old subdisk began and placed consecutively with no space between them. The operation requires that oldsd be associated with an associated plex and that all new subdisks be dissociated. The operation can be used on a subdisk that is used by an active volume, and will ensure that data is copied and associations are changed without loss or corruption of data. The rules for performing the operation depend upon the usage type of the volume.; Moving a subdisk is the normal means of reorganizing disk space. For example, move regions of disk used by one volume to another disk to reduce contention on the original disk. Typically, once the operation completes, the original subdisk is no longer needed and can be removed. To support this use of the operation, -o rm can be specified to remove oldsd after successful completion of the operation.

Options

-g diskgroup

Specify the disk group for the operation, either by disk group ID or by disk group name. By default, the disk group is chosen based on the name operands.

-U usetype

Limit the operation to apply to this usage type. Attempts to affect volumes with a different usage type will fail.

-o useopt

Pass in usage-type-specific options to the operation. A certain set of operations are expected to be implemented by all usage types:

slow[=iodelay]: Reduce the system performance impact of copy operations. Copy operations are usually a set of short copy operations on small regions of the volume (normally from 16 kilobytes to 128 kilobytes). This option inserts a delay between the recovery of each such region. A specific delay can be specified with iodelay as a number of milliseconds, or a default is chosen (normally 250 milliseconds).
iosize=size: Perform copy operations in regions with the length specified by size, which is a standard Volume Manager length number (see vxintro(ADM)). Specifying a larger number typically causes the operation to complete sooner, but with greater impact on other processes using the volume. The default I/O size is typically 32 kilobytes.
rm: Remove the subdisks after successful completion of a vxsd dis operation. Remove the source subdisk after successful completion of vxsd mv.

-V

Write a list of utilities that would be called from vxsd, along with the arguments that would be passed. The -V performs a ``mock run'' so the utilities are not actually called.

-s size

Specify the size for the subdisk split operation. This option takes a standard Volume Manager length number (see vxintro(ADM)).

-l [column/]offset

Specify the offset of a subdisk within a plex address space for the vxsd assoc operation. For striped plexes a column number may be optionally specified. If one number is given for striped plexes the number is interpreted as a column number and the subdisk is associated at the end of the column. The offset is a standard Volume Manager length number (see vxintro(ADM)).

-v volume

Require that a named plex be associated with this volume, or that a named subdisk (source subdisk for vxsd split, join, and mv) be associated with a plex that is associated with this volume.

-p plex

Require that a named subdisk (source subdisk for vxsd split, join, and mv) be associated with this plex.

-f

Force an operation that the Volume Manager considers potentially dangerous or of questionable use. This permits a limited set of operations that would otherwise be disallowed. Some operations may be disallowed even with this flag.

Fsgen and gen usage types

The fsgen and gen usage types provide identical semantics for all operations of the vxsd utility.

In addition to the standard -o options required for all usage types, the fsgen and gen usage types provide the following additional option:

force: Force an operation that the Volume Manager considers potentially dangerous or of questionable use. This applies to attempts to dissociate subdisks (making a plex sparse) and to attempts to move subdisks onto subdisks that have a different size. This flag is the same as -f.

Limitations and extensions for the fsgen and gen usage types consist of the following:

assoc: If the named plex is enabled, and is associated with an enabled plex, then the named plex must be ACTIVE or EMPTY. Subdisks can be associated with a non-enabled plex only if the utility state of the plex is EMPTY, STALE, or OFFLINE, or if the plex is CLEAN and no other plexes associated with the volume are CLEAN or ACTIVE.; If the subdisk is associated with a non-enabled plex, or if it is associated with the only enabled, read- write plex in a volume, then the operation completes without copying any data onto the subdisk. If the subdisk is associated with an enabled plex in a mirrored volume, then the operation may have to copy data from the volume onto the new subdisk before the operation can complete.
aslog: If a log subdisk is associated with a plex that is associated with a volume that has a logging type of UNDEF, then the logging type of the volume is converted to DRL. Logging of volume changes is not enabled until there are at least two read-write mode plexes attached to the volume.
dis: Dissociating a subdisk requires use of -f if it would cause an enabled plex in an enabled volume to become sparse relative to the volume. Even with -f, it is not possible to make two plexes sparse if no complete, enabled, read-write plexes would remain associated. For disabled volumes, a similar check is made with respect to ACTIVE and CLEAN plexes.
split and join: The fsgen and gen usage types apply no additional restrictions and add no extensions to the split and join operations.
mv: If the total size of the destination subdisks differs from that of the source subdisk, then the -f option must be specified. The operation still fails if the total size of the destination subdisks is larger than the source subdisk and if the address range of any destination subdisk would conflict with another subdisk that is associated with the plex. The total size of the destination subdisks cannot be larger than the source subdisk if the kernel state of the volume or plex is detached.; The operation fails if the total size of the destination subdisks is smaller than the source subdisk and the operation would cause the total number of complete, enabled, read-mode plexes in the volume to drop to zero, while leaving more than one sparse, enabled, read-write plex.

RAID-5 usage type

In addition to the standard -o options required for all usage types, the raid5 usage type provides the following additional options:

force: Force an operation that the Volume Manager considers potentially dangerous or of questionable use. This applies to attempts to move a subdisk in a RAID-5 plex if the volume the plex is associated with does not have a log plex. This flag is the same as -f.

The raid5 usage type supports the following keywords:

assoc: Associate the named subdisks with the named RAID-5 plex. If plex is enabled and is associated with an enabled volume, then any data that maps onto the subdisk will be regenerated from the other columns of the RAID-5 plex. This is done by marking the subdisk as stale and writeonly, regenerating the data via VOL_R5_RECOVER ioctls, and then turning off the stale and writeonly flags.; If the RAID-5 plex is not associated or the RAID-5 volume is not ENABLED, the subdisk is associated and marked as stale. The subdisk's contents will be recovered when the volume is started.; The assoc operation may not be used on a log plex.
dis: Dissociate the named subdisks from the named RAID-5 plex. If removing the subdisk would make the volume unusable (because other subdisks in other columns at the same altitude are unusable or missing) and the volume is not disabled and EMPTY, the operation is not allowed. If the volume is disabled and non-EMPTY the operation requires use of -f.; The dis operation may not be used on a log plex.
split and join: The raid5 usage type applies no additional restrictions and adds no extensions to the split and join operations. These operations may not be used on a log plex.
mv: If the old subdisk is associated with a RAID-5 plex that is associated to a RAID-5 volume, the volume must be enabled for the move operation to complete. The mv operation is not allowed if the volume has stale parity or has missing or stale subdisks at the same altitude as the subdisk being replaced.; The mv operation first dissociates the old subdisk and then associates the new subdisk in its place. It then recovers the data using VOL_R5_RECOVER ioctls, as is done for the assoc operation. If the RAID-5 volume has no valid logs, the operation requires use of -f. This is necessary because if a crash were to occur while the data on the new subdisks was being recovered, the parity could become stale while some of the new subdisks are marked stale, thus rendering the volume unusable.; The mv operation may be used on a log plex. Similar rules as those defined for the fsgen and gen usage type plexes apply to log plexes. The force or -f must be used to make a log plex sparse.

Note that there is no aslog operation for the raid5 usage type. Logging is done on a plex level and therefore vxsd aslog is not needed. Log plexes can be associated with RAID-5 volumes using the vxplex att command.

Files

/etc/vx/type/usetype/vxsd: The utility that performs vxsd operations for a particular volume usage type.

Exit codes

The vxsd 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 vxintro(ADM) for a list of standard exit codes.

References

vxintro(ADM), vxplex(ADM), vxsd(ADM), vxvol(ADM), vxmake(F)