vxdmpadm

NAME

vxdmpadm - DMP subsystem administration

SYNOPSIS

DESCRIPTION

The vxdmpadm utility is an administrative interface to the VERITAS Volume Manager (VxVM) Dynamic Multipathing (DMP) facility. vxdmpadm lists the paths under a DMP device, gets the DMP device corresponding to a path, lists all the disk controllers on the system, lists all the paths through a host disk controller, lists all the DMP nodes through a disk array, and enables or disables a host disk controller on the system.

vxdmpadm keywords select the action to perform, and attributes specify the objects on which the action is performed.

KEYWORDS

cfgapm

Loads the specified array policy module (APM) together with any required attribute-value pairs into the CLI. An APM is a dynamically loadable kernel module that is developed by array vendors for the supported array. DMP refers to the latest version of APM that is available to it. If the current APM does not support certain arrays, DMP refers to the APM with the next lowest version number.

One of the following options may be specified for configuring the APM:

-a

Adds a vendor-supplied APM and configures it.

-r

Removes an APM if it is not busy.

-u

Refers DMP to the specified APM. This allows an older version of an APM to be used instead of the latest version.

disable

Disables I/O on a host disk controller or path. This prevents DMP from issuing I/O requests through the specified controller or path. Depending on the number of pending I/O requests, this command can take some time to complete before returning control to the user. The command blocks until all pending I/O that was issued through the specified disk controller or path has been completed.

The disable operation fails with an error if it is applied to a controller that is connected to the disk through a single path.

The following options may be used with the disable operation:

-c

Checks if the specified path is the last active path to the disk.

-f

Forcibly disables the last active path to the disk.

disable supports the attributes ctlr, enclosure, and type. (A specified enclosure type must be an enclosure category that supported by DMP.)

enable

Enables a previously disabled host disk controller or path to accept I/Os. This operation succeeds only if the controller or path is accessible to the host and I/O can be performed on it. When connecting Active/Passive disk arrays in a non-clustered environment, using enable results in a failback of I/Os to the primary path.

Attributes that can be specified with enable are enclosure, type, path, and ctlr. (A specified enclosure type must be an enclosure category that supported by DMP.)

getattr

Displays the default and current settings of the iosize or partitionsize attribute for the specified enclosure, array, or array type.

getctlr

Lists the logical and physical names of a specified controller, or of all the controllers present in the system.

getlungroup

Displays all DMP nodes in the same LUN group as the DMP node that is named as the argument to the dmpnodename attribute. dmpnodename specifies the DMP metanode name, and must be a valid node listed in the /dev/vx/[r]dmp directory.

getdmpnode

Displays the DMP device that controls a particular physical path. The physical path is specified as the argument to the nodename attribute. nodename must be a valid path listed in the /dev/[r]dsk directory.

Use the enclosure attribute with getdmpnode to obtain a list of all DMP nodes for the specified enclosure.

getsubpaths

Displays the paths controlled by the specified host controller (ctlr), DMP node (dmpnodename) or third-party driver (TPD) device (tpdnodename).

A specified DMP node name must be a valid node in the /dev/vx/[r]dmp directory.

When the tpdnodename attribute is used to specify a TPD device, the command displays the paths that DMP maintains for that device, provided that the coexistence of the TPD with DMP is supported by an appropriate ASL.

Enabled paths which are available for I/O are indicated by ENABLED(A) in the STATE column. A path that is enabled, but which is not currently available for I/O, is shown as ENABLED. For A/A arrays, all enabled paths that are available for I/O are shown as ENABLED(A). For A/P arrays in which the I/O policy is set to singleactive, only one path is shown as ENABLED(A). The other paths are enabled but not available for I/O. If the I/O policy is not set to singleactive, DMP can use a group of paths (all primary or all secondary) for I/O, which are shown as ENABLED(A).

A path that is set manually, rather than being discovered, is indicated by M in the PATH-TYPE column.

gettpdnode

Displays the third-party driver device that corresponds to the node specified as the argument to the nodename attribute.

help

Displays a detailed information about attributes used with a particular keyword. For example, to obtain a usage message for listctlr, use the command:

iostat

Controls the gathering and display of I/O statistics using the following keywords:

reset

Resets the counters to zero.

show

Displays I/O statistics for all controllers, or for a specified node, enclosure or path. The statistics displayed are the CPU usage and amount of memory per CPU used to accumulate statistics, the number of read/write operations, the number of blocks read/written, and the average time in milliseconds per read/write operation.

The interval and count attributes may be used to specify the interval in seconds between displaying the I/O statistics and the number of lines to be displayed. The actual interval may be smaller than the specified value if insufficient memory is available to record the statistics.

dmpnodename specifies the DMP metanode name, and must be a valid node listed in the /dev/vx/[r]dmp directory.

start

Enables the gathering of I/O statistics. The memory attribute can be used to limit the maximum amount of memory that is used to record I/O statistics for each CPU. The default limit is 32KB per CPU.

stop

Disables the gathering of I/O statistics.

listapm

This displays all the APMs in the system. The list includes the file name of the module, the array type supported by the module, the APM name, APM version and status (loaded or not) of the module.

You can also specify a module name. The details of this module will be displayed.

listctlr

Lists the disk controllers connected to the host. listctlr all lists all controllers on the host. You can specify the enclosure, ctlr, and type attributes to display a list of controllers on a particular disk array or on a particular enclosure type.

listenclosure

Displays all attributes of the specified enclosure. For example, this command displays all attributes for the disk array ENC01:

The attribute all displays the attributes associated with all the enclosures connected to the host.

setattr

Assigns a new value for an attribute to the specified array, array type, enclosure, or path.

The following attribute may be set for named arrays or enclosures, or for array types:

iopolicy

Determines the I/O policy that is used to balance the I/O load across multiple paths to a disk array or enclosure in a system. You can set policies for an enclosure (for example, HDS01), for all enclosures of a particular type (for example, HDS), or for all enclosures of a particular array type (A/A for active/active, or A/P for active/passive).

The policies that can be set are:

adaptive

In SAN environments, determines the paths that have the least delay, and schedules I/O on paths that are expected to carry a higher load. Priorities are assigned to the paths in proportion to the delay.

balanced [partitionsize=block_shift]

Takes the track cache into consideration when balancing I/O across paths. This is the default policy.

The size of the track cache may be specified using the partitionsize attribute. The size is in blocks and should be a power of 2. If the specified size is not a power of 2, it is rounded down to the nearest power of 2. A value of 0 selects the default of 1024 blocks.

minimumq

Uses a minimum I/O queue policy. I/O is sent on paths that have the minimum number of I/O requests in the queue. This policy is suitable for low-end disks or JBODs where a significant track cache does not exist.

priority

Assigns the path with the highest load carrying capacity as the priority path. (The path priority may be set using the vxdmpadm setattr path command as described below.)

round-robin

Sets a simple round-robin policy for I/O.

singleactive

I/O is channeled through the single active path.

The following attributes may be set for enclosures:

name

Assigns a new name to the specified enclosure. Each enclosure must have a unique name. This name can be used to refer to the enclosure during any vxdmpadm operation.

The new name cannot be more than 25 characters. If a name exceeds this length, setattr fails with an error message.

tpdmode

Specifies the form of device names that VxVM commands such as vxdisk display for devices that are controlled by third-party drivers (TPDs) whose coexistence is supported by an appropriate ASL. If set to pseudo (default), the TPD node name is used. If set to native, the subpath with the smallest device number known to the operating system is used.

The following attributes may be set for paths:

active

Changes a standby path to active.

nomanual

Restores the original primary or secondary attributes of a path.

nopreferred

Restores the normal priority of the path.

preferred [priority=N]

Specifies a preferred path, and optionally assigns a priority value to it. This indicates a path that is able to carry a higher I/O load. The priority value must be an integer greater than or equal to 1. Larger priority values indicate a greater load carrying capacity.

primary

Assigns a primary path for an Active/Passive disk array.

secondary

Assigns a secondary path for an Active/Passive disk array.

standby

Marks a path as not available for normal I/O scheduling. This path is only invoked if there are no active paths available for I/O.

start restore

Starts the DMP restore daemon. The restore daemon analyzes the condition of paths every interval seconds. The type of analysis depends on the specified policy:

check_all

The restore daemon analyzes all paths in the system and revives the paths that are back online as well as disables the paths that are inaccessible.

check_alternate

The restore daemon checks that at least one alternate path is healthy. It generates a notification on the first occasion that this condition is not met.

If there are less than two active (and enabled) paths under a DMP node, vxnotify displays the message "dmpnode name has N alternate paths."

check_disabled

The restore daemon checks the condition of paths that were previously disabled due to hardware failures and revives them if they are back online.

check_periodic

The restore daemon performs check_all once in a given number of cycles, and check_disabled in the remainder of the cycles.

The default policy is check_disabled. To change the interval or policy, you must stop the restore daemon and restart it with new attributes.

To set the policy to check_all, enter:

If a controller disabled using the following command, the restore daemon does not change the disabled state of the path through it.

To set the polling interval to 400 seconds, enter:

Caution: The default polling interval is 300 seconds. Decreasing this interval can adversely affect system performance.

The check_periodic policy can be invoked as follows:

The period n is the number of times that check_disabled is invoked before check_all is invoked. This sequence is then repeated.

The integer value n of period can either be specified on the command line, or set as a tunable dmp_restore_daemon_cycles (this requires a system shutdown and reboot to take effect). The value of period specified on the command line takes precedence. If not specified in either of these ways, the default period is 10.

The check_alternate policy can be invoked as follows:

stat errord

Displays the number of error daemons running.

stat restored

Displays the status of the automatic path restoration daemon, the interval of polling, and the policy used to check the condition of paths.

stop restore

Stops the VERITAS Volume Manager restore daemon. Automatic path failback stops if the restore daemon stops.

EXIT CODES

vxdmpadm exits with a zero status if the attempted operation succeeds. 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

To display the usage message for all vxdmpadm commands, enter:

To list all attributes of all host I/O controllers on the system, enter:

To list all attributes of all the enclosures on the system, enter:

To list all attributes of the disk array enc0, enter:

Assign the new name l1e1 to the disk array ENC01:

To disable I/O through the host disk controller c2, enter:

If you then run the listctlr all command, the state of the controller c2 is shown as disabled. To enable the host disk controller c2, which was disabled by vxdmpadm disable ctlr=c2, enter:

Executing listctlr all after this command shows the state of the controller c2 as enabled. The following examples outline the attributes supported by vxdmpadm listctlr.

The following command lists all paths controlled by the DMP node c2t1d0s2.

The following command obtains all paths through the host disk controller c2.

The following command displays the DMP node that controls the node c3t2d1s2.

The following command displays the DMP nodes connected to the enclosure enc0.

The following command assigns a new name, VMGRP_1, to the enclosure enc0.

To start the restore daemon with the default interval (300 seconds) and default policy (check_disabled), enter:

To specify the interval of polling as 400 seconds, enter:

The daemon checks the condition of the paths as specified by the policy attribute. To set the policy as check_all, enter:

The following command stops the DMP restore daemon; the restore daemon is automatically started at system startup time with default attributes.

To list the intervals of restore daemons running and the number of error daemons, enter:

Set the I/O policy to round-robin for the enclosure SENA0, and to balanced for arrays of type SENA:

Set c1t10d0 as a standby path:

Set c1t20d0 as an active path:

Set c2t20d0 as a preferred path with priority 2:

Reset the priority on path c2t20d0:

Display operating system device names instead of TPD node names for the enclosure EMC0:

NOTES

The terms disk array and enclosure are synonymous.

If only a Base VxVM license is installed, the vxdctl license command displays "DMP (single path enabled)". If either the Full VxVM license or an automatically generated license (such as that for the PHOTON array) is installed, the command displays "DMP (multipath enabled)".

FILES

/etc/vx/dmppolicy.info

Persistent file used to store DMP policy settings.

SEE ALSO

vxdctl (1M), vxintro (1M)

VERITAS Volume Manager Hardware Notes