vxsd

NAME

vxsd - perform VERITAS Volume Manager operations on subdisks

SYNOPSIS

DESCRIPTION

The vxsd utility performs VERITAS Volume Manager (VxVM) 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. 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(1M). 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.

KEYWORDS

aslog

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

assoc

Associates each named subdisk operand with the specified plex. The first form applies to concatenated plexes (that is, with a layout of concat). The offset within the plex for the association can be specified with -l, which takes a standard VERITAS Volume Manager length number (see vxintro(1M)). 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(4)). 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 VERITAS 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.

dis

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

join

Joins 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

Moves the contents of oldsd onto the new subdisks and replaces 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.

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

OPTIONS

-d

Discard the relocation origin information in the subdisk record. When a user attempts to manually move a subdisk that has been hot-relocated, the -d option can be specified to discard the relocation origin information in the subdisk record. When this option is specified, the subdisk will not be unrelocated to its original disk using the vxunreloc utility.

-f

Force an operation that VxVM 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.

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

-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 length number in VxVM (see vxintro(1M)).

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

iosize=size

Perform copy operations in regions with the length specified by size, which is a standard VERITAS Volume Manager length number (see vxintro(1M)). 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 1 megabyte.

noecopy

Turns off Extended Copy Services for one invocation of a vxsd mv operation. By default, the Extended Copy Services feature of VxVM automatically offloads copy requests to an array's copy manager if both the source and destination disks are enabled for ecopy operations.

rm

Remove the subdisks after successful completion of a vxsd dis operation. Remove the source subdisk after successful completion of vxsd mv.

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

-p plex

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

-r

Retain the relocation origin information in the subdisk record. When a user attempts to manually move a subdisk that has been hot-relocated, either the -r or the -d option has to be provided to specify the disposition of the origin information, otherwise, the vxsd command returns an error. The -r option provides the user a way to retain the relocation origin information during a manual move.

-s size

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

-t tasktag

If any tasks are registered to track the progress of the operation, mark them with the tag tasktag. The tag specified by tasktag is a sequence of up to 16 alphanumeric characters.

-U usetype

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

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

-V

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

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

Forces an operation that VxVM 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:

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.

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.

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.

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.

split and join

The fsgen and gen usage types apply no additional restrictions and add no extensions to the split and join operations.

RAID-5 USAGE TYPE

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

force

Forces an operation that VxVM 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.

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 creates a redundant subvolume structure and synchronizes the new subdisk(s) using VOL_R5_RECOVER ioctls. This makes the operation safe in case of failures in the new subdisks, and does not put the integrity of the data at risk.

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.

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.

FILES

/usr/lib/vxvm/type/usetype/vxsd

The utility that performs vxsd operations for a particular volume usage type.

EXIT CODES

The vxsd utility exits with a non-zero status if the attempted operation fails. A non-zero 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(1M) for a list of standard exit codes.

EXAMPLES

Split subdisk disk03-02 (with size 2000 megabytes) into subdisks disk03-02, disk03-03, disk03-04 and disk03-05 (each with size 500 megabytes):

Join contiguous subdisks disk03-02, disk03-03, disk03-04 and disk03-05 as subdisk disk03-02:

Move the contents of subdisk disk02-02 slowly to subdisk disk03-01, and then remove disk02-02:

Add subdisk disk03-02 to the end of the concatenated plex, agg-01:

Add subdisks disk03-03, disk04-03, and disk05-03 to the ends of the three columns in the striped plex, okapi-01:

Dissociate subdisk disk04-01 from its plex, and then remove it altogether:

SEE ALSO

vxassist (1M), vxintro (1M), vxmake (1M), vxplex (1M), vxtask (1M), vxunreloc (1M), vxvol (1M)