Common Volume Manager Commands

vxedit Command

The common command used to remove or rename Volume Manager objects (volumes, plexes, and subdisks) is the vxedit command. The vxedit command has two functions:

Volume Manager objects that are associated with other objects are not removable by the vxedit command. This means that the vxedit command cannot remove:

	NOTE: Using the recursive suboption (-r) to the removal option of the vxedit command removes all objects from the specified object downward. In this way, a plex and its associated subdisks, or a volume and its associated plexes and their associated subdisks, can be removed by a single vxedit command.

For detailed information, see the vxedit(1M) manual page.

vxtask Utility

The vxtask utility performs basic administrative operations on Volume Manager tasks that are running on the system. Operations include listing tasks, modifying the state of a task (pausing, resuming, aborting) and modifying the rate of progress of a task. See the vxtask(1M) manual page for more information.

Volume Manager tasks represent long-term operations in progress on the system. Every task gives information on the time the operation started, the size and progress of the operation, and the state and rate of progress of the operation. The administrator can change the state of a task, giving coarse-grained control over the progress of the operation. For those operations that support it, the rate of progress of the task can be changed, giving more fine-grained control over the task.

Every task is given a unique task identifier. This is a numeric identifier for the task that can be specified to the vxtask utility to specifically identify a single task. For most utilities, the tag is specified with the -t tag option.

Operations

The vxtask utility supports the following operations:

list

List tasks running on the system in one-line summaries. The -l option prints tasks in long format. The -h option prints tasks hierarchically, with child tasks following the parent tasks. By default, all tasks running on the system are printed. If a taskid argument is supplied, the output is limited to those tasks whose taskid or task tag match taskid. The remaining arguments are used to filter tasks and limit the tasks actually listed.

monitor

The monitor operation causes information about a task or group of tasks to be printed continuously as task information changes. This allows the administrator to track progress on an ongoing basis. Specifying -l causes a long listing to be printed. By default, short one-line listings are printed. In addition to printing task information when a task state changes, output is also generated when the task completes. When this occurs, the state of the task is printed as EXITED (see “Output”).

pause

resume

abort

These three operations request that the specified task change its state. The pause operation puts a running task in the paused state, causing it to suspend operation. The resume operation causes a paused task to continue operation. The abort operation causes the specified task to cease operation. In most cases, the operations "back out" as if an I/O error occurred, reversing to the extent possible what had been done so far.

set

The set operation is used to change modifiable parameters of a task. Currently, there is only one modifiable parameter for tasks: the slow attribute, which represents a throttle on the task progress. The larger the slow value, the slower the progress of the task and the fewer system resources it consumes in a given time. (The slow attribute is the same attribute that many commands, such as vxplex(1M), vxvol(1M) and vxrecover(1M) accept on command lines.)

Output

There are two output formats printed by the vxtask command: a short, one-line summary format per task, and a long task listing. The short listing provides the most used task information for quick perusal.

The long output format prints all available information for a task, spanning multiple lines. If more than one task is printed, the output for different tasks is separated by a single blank line. Each line in the long output format contains a title for the line, followed by a colon (:), followed by the information.

Examples

To list all tasks currently running on the system, use the following command:

# vxtask list

The vxtask list command produces the following output:

TASKID PTID TYPE/STATE PCT PROGRESS 162 RDWRBACK/R 01.10% 0/1048576/11520 VOLSTART mirrvol-L01

To print tasks hierarchically, with child tasks following the parent tasks, us the -h option, as follows:

# vxtask -h list

Use of the -h option produces the following output:

TASKID PTID TYPE/STATE PCT PROGRESS 167 ATCOPY/R 06.79% 0/1048576/71232 PLXATT mirrvol mirrvol-02

To trace all tasks in the diskgroup foodg that are currently paused, as well as any tasks with the tag sysstart, use the following command:

# vxtask -G foodg -p -i sysstart list

To list all tasks on the system that are currently paused, use the following command:

# vxtask -p list

The vxtask -p list command is used as follows:

# vxtask pause 167 # vxtask -p list TASKID PTID TYPE/STATE PCT PROGRESS 167 ATCOPY/P 27.82% 0/1048576/291712 PLXATT mirrvol(mirrvol-02) # vxtask resume 167 # vxtask -p list TASKID PTID TYPE/STATE PCT PROGRESS

To monitor all tasks with the tag myoperation, use the following command:

# vxtask monitor myoperation

To cause all tasks tagged with recovall to exit, use the following command:

# vxtask abort recovall

vxassist Command

You can use the vxassist command to create and manage volumes from the command line. The vxassist command requires minimal input from you and performs many underlying tasks for you. You can use the vxassist command to easily create, mirror, grow, shrink, remove, and back up volumes. The vxassist command is capable of performing many operations that would otherwise require the use of a series of more complicated Volume Manager commands. The vxassist command creates and manipulates volumes based on a set of established defaults, but also allows you to supply preferences for each task.

The vxassist command can perform tasks that would otherwise require the use of several other Volume Manager commands. The vxassist command automatically performs all underlying and related tasks that would otherwise be done by the user (in the form of other commands).

The vxassist command does not conflict with existing Volume Manager commands or preclude their use. Objects created by the vxassist command are compatible and inter-operable with objects created by other VM commands and interfaces.

The vxassist command typically takes the following form:

# vxassist keyword volume_name [attributes...]

Select the specific action to perform by specifying an operation keyword as the first argument on the command line. For example, the keyword for creating a new volume is make. You can create a new volume by entering:

# vxassist make volume_name length

The first argument after any vxassist command keyword is always a volume name. Follow the volume name with a set of attributes. Use these attributes to specify where to allocate space and whether you want mirroring or striping to be used.

You can select the disks on which the volumes are to be created by specifying the disk names at the end of the command line. For example, to create a 30 megabyte striped volume on three specific disks (disk03, disk04, and disk05), enter:

# vxassist make stripevol 30m layout=stripe disk03 disk04\disk05

The vxassist command defaults are listed in the file /etc/default/vxassist. The defaults listed in this file take effect if there is no overriding default specified on the vxassist command line.

The vxassist command performs the following tasks:

For more information, see the vxassist(1M) manual page.

Advantages of the vxassist Command

	NOTE: The vxassist command is required for vxrelayout.

Some of the advantages of using the vxassist command include:

• The use of the vxassist command involves only one step (command) on the part of the user.

• You are required to specify only minimal information to the vxassist command, yet you can optionally specify additional parameters to modify its actions.

The vxassist command tasks result in a set of configuration changes that either succeed or fail as a group, rather than individually. Most vxassist tasks work so that system crashes or other interruptions do not leave intermediate states to be cleaned up. If the vxassist command finds an error or an exceptional condition, it exits without leaving partially-changed configurations. The system is left in the same state as it was prior to the attempted vxassist task.

How the vxassist Command Works

The vxassist command allows you to create and modify volumes. You specify the basic volume creation or modification requirements and the vxassist command performs the necessary tasks.

The vxassist command obtains most of the information it needs from sources other than your input. The vxassist command obtains information about the existing objects and their layouts from the objects themselves.

For tasks requiring new disk space, the vxassist command seeks out available disk space and allocates it in the configuration that conforms to the layout specifications and that offers the best use of free space.

The vxassist command typically takes this form:

# vxassist keyword volume_name [attributes...]

where keyword selects the task to perform. The first argument after a vxassist command keyword is a volume name, which is followed by a set of attributes. For details on available vxassist keywords and attributes, see the vxassist(1M) manual page.

The vxassist command creates and manipulates volumes based on a set of established defaults, but also allows you to supply preferences for each task.

vxassist Command Defaults

The vxassist command uses a set of tunable parameters that can be specified in the defaults files or at the command line. The tunable parameters default to reasonable values if they are not listed on the command line. Tunables listed on the command line override those specified elsewhere.

Tunable parameters are as follows:

• Internal defaults—The built-in defaults are used when the value for a particular tunable is not specified elsewhere (on the command line or in a defaults file).

• System-wide defaults file—The system-wide defaults file contains default values that you can alter. These values are used for tunables that are not specified on the command line or in an alternate defaults file.

• Alternate defaults file—A non-standard defaults file, specified with the command vxassist -d alt_defaults_file.

• Command line—The tunable values specified on the command line override any values specified internally or in defaults files.

Defaults File

The default behavior of the vxassist command is controlled by the tunables specified in the /etc/default/vxassist file. The format of the defaults file is a list of attribute=value pairs separated by new lines. These attribute=value pairs are the same as those specified as options on the vxassist command line (see the vxassist(1M) manual page for details).

The following is a sample vxassist defaults file:

# by default: # create unmirrored, unstriped volumes # allow allocations to span drives # with RAID-5 create a log, with mirroring don't create a log # align allocations on cylinder boundaries layout=nomirror,nostripe,span,nocontig,raid5log,noregionlog, diskalign # use the fsgen usage type, except when creating RAID-5 volumes usetype=fsgen # allow only root access to a volume mode=u=rw,g=,o= user=root group=root # when mirroring, create two mirrors nmirror=2 # for regular striping, by default create between 2 and 8 stripe # columns max_nstripe=8 min_nstripe=2 # for RAID-5, by default create between 3 and 8 stripe columns max_nraid5stripe=8 min_nraid5stripe=3 # create 1 log copy for both mirroring and RAID-5 volumes, by default nregionlog=1 nraid5log=1 # by default, limit mirroring log lengths to 32Kbytes max_regionloglen=32k # use 64K as the default stripe unit size for regular volumes stripe_stwid=64k # use 16K as the default stripe unit size for RAID-5 volumes raid5_stwid=16k

vxdctl Daemon

The volume configuration daemon (vxconfigd) is the interface between the Volume Manager commands and the kernel device drivers (vol, vols, DMP). The config device is a special device file created by the Volume Manager that interacts with vxdctl to make system configuration changes.

Some vxdctl tasks involve modifications to the volboot file that indicates the location of some root configuration copies.

The vxdctl daemon is the interface to vxconfigd and is used for:

For more information, see the vxdctl (1M) manual page.

vxmake Command

You can use the vxmake command to add a new volume, plex, or subdisk to the set of objects managed by Volume Manager. The vxmake command adds a new record for that object to the Volume Manager configuration database. You can create records from parameters specified on the command line or by using a description file.

Specify operands on the command line as shown in this example:

# vxmake -Uusage_type vol volume_name len=length plex=plex_name,..

where:

If no operands are specified on the command line, then a description file is used to specify the records to create.

A description file is a file that contains plain text that describes the objects to be created with vxmake. A description file can contain several commands, and can be edited to perform a list of tasks. The description file is read from standard input, unless the -d description_file option specifies a filename.

The following is a sample description file:

#rectyp #name       #options
sd      disk3-01    disk=disk3 offset=0 len=10000
sd      disk3-02    disk=disk3 offset=25000 len=10480
sd      disk4-01    disk=disk4 offset=0 len=8000
sd      disk4-02    disk=disk4 offset=15000 len=8000
sd      disk4-03    disk=disk4 offset=30000 len=4480
plex    db-01       layout=STRIPE ncolumn=2 stwidth=16k
                    sd=disk3-01:0/0,disk3-02:0/10000,disk4-01:1/0,\
							disk4-02:1/8000, disk4-03:1/16000
sd      ramd1-01    disk=ramd1 len=640
                    comment="Hot spot for dbvol
plex    db-02       sd=ramd1-01:40320
vol     db          usetype=gen plex=db-01,db-02
                    readpol=prefer prefname=db-02
                    comment="Uses mem1 for hot spot in last 5m

This description file specifies a volume with two plexes. The first plex has five subdisks on physical disks. The second plex is preferred and has one subdisk on a volatile memory disk. For more information, see the vxmake (1M) manual page.

vxplex Command

The vxplex command performs Volume Manager tasks on a plex or on volume-and-plex combinations. The first operand is a keyword that specifies the task to perform. The remaining operands specify the objects to which the task is to be applied.

Use the vxplex command to:

For more information, see the vxplex (1M) manual page.

vxsd Command

The vxsd command maintains subdisk-mirror associations. Use the vxsd command to:

	NOTE: Some vxsd tasks can take a large amount of time to complete.

For more information, see the vxsd (1M) manual page.

vxmend Command

The vxmend command performs Volume Manager usage-type-specific tasks on volumes, plexes, and subdisks. These tasks fix simple problems in configuration records (such as clearing utility fields, changing volume or plex states, and offlining or onlining volumes or plexes).

The vxmend command is used primarily to escape from a state that was accidentally reached. The offline and online functions can be performed with disk-related commands.

For more information, see the vxmend (1M) manual page.

vxprint Command

The vxprint command displays information from records in a Volume Manager configuration database. You can use this command to display partial or complete information about any or all Volume Manager objects. The format can be hierarchical to clarify relationships between Volume Manager objects. UNIX system utilities such as awk, sed, or grep can also use vxprint output.

For more information, see the vxprint (1M) manual page.

vxrelocd Command

Hot-relocation is turned on as long as the vxrelocd program is running. It is advisable to leave hot-relocation turned on so that you can take advantage of this feature if a failure occurs. However, if you disable this feature because you do not want the free space on some of your disks used for relocation, you must prevent the vxrelocd program from starting at system startup time.

You can stop hot-relocation at any time by killing the vxrelocd process (this should not be done while a hot-relocation attempt is in progress).

You can make some minor changes to the way the vxrelocd program behaves by either editing the vxrelocd line in the startup file that invokes the vxrelocd program (/sbin/rc2.d/S095vxvm-recover) or killing the existing vxrelocd process and restarting it with different options. After making changes to the way the vxrelocd program is invoked in the startup file, reboot the system so that the changes take effect. If you kill and restart the daemon instead, make sure that hot-relocation is not in progress when you kill the vxrelocd process. You should also restart the daemon immediately so that hot-relocation can take effect if a failure occurs.

Thevxrelocd command can be altered as follows:

where the optional IOdelay indicates the desired delay (in milliseconds). The default value for the delay is 250 milliseconds. For more information, see the vxrelocd(1M) manual page.

vxstat Command

The vxstat command prints statistics about Volume Manager objects and block devices under Volume Manager control. The vxstat command reads the summary statistics for Volume Manager objects and formats them to the standard output. These statistics represent Volume Manager activity from the time the system initially booted or from the last time statistics were cleared. If no Volume Manager object name is specified, statistics from all volumes in the configuration database are reported.

For more information, see the vxstat(1M) manual page and Chapter 9 “Performance Monitoring”.

vxtrace Command

The vxtrace command prints kernel I/O error or I/O error trace event records on the standard output or writes them to a file in binary format. Binary trace records written to a file are also read back and formatted by the vxtrace command.

If no operands are given, then either all error trace data or all I/O trace data on all virtual disk devices are reported. With error trace data, you can select all accumulated error trace data, wait for new error trace data, or both (the default). Selection can be limited to a specific disk group, to specific Volume Manager kernel I/O object types, or to particular named objects or devices.

For more information, see the vxtrace(1M) manual page and Chapter 9 “Performance Monitoring”.

vxunrelocate Command

After the disk that experienced the failure is fixed or replaced, the vxunreloc command can be used to move all the hot-relocated subdisks back to the disk. When a subdisk is hot-relocated, its original disk media name and the offset into the disk, are saved in the configuration database. When a subdisk is moved back to the original disk or to a new disk using the vxunreloc command, the information is erased. The original dm name and the original offset are saved in the subdisk records. To print all of the subdisks that were hot-relocated from disk01 in the rootdg disk group, use the following command:

# vxprint -g rootdg -se 'sd_orig_dmname="disk01"'

To move all the subdisks that were hot-relocated from disk01 back to the original disk, use the following command:

# vxunreloc -g rootdg disk01

The vxunreloc command provides the -n option to move the subdisks to a different disk from where they were originally relocated. For example, when disk01 fails, all the subdisks that reside on it are hot-relocated to other disks. After the disk is repaired, it is added back to the disk group using a different name, for example, disk05. To move all the hot-relocated subdisks to the new disk, use the following command:

# vxunreloc -g rootdg -n disk05 disk01

The destination disk should have at least as much storage capacity as was in use on the original disk. If there is not enough space, the unrelocate operation fails and none of the subdisks are moved.

The vxunreloc command moves the hot-relocated subdisks to the original offsets. However, if some subdisks occupy part or all of the area on the destination disk, the vxunreloc command fails. If vxunreloc command failure occurs, select one of the following two options:

A subdisk that is hot-relocated more than once due to multiple disk failures can still be unrelocated back to its original location. For example, if disk01 fails, a subdisk named disk01-01 is moved to disk02. If disk02 then fails, all subdisks that reside on it, including the subdisk that was hot-relocated to it, are moved again. When disk02 is replaced, an unrelocate operation for disk02 does not affect hot-relocated subdisk disk01-01. However, a replacement of disk01, followed by the unrelocate operation, moves disk01-01 back to disk01 when the vxunreloc command is run immediately after the replacement.

Restarting the vxunreloc Program After Errors

Internally, the vxunreloc program moves subdisks in three phases.The first phase creates as many subdisks on the specified destination disk as there are subdisks to be unrelocated. When the subdisks are made, the vxunreloc program fills in the comment field in the subdisk record with the string UNRELOC for identification. In the second phase, the data is moved. If all the subdisk moves are successful, the third phase clears the comment field of the subdisk records.

Making the subdisk is an all-or-none operation. If the vxunreloc program cannot make all the subdisks successfully, no subdisks are made and the vxunreloc program exits. The operation of the subdisks move is not all-or-none. One subdisk move is independent of another, and as a result, if one subdisk move fails, the vxunreloc utility prints an error message and then exits. However, all of the subsequent subdisks remain on the disk where they were hot-relocated and are not moved back. Subdisks that are returned home retain the UNRELOC string in the comment field of the subdisk records because the cleanup phase does not execute.

If the system goes down after the new subdisks are made on the destination, but before they are moved back, the unrelocate utility can be executed again after the system is brought back up. As described above, when a new subdisk is created, the vxunreloc command sets the comment field of the subdisk to UNRELOC. Re-execution of the vxunreloc command checks the offset, the len, and the comment fields of the existing subdisks on the destination disk to determine if the subdisks were left on the disk during a previous execution of the vxunreloc command.

	NOTE: Do not manually modify the string UNRELOC in the comment field.

If one out of a series of subdisk moves fails, the vxunreloc program exits. Check the error that caused the subdisk move to fail and determine if the unrelocation can proceed. When you re-execute the vxunreloc command to resume the subdisk moves, it uses the subdisks created at a previous run.

The cleanup phase is performed with one transaction. The vxunreloc command resets the comment field to a NULL string for all subdisks marked as UNRELOC that reside on the destination disk. This includes clean-up for those subdisks that were unrelocated in any previous invocation of the vxunreloc command.

vxvol Command

The vxvol command performs Volume Manager tasks on volumes. Use the vxvol command to:

Starting a volume changes its kernel state from DISABLED or DETACHED to ENABLED. Stopping a volume changes its state from ENABLED or DETACHED to DISABLED. For more information about volume states, see Chapter 8 “Recovery”.

Use the vxvol command to specify one of these read policies:

For more information, see the vxvol (1M) manual page.