|
|
|
|
|
vxdmpadm - DMP subsystem administration
vxdmpadm [-a|-r|-u] cfgapm module_name
[attr1=value1 [attr2=value2] ...]
vxdmpadm [-c | -f] disable
{ctlr=ctlr_name | enclr=enclr_name portid=array_port_ID |
path=path_name | pwwn=port_WWN}
[enclosure=enclr_name] [type=enclr_type]
vxdmpadm enable
{ctlr=ctlr_name | enclr=enclr_name portid=array_port_ID |
path=path_name | pwwn=port_WWN}
[enclosure=enclr_name] [type=enclr_type]
vxdmpadm getattr {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}} {iopolicy | partitionsize | recoveryoption}
vxdmpadm getctlr {all | ctlr_name}
vxdmpadm getlungroup dmpnodename=DMP_node_name
vxdmpadm getdmpnode [enclosure=enclr_name | nodename=node_name]
vxdmpadm getportids {ctlr=ctlr_name | dmpnodename=DMP_node_name |
enclr=enclr_name | path=path_name}
vxdmpadm getsubpaths [ctlr=ctlr_name | dmpnodename=DMP_node_name |
enclr=enclr_name portid=array_port_ID |
pwwn=port_WWN | tpdnodename=TPD_node_name]
vxdmpadm gettpdnode [nodename=node_name]
vxdmpadm iostat show
{all | ctlr=ctlr_name | dmpnodename=DMP_node_name |
enclosure=enclr_name | pathname=path_name}
[interval=seconds [count=N]]
vxdmpadm iostat start [memory=size]
vxdmpadm listapm {all|module_name}
vxdmpadm listctlr {all\|ctlr=ctlr_name|
enclosure=enclr_name|type=enclr_type}
vxdmpadm listenclosure {all\|enclr_name}
vxdmpadm setattr arrayname array_name [attribute=value ...]
vxdmpadm setattr arraytype {A/A|A/P|...}} [attribute=value ...]
vxdmpadm setattr enclosure enclr_name [attribute=value ...]
vxdmpadm setattr enclosure enclr_name name=new_name
vxdmpadm setattr enclosure enclr_name tpdmode={native|pseudo}
vxdmpadm setattr {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}}
iopolicy={adaptive | balanced [partitionsize=block_shift]|
minimumq | priority | round-robin | singleactive}
[use_all_paths={yes|no}]
vxdmpadm setattr {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}}
recoveryoption=default
vxdmpadm setattr \ {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}}
recoveryoption=fixedretry retrycount=N
vxdmpadm setattr {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}}
recoveryoption=nothrottle
vxdmpadm setattr {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}}
recoveryoption=throttle {iotimeout=seconds | queuedepth=N}
vxdmpadm setattr \ {enclosure enclr_name | arrayname array_name |
arraytype {A/A|A/P|...}}
recoveryoption=timebound iotimeout=seconds
vxdmpadm setattr path path_name [attribute=value ...]
vxdmpadm setattr path path_name
pathtype={primary | secondary | nomanual|
standby | active | nopreferred | preferred [priority=N]}
vxdmpadm settune tunable=value
vxdmpadm start restore [attribute...]
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 an HBA controller, lists all the DMP nodes through a disk array, and enables or disables I/O through a HBA controller on the system.
vxdmpadm keywords select the action to perform, and attributes specify the objects on which the action is performed.
Configures the specified array policy module (APM) together with any required attribute-value pairs that specify its operation. 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:
Adds a vendor-supplied APM and configures it.
Removes an APM if it is not busy.
Refers DMP to the specified APM. This allows an older version of an APM to be used instead of the latest version.
Disables I/O on a specified path, or on all the paths that are conected to a specified HBA controller or array port. (An array port can be specified either by the name of the enclosure and the array port ID, or by the worldwide name (WWN) identifier of the array port.) This prevents DMP from issuing I/O requests through the specified controller, path or array port. 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:
Checks if the specified path is the last active path to the disk.
Forcibly disables the last active path to the disk.
The disable operation supports the attributes enclosure and type to specify an unambiguous path. (A specified enclosure type must be an enclosure category that supported by DMP.)
Enables I/O on a previously disabled path, or on all the paths that are connected to a specified HBA controller or array port. (An array port can be specified either by the name of the enclosure and the array port ID, or by the worldwide name (WWN) identifier of the array port.) This operation succeeds only if the controller, path or array port is accessible to the host and I/O can be performed on it. When connecting Active/Passive disk arrays, using enable results in a failback of I/O to the primary path.
The enable operation supports the attributes enclosure and type to specify an unambiguous path. (A specified enclosure type must be an enclosure category that supported by DMP.)
Displays the default and current settings of the iosize, partitionsize or recoveryoption attributes for the specified enclosure, array or array type.
Lists the logical and physical names of a specified controller, or of all the controllers present in the system.
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.
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.
Displays the array port ID and array port worldwide number (WWN) corresponding to the specified HBA controller, DMP node, enclosure or path.
Displays the paths controlled by the specified HBA controller, DMP node, array port or third-party driver (TPD) device. (An array port can be specified either by the name of the enclosure and the array port ID, or by the worldwide name (WWN) identifier of the array port.)
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.
Displays the third-party driver device that corresponds to the node specified as the argument to the nodename attribute.
Returns the values of the DMP tunable parameters. If the name of a tunable is not specified, a list of all the DMP tunables is displayed.
Displays a detailed information about attributes used with a particular keyword. For example, to obtain a usage message for listctlr, use the command:
Controls the gathering and display of I/O statistics using the following keywords:
Displays I/O statistics for all controllers, or for a specified controller, 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 and write operations, the number of kilobytes that are read or written, and the average time in milliseconds per kilobyte that is read or written.
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.
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.
Disables the gathering of I/O statistics.
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.
Lists the HBA controllers that are attached 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.
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.
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:
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 (for example, A/A for active/active and A/P for active/passive).
The policies that can be set are:
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.
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 block_shift of 0 selects the default value of 1024 blocks (1MB).
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.
This is the default policy for Active/Active (A/A) arrays.
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.) This policy is useful when the paths in a SAN have unequal performance, and you want to enforce load balancing manually.
Sets a simple round-robin policy for I/O.
This is the default policy for Active/Passive (A/P) and Asynchronous Active/Active (A/A-A) arrays.
I/O is channeled through the single active path.
The optional attribute use_all_paths controls whether the secondary paths in an Asymmetric Active/Active (A/A-A) array are used for scheduling I/O requests in addition to the primary paths. The default setting is no, which disallows the use of the secondary paths.
Specifies how DMP responds to failed I/O requests on a path. You can set recovery options for the paths to an enclosure (for example, HDS01), for the paths to all enclosures of a particular type (for example, HDS), or for the paths to all enclosures of a particular array type (for example, A/A for active/active and A/P for active/passive).
The recovery options that can be set are:
Corresponds to setting both fixedretry retrycount=30 and throttle queuedepth=20 on the paths.
DMP retries failed I/O requests on a path for the number of times specified by retrycount. The default value for retrycount is 30.
Turns off I/O throttling for a path.
Enables I/O throttling for a path.
If a timeout in seconds is specified using iotimeout, DMP continues to schedule I/O requests on a path on which an I/O failure has occurred for that many seconds. It will then prevent new I/O requests being scheduled on the path, and attempt to reschedule failed I/O requests on other paths. The default value for iotimeout is 10 seconds.
If a maximum number of queued I/O requests is specified using queuedepth, DMP continues to schedule I/O requests on a path on which an I/O failure has occurred until the queue limit is reached. It will then prevent new I/O requests being scheduled on the path, and attempt to reschedule failed I/O requests on other paths. The default value for queuedepth is 20.
Only one of iotimeout or queuedepth may be specified.
DMP retries failed I/O requests on a path for the time in seconds specified by iotimeout. The default value for iotimeout is 10 seconds.
The nothrottle and throttle options, and the fixedretry and timebound options are mutually exclusive for a given path.
The settings of iotimeout for throttle and for timebound are independent of each other.
The following attributes may be set for enclosures:
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.
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.
Note
This feature can only be used if the default naming scheme is set to use operating system-based naming, and the TPD-controlled enclosure does not contain fabric disks.
The following attributes may be set for paths:
Changes a standby path to active.
Restores the original primary or secondary attributes of a path.
Restores the normal priority of the path.
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.
Note
Marking a path as a preferred path does not change its I/O load balancing policy.
Assigns a primary path for an Active/Passive disk array.
Assigns a secondary path for an Active/Passive disk array.
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.
Sets the value of the specified DMP tunable parameter. This value takes precedence over any value that is set using the method provided by the operating system. The changed value is persistent across reboots of the system.
The following tunable parameters may be changed for DMP:
If set to on, the first open on a device that is performed by an array support library (ASL) is cached. This enhances the performance of device discovery by minimizing the overhead caused by subsequent opens by ASLs. If set to off, caching is not performed. The default setting is off.
The time limit for retrying an I/O request or before invoking I/O throttling in DMP. The default value is 300 seconds. This value may be overridden for individual paths by specifying a iotimeout value to the setattr recoveryoption=throttle or setattr recoveryoption=timebound operations.
The time in seconds for which a path must stay healthy. If a path's state changes back from enabled to disabled within this time period, DMP marks the path as intermittently failing, and does not re-enable the path for I/O until dmp_path_age seconds elapse. The default value of dmp_health_time is 60 seconds. A value of 0 prevents DMP from detecting intermittently failing paths.
The level of detail that is displayed for DMP console messages. The following level values are defined:
Display all DMP log messages that existed in releases before 5.0. This is the default setting.
Display level 1 messages plus messages that relate to I/O throttling, suspected paths, repeated path failures and DMP node migration.
Display level 1 and 2 messages plus messages that relate to I/O errors, I/O error analysis and path media errors.
Display level 1, 2 and 3 messages plus messages that relate to setting or changing attributes on a path.
The time for which an intermittently failing path needs to be monitored as healthy before DMP once again attempts to schedule I/O requests on it. The default value is 300 seconds. The minimum value is 1 second.
The default number of contiguous I/O blocks (expressed as the integer exponent of a power of 2; for example 11 represents 2048 blocks) that are sent along a DMP path to an Active/Active array before switching to the next available path. The default value of this parameter is set to 10 so that 1024 blocks (1MB) of contiguous I/O are sent over a DMP path before switching. This value may be overridden for individual paths by specifying a partitionsize value to the setattr iopolicy=balanced operation.
If DMP statistics gathering is enabled, set to 1 (default) to have the path restoration kernel thread probe idle LUNs, or to 0 to turn off this feature. (Idle LUNs are VM disks on which no I/O requests are scheduled.) The value of this tunable is only interpreted when DMP statistics gathering is enabled. Turning off statistics gathering also disables idle LUN probing.
The maximum number of queued I/O requests on a path during I/O throttling. The default value is 20. This value may be overridden for individual paths by specifying a queuedepth value to the setattr recoveryoption=throttle operation.
The number of retries to attempt on a path if there is an I/O error. The default number of retries is 5. This value may be overridden for individual paths by specifying a fixedretry value to the setattr recoveryoption=fixedretry operation.
Starts the kernel thread that implements DMP path restoration. This thread analyzes the condition of paths every interval seconds. The type of analysis depends on the specified policy:
The path restoration thread analyzes all paths in the system and revives the paths that are back online as well as disables the paths that are inaccessible.
The path restoration thread 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."
Note
This policy avoids inquiry commands on all healthy paths, and is less costly than check_all in cases where a large number of paths are available. This policy reduces to check_all if there are only two paths per DMP node.
The path restoration thread checks the condition of paths that were previously disabled due to hardware failures and revives them if they are back online.
The path restoration thread performs check_all once in a given number of cycles, and check_disabled in the remainder of the cycles.
Note
This policy may lead to periodic slowing down (due to check_all) if there are large number of paths available.
The default policy is check_disabled. To change the interval or policy, you must stop the path restoration thread and restart it with new attributes.
To set the policy to check_all, enter:
vxdmpadm start restore policy=check_all
If a controller disabled using the following command, the path restoration thread does not change the disabled state of the path through it.
To set the polling interval to 400 seconds, enter:
vxdmpadm start restore interval=400
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:
vxdmpadm start restore policy=check_periodic \
Note
A polling interval must be specified. This specifies how often (in seconds) the DMP path restoration thread checks the status of disabled paths.
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:
vxdmpadm start restore policy=check_alternate \
Displays the number of error handling threads that are running.
Displays the status of the automatic path restoration daemon, the interval of polling, and the policy used to check the condition of paths.
Stops the DMP path restoration thread. Automatic path failback stops if the path restoration thread stops.
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.
To display the usage message for all vxdmpadm commands, enter:
To list all attributes of all HBA 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:
vxdmpadm setattr enclosure ENC01 name=l1e1
To disable I/O through the HBA controller c2, enter:
If you then run the listctlr all command, the state of the controller c2 is shown as disabled. To enable the HBA 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.
vxdmpadm listctlr enclosure=enc0 type=ENC
vxdmpadm listctlr enclosure=enc0
The following command lists all paths controlled by the DMP node c2t1d0s2.
vxdmpadm getsubpaths dmpnodename=c2t1d0s2
The following command obtains all paths through the HBA controller c2.
The following command displays the DMP node that controls the node c3t2d1s2.
vxdmpadm getdmpnode nodename=c3t2d1s2
The following command displays the DMP nodes connected to the enclosure enc0.
vxdmpadm getdmpnode enclosure=enc0
The following command assigns a new name, VMGRP_1, to the enclosure enc0.
vxdmpadm setattr enclosure enc0 name=VMGRP_1
To start the path restoration thread with the default interval (300 seconds) and default policy (check_disabled), enter:
To specify the interval of polling as 400 seconds, enter:
vxdmpadm start restore interval=400
The daemon checks the condition of the paths as specified by the policy attribute. To set the policy as check_all, enter:
vxdmpadm start restore policy=check_all
The following command stops the DMP path restoration thread; the thread is automatically started at system startup time with default attributes.
To list the intervals of the path restoration thread and the number of error handling threads, enter:
Set the I/O policy to round-robin for the enclosure SENA0, and to balanced for arrays of type SENA:
vxdmpadm setattr enclosure SENA0 iopolicy=round-robin
vxdmpadm setattr arrayname SENA iopolicy=balanced partitionsize=2048
Set c1t10d0 as a standby path:
vxdmpadm setattr path c1t10d0 pathtype=standby
Set c1t20d0 as an active path:
vxdmpadm setattr path c1t20d0 pathtype=active
Set c2t20d0 as a preferred path with priority 2:
vxdmpadm setattr path c2t20d0 pathtype=preferred priority=2
Reset the priority on path c2t20d0:
vxdmpadm setattr path c2t20d0 pathtype=nopreferred
Display operating system device names instead of TPD node names for the enclosure EMC0:
vxdmpadm setattr enclosure EMC0 tpdmode=native
Enable I/O throttling with a timeout of 400 seconds for all paths to the enclosure enc1:
vxdmpadm setattr enclosure enc1 recoveryoption=throttle iotimeout=400
Turn off I/O throttling for all paths to the enclosure enc1:
vxdmpadm setattr enclosure enc1 recoveryoption=nothrottle
Enable time-bound I/O recovery with a timeout of 600 seconds for all paths to the enclosure enc1:
vxdmpadm setattr enclosure enc1 recoveryoption=timebound iotimeout=600
Display details of the array ports that are configured for the enclosure enc2:
vxdmpadm getportids enclr=enc2
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)".
Persistent file used to store DMP policy settings.