Home > Veritas Storage Foundation™ Volume Manager Manual Pages
VXVOL (1M) |
Maintenance Commands |
vxvol [-fqV] [-g diskgroup] [-m] [-r rvg] assoc rvg volume [primary_datavol]
vxvol [-f] [-g diskgroup] [-c "ch_addopt"] [-o index] assoc vset volume [index]
vxvol [-fqV] [-g diskgroup] dis volume
vxvol [-g diskgroup] [-c "ch_rmopt"] dis volume vset
vxvol [-qV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] init init_type volume [arg ...]
vxvol [-fqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] maint volume ...
vxvol [-fqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] noderecover volume ...
vxvol [-fqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] rdpol policy volume [plex]
vxvol [-fqV] [-g diskgroup] [-U usetype] [-o useopt] recover volume [subdisk] ...
vxvol [-fqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] resync volume ...
vxvol [-fqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] set attribute=value ... [ -- ] volume ...
vxvol [-faqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] start volume ...
vxvol [-faqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] startall
vxvol [-faqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] stop volume ...
vxvol [-faqV] [-g diskgroup] [-U usetype] [-o useopt] [-t tasktag] stopall
Each operation can be applied to only one disk group at a time. If a disk group is not specified using the -g diskgroup option, the default disk group is determined using the rules described in vxdg(1M).
Note: If the RVG already has associated volumes, then the new volume being associated should be of the same type as the existing volumes. A volume can be either VxVM ISP volume or VxVM non-ISP volume.
(Volume Sets) Associates the specified standalone volume, vol, with the volume set, vset. If the -o index option is specified, the value of the index argument is assigned to the volume. If the -o index option is not specified, an index value is assigned automatically.
Note: If volume set is associated to the RVG then the added volume is associated to the RVG automatically.
Note: The volume must be in the same disk group as the volume set, and it may not already be a member of another volume set.
After the move, any ch_addopt argument string that is specified using the -c option is passed to the vset_addvol content-handler operation (if any). This string indicates how the volume is to be processed by the application. For example, the string may indicate how the volume should be incorporated into a file system. The vset_addvol operation may provide a context string that is stored in the volume record.
Note: The -f (force) option must be specified if the volume being associated with the volume set, or any volume in the volume set, is either a snapshot or the parent of a snapshot. Using this option can potentially cause inconsistencies in a snapshot hierarchy if any of the volumes involved in the operation is already in a snapshot chain.
(Volume Sets) Dissociates the specified volume, vol, from the volume set, vset, and makes it available a standalone volume.
Note: If the volume set and the volume are associated to the RVG then this operation automatically dissociate the volume from the RVG.
The content-handler string, ch_rmopt, that is specified by the -c option is passed to the vset_rmvol content-handler operation (if any). Typically, the vset_rmvol operation (if any) may choose to reorganize the data in the data set before performing the remove operation, or alternatively, it may cancel the the remove operation altogether.
Note: A volume set is deleted when the final volume is removed from it.
Note: The -f (force) option must be specified if the volume being disassociated from the volume set, or any volume in the volume set, is either a snapshot or the parent of a snapshot. Using this option can potentially cause inconsistencies in a snapshot hierarchy if any of the volumes involved in the operation is already in a snapshot chain.
This operation is currently applicable only to the volumes with DRL logs and is relevant only in clustered systems.
- prefer
- Reads 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 prefer read-policy type.
- round
- Uses a round-robin read order among the enabled, readable plexes associated with the volume. No plex operand should be specified for the round read-policy type.
- select
- Selects a default policy based on plex associations to the volume. For a volume that contains one enabled, striped plex, the default is to prefer that plex. For any other set of plex associations, the default is to use a round-robin policy. No plex operand should be specified for the select read-policy type.
- siteread
- Reads preferentially from plexes at the locally defined site. This is the default policy for volumes in disk groups where site consistency has been enabled. No plex operand should be specified for the siteread read-policy type.
The set of attribute=value attribute arguments that are recognized depends upon the volume usage type (see the sections on usage types later in this manual page for information on available attributes). However, an attribute argument of the form len=number is expected to be interpreted (if at all) as requesting a change in the length of a volume, regardless of the volume's usage type. The number value is interpreted as a standard length number (see vxintro(1M)).
If the start operation is applied to an uninitialized volume (for example, a volume just created by vxmake), a default initialization is used to initialize and enable the volume.
If the volume is not normally started because failures and disk removals have left all associated plexes with invalid data, the -f option can be used to try to start the volume, anyway. This can be used after replacing disks to enable the volume so that its contents can be restored from backup or reinitialized.
The -a option can be used to start the sub-volumes of a layered volume recursively. If the top-level volume in a layered volume fails to start, its sub-volumes are not started.
The -a option can be used to start the sub-volumes of a layered volume recursively. If the top-level volume in a layered volume fails to start, its sub-volumes are not started.
Note: It is rarely necessary to stop a volume in this way. If required for debugging purposes, use the vxvol maint command to take a volume offline, or to prevent a volume from being opened.
A disk group cannot be deported until all its volumes are closed. The stop operation cannot be used to close a volume that is open to applications. Even if the -f option is specified for an open volume, the volume is disabled but not closed. Failures are returned for any pending or further I/O operations on the volume device.
The -a option stops the sub-volumes of a layered volume recursively. (This is the default behavior from VxVM 4.0 onwards.)
Note: A layered volume is only stopped if either the top-level volume, or all of the volumes in the layered volume are specified as arguments. If the top-level volume in a layered volume is in use, its sub-volumes are not stopped.
If the -o usetype option is specified, VxVM attempts to stop all disabled volumes with the indicated usage type. By default, all volumes in the default disk group (see vxdg(1M)) are stopped. A different disk group can be specified with the -g option.
Note: If the top-level volume in a layered volume is in use, its sub-volumes are not stopped.
Note: The mapping is only necessary and is only maintained on the secondary. The primary does not know or care what names the secondary is using for its data volumes.
The current mapping for a secondary volume is given by the primary_datavol field in the long listing of the secondary volume (vxprint -l). If this field is not listed, then global naming is in effect for that data volume, which means that the secondary is using the same name as the primary. The primary_datavol field can also be set for a secondary data volume with vxedit(1M).
- bg
- Performs any extended revive operations in background processes after the volume and one or more plexes have been enabled. A volume that is started, or whose length is changed successfully with this option, is usable immediately after the operation completes, although recovery operations may affect performance of the volume for an extended period of time.
- delayrecover
- Does not perform any plex revive operations when starting a volume. Instead, the volume and any plexes are enabled. This may leave some stale plexes, and may leave a mirrored volume in a special read-writeback (NEEDSYNC) recover state that performs limited plex recovery for each read to the volume.
- index
- Specifies the index of a volume within a volume set.
- iosize=size
- Performs recovery 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.
- plexfork[=count]
- Performs up to count plex revive operations simultaneously. If no count is specified, then a suitable small number is used.
- slow[=iodelay]
- Reduces the system performance impact of plex recovery operations and volume length changes. Startup recovery and length change consistency operations are usually a set of short operations on small regions of the volume (normally from 16K bytes to 128K bytes). 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 else a default is chosen (normally 250 milliseconds).
- node=nodename
- Specifies the name of a cluster node on which to process this task. This attribute is used by vxrecover while executing vxvol when the volume recovery I/O distribution is in effect. The nodename should be in the form displayed in the output of the vxclustadm nidmap command.
- verbose
- Prints a message for each volume that is successfully started. Without this option, messages appear only for volumes that fail to start.
In addition to the standard -o options required for all usage types, the fsgen and gen usage types provide the following additional options:
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.
- vxvol init active volume
- Sets the state for all plexes associated with volume to ACTIVE and enables 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.
- vxvol init clean volume [plex]
- Sets the state for the specified plex to CLEAN, and sets all other plexes to STALE. The vxvol start operation can then be used to recover the volume from the CLEAN plex. This operation requires that the volume not be enabled.
If the specified volume has only one plex, then the plex argument is not required as it defaults to that plex. If specified, then the plex argument must represent a plex that is associated with the volume.
- vxvol init enable volume
- Enables the volume and its plexes but leaves the volume uninitialized. 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.
- vxvol init zero volume
- Writes 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 volume 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 some cleanup. A set of commands to perform this cleanup are written to the standard error before the volume utility exits.
Plexes in the SYNC state may already be under recovery and the volume command takes no action to recover them unless the command was invoked with the -o force option.
- exclusive=yes|y|on|true|no|n|off|false
- Sets or clears the EXCLUSIVE flag on the volume. A volume in exclusive open state can be opened by only one node in the cluster at a time. Multiple opens of an exclusive volume from the same node are permitted. Non-exclusive volumes can be simultaneously opened by more than one node. After a node opens an exclusive volume, every other node's open attempt fails until the last close of the volume by the first opener. Such an open failure returns a EBUSY error code. Available only if the Veritas Volume Manager cluster feature is enabled.
- fastresync=yes|y|on|true|no|n|off|false
- Enables or disables the FastResync (previously known as Fast Mirror Resynchronization) feature. If enabled, FastResync is non-persistent if no DCO object or DCO volume are associated with a volume. By default, Persistent FastResync is enabled on a volume when a DCO object and DCO volume are created.
Note: A license is necessary to use the FastResync feature.
- fmr=yes|y|on|true|no|n|off|false
- Identical to fastresync.
- len=number
- Changes the length of each volume specified by the volume operands to number sectors. number is a standard Veritas Volume Manager length number (see vxintro(1M)). Decreasing the length of a volume requires use of -f.
If the volume is enabled, the number of enabled, read-write plexes that would remain complete after the length change is calculated. The operation fails if this number would become zero, but the number of sparse plexes would become greater than 1. Changing the length of a volume with one enabled plex beyond the length of the plex requires use of the -f option.
If the volume is not enabled, the number of CLEAN and ACTIVE plexes that would remain complete after the length change is calculated. The operation fails if this number would become zero, but the number of sparse plexes would become greater than 1. Changing the length of a volume with one enabled plex beyond the length of the plex requires use of the -f option.
To ensure that the new region of the volume is consistent across all plexes of the volume, the volume is put into a SYNC state and read/write-back mode, and a read loop is then performed against the volume. Once this loop has completed, the volume is put back into the ACTIVE state.
- loglen=size
- Sets the size for logs used with the volume. The size value is a standard Veritas Volume Manager length numbers (see vxintro(1M)).
- logmap_len=size
- Specifies the maximum usable size of a DRL or DCM log. This value must be a positive integer multiple of the alignment value for the disk group (see vxdg(1M)).
- logtype=type
- Sets 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:
- dcm
- (VVR only) Used by VVR for srl overflow protection and autosync.
- drl
- Logs the regions involved in all mirrored or RAID-5 volume writes. (Dirty region logging or DRL is used for speedy recovery after a system crash.)
Note: For volumes with version 20 DCOs, DRL is supported within the DCO volume itself.
- drlseq
- (Sequential DRL) Identical to drl except that the number of dirty bits that can be set in the DRL is limited to the value of the tunable voldrl_max_seq_dirty (default value is 3). This is useful on volumes that are usually written to sequentially, such as database log volumes. Limiting the number of dirty regions allows for faster recovery if a crash occurs. However, if applied to volumes that are written to randomly, this type of logging can be a performance bottleneck as it limits the number of parallel writes that can be carried out.
Note: For volumes with version 20 DCOs, sequential DRL is supported within the DCO volume itself.
- none
- Turns off logging.
- undef
- Turns off logging until a vxsd aslog or vxplex att operation changes it to drl. See the fsgen and gen sections of vxsd(1M) and vxplex(1M) for more information.
- siteconsistent={on|off}
- Controls whether a volume that is being created inherits the site-consistency attribute setting that is configured on the disk group (see vxdg(1M)). This setting is persistent, and does not change when the setting on the disk group is changed.
If set to on, a volume that is being created must have a number of mirrors equal to or a multiple of the number of sites. If off is specified, this requirement is removed.
Note: Site consistency is not supported for RAID-5 volumes.
- startopts=volume_options
- Sets 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.
Starting a volume with no active dirty region logging involves enabling all CLEAN and ACTIVE plexes and putting them in the ACTIVE state. If an I/O failure was logged against the plex, or if a disk replacement caused a plex to become stale, then the plex is considered STALE. If any of the subdisks for the plex reside on a removed or inaccessible disk, then the plex is ignored for the purposes of starting the volume.
If two or more plexes were enabled, and if the volume was active at the time the system went down, then the state for the volume is set to SYNC and a special read/write-back recovery mode is used to recover consistency of the volume, segment-by-segment, on every read. A process is then started (in the background with the -o bg option) to recover consistency for the entire length of the volume.
If any plexes were considered STALE, then those plexes are attached by calling vxplex att. The number of concurrent plex attach operations are limited based on the rules for -o plexfork.
Recovery of plexes with a dirty region log uses the same rules as for volumes without a valid dirty region log, except that recovery of non-stale plexes is done by scanning the contents of the dirty region log and recovering consistency for those regions listed in the log as requiring recovery.
In addition to enabling the volume and managing the recovery of plex consistency, starting a volume clears any transient operations that were being applied to a volume before the system was rebooted. Starting a volume dissociates and removes temporary plexes or subdisks, and dissociates plexes that were being attached if the attach operation did not complete. Snapshot plexes created by vxassist are also removed.
If the volume is unstartable because there are no valid, non-stale plexes and the -f flag is then specified, all STALE plexes that do not contain unusable subdisks (subdisks on failed or removed disks) are changed to ACTIVE. The volume is then started and synchronized from those plexes.
- If the plex is detached or disabled, set the state for the plex to STALE. If all plexes are set to STALE, then the volume cannot be started until vxmend is used to change the state of one or more plexes to CLEAN or ACTIVE. A plex normally becomes detached as a result of an I/O error on the plex, or a disk failure or replacement. I/O failures do not normally detach the last remaining enabled plex in a volume, so disk removal operations are the only normal operational method of making a volume unstartable.
- If the plex is volatile, that is, one of the subdisks in the plex is defined on a disk with the volatile attribute (see vxdisk(1M)), then set the plex state to STALE.
- If the volume is enabled and the plex is also enabled, then set the plex state to CLEAN.
- If the volume is detached and the plex is enabled, then the plex state is left as ACTIVE. A volume can be left detached, with remaining valid plexes, only as a result of calling vxvol maint to detach an enabled volume.
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 tutil0 field in a volume or plex record. If the -f option is specified, then the stop operation ignores volume and plex tutil0 fields.
The -f 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. Stopping an open or mounted volume is not normally advisable.
- vxvol init active volume
- Zeros the RAID-5 log plexes, if any, and make the volume available for use. The parity in the volume is marked as stale, though no parity resynchronization is performed; the volume is left with a state of NEEDSYNC.
- vxvol init zero volume
- Writes zeros to the RAID-5 log plexes, if any, and write zeros to the entire length of the volume. This is achieved by issuing the VOL_R5_ZERO ioctl for the entire altitude of the volume. The volume is left in the ACTIVE state.
- recover [subdisk ...]
- Initiates a recovery of subdisks containing invalid data. If subdisks are specified and are stale, they are recovered in the order specified. This is done by setting the stale and write-only flags on the subdisks and issuing VOL_R5_RECOVER ioctls to regenerate the data. After a successful recovery, the subdisk is marked as non-stale and read-write.
If no subdisk arguments are specified, the subdisks of the RAID-5 plex of the volume are checked to see if they are stale or have invalid contents. If any are found, they are recovered as described above.
- len=number
- Changes the length of the volumes specified to be number sectors. number is a standard Veritas Volume Manager length specification (see vxintro(1M)). Decreasing the length of a volume requires -f.
The volume length cannot be increased such that the RAID-5 plex is sparse in respect to the new volume length; this would make the volume unusable.
In order to assure that the new region of the volume is consistent, the new region of the volume (from the old length to the new length) is filled with zeros by issuing VOL_R5_ZERO ioctls before the length is reset.
- loglen=size
- Sets the size of the RAID-5 log for the volume. This cannot be set if the volume has no logs. If the length is being increased, the operation is not allowed if it would cause any of the RAID-5 log plexes to become sparse in respect to the new length.
- startopts=volume_options
- Sets 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. Unrecognized or inappropriate options are ignored.
Starting a volume that has been shut down cleanly or is not marked as dirty enables the RAID-5 plex and RAID-5 log plexes, and sets the volume kernel state to detached to zero the RAID-5 log plexes for the volume, if any. Once this is completed, all valid RAID-5 log plexes are set to LOG and the volume is enabled and put in the ACTIVE state.
Starting a volume that was not shut down cleanly requires that the parity be resynchronized. If the volume has valid RAID-5 log plexes, the volume is first detached and has its state set to REPLAY, and all log plexes and the RAID-5 plex are enabled. If there are any valid RAID-5 log plexes, their contents are read and their data is written to the appropriate regions of the RAID-5 plex. If reading the RAID-5 logs fails, the logs are marked as invalid and the parity is resynchronized as if there were no logs. Once the replay is complete, the RAID-5 logs are enabled and the volume is enabled and its state is set to ACTIVE.
If the volume needs resynchronization and no valid log plexes exist, the parity must be fully resynchronized. The volume is enabled and its state is set to RESYNC, and the RAID-5 plex is enabled. If usable RAID-5 plexes are available, but contain invalid data, they are zeroed. The parity is then resynchronized by issuing VOL_R5_RESYNC ioctls for the entire length of the volume. Once this is completed, the volume's state is set to ACTIVE. Any usable RAID-5 logs are enabled and set to the LOG state.
If a volume requires full resynchronization (that is, has no usable logs) and the RAID-5 plex has stale or unusable subdisks, the volume is unusable and the start operation fails. This can be overridden by using the -f flag or the -o force option. In this case, any stale subdisks are marked as non-stale and a full resynchronization is performed; however, this may result in some invalid data being introduced into the volume. If multiple subdisks at the same altitude in the RAID-5 plex are unusable (such as because they have their NODEVICE flag set), the volume is unusable and cannot be overridden.
Once any parity resynchronization has been completed, any subdisks still marked as stale are recovered. This is done by marking the subdisk as stale and write-only and issuing VOL_R5_RECOVER ioctls to regenerate the data on the stale subdisks. The subdisk is then marked as non-stale and read-write.
If the -o delayrecover option is specified, the only recoveries that are performed are log replays. If the volume requires a parity resynchronization, it is enabled and left in the NEEDSYNC operation, and its parity is marked as stale. Any subdisk recoveries that are needed are not performed, and the stale subdisks are marked as stale.
Normally, if a volume has no RAID-5 logs, it is not enabled with a stale subdisk or an unusable subdisk. This is because a system crash or power failure while the volume is in use can make the parity stale and render the volume unusable. This behavior can be overridden by specifying the -o unsafe option, which enables the volume during the above situations.
Caution: Using the -o unsafe option can potentially result in data loss.
If only the -o delayrecover option is specified to start a volume with a stale subdisk or an unusable subdisk, the start operation fails. In this case, the delayrecover option can be ignored by also specifying the -o syncstartok option.
Normally, the stop operation fails if any extended operations are using the volume or any of its plexes. Such operations are detected as a non-empty value for the tutil0 field in a volume or plex record. If the -f option is specified, then the stop operation ignores volume and plex tutil0 fields.
See vxintro(1M) for a list of standard exit codes.
Last updated: 17 Jul 2008
Copyright ©2009 Symantec Corporation
All rights reserved.