ppath

Description:

ppath is a scriptable tool to parse multipath devices presented by the native Linux multipath driver.

The multipath command that is part of the native Linux multipath-tools package is not the most scriptable tool in the world. ppath is a command that will return the same information, but in a awk and grep-able format that is conducive to scripting.

hbastat uses code from ppath to display / aggregate stats by multipath device.

Notes:

The package also includes some sample scripts that I have used in our environment that may be of some help when inserting ppath into your own scripts. It should be noted that the sample scripts I have included make some assumptions about the environment that it was written in and may not reflect the situation of your environment (IE: Our environment always has active/active paths, we do not use active/passive). ppath should work in any environment where multipathd is running.

It is also the desire of the author of this package that other people wishing to write similar code are not forced to resort to such brute force methods to write against the libdevmapper library. The libdevmapper.h file has some comments but tends to be a bit short on really meaningful commentary on how to write against it. As a result, it is virtually essential that a developer read kernel source (for the ioctl() call) to write this code because it is virtually impossible to do it based upon the comments in libdevmapper.h alone.

It is my opinion that someone should write a HOWTO on the libdevmapper library and some of the calls (ie: dm_task_create(), dm_task_run(), dm_task_destroy()) and how to make simple requests for info from the multipathd daemon. For example a discussion on the need for a call to dm_task_no_open_count() might be of value.

Let it be known: If I get as much as one request for this documentation I will produce a Mini-HOWTO on this subject, at a minimum. Until then, you can rely upon the sample code here or just use the utility as is.

Having spent some time in the Solaris and AIX community I have grown accustomed to having proper documentation of the APIs in the header files. The common refrain from the Linux community seems to be "Read the source!". This is hardly a valid response from vendors like Red Hat and SuSE that put the title "Enterprise" on their products.

The Distribution:

parsepath-0_15_2.tar.gz

This code is released under the GPL.

Build by uncompressing / taring the package and running "make". It will build on RHEL4 and RHEL5 with the multipath tools installed (including the library etc...). In short, it should run on any system that is currently running multipath and multipathd.

The 0.15.2 version includes better code documentation and fixes a bug when running "ppath -smd". In this case ppath was not getting extended info for disks from /sys/block (because the -m (major:minor) flag was used), and then was requiring that info because -s (size) comes from /sys/block/<DEVICE>/size.

ppath -h

# ./ppath -h
ppath - ParsePath - Create a parsable list of multipath devices.
 Version: 0.15.0
 Usage:
   ppath <options> <device>
 Options:
   -a  Show all devices (multipath and linear). Default = just multipath.
   -c  Count paths to device.
   -d  Print path (sub) devices.
   -f  Display the dm-X device created for this device.
   -h  Show help / usage info and exit.
   -l  Print H:C:S:L instead of (sub) device names.
   -m  Print major and minor numbers.
   -s  Print size of device (AutoSized).
   -t  Print pathing type (SP, AA, or AP).
   -u  Print uuid.
   -v  Show version information and exit.
   -x  Print device type (multipath or linear (LVM)).
 Notes:
  - Switches can be in any order but output is always in the same order.
    UUID DT M:M PT PC SZ DM Devices
     where:
      UUID = Unique ID of device. (-u)
      DT = Device type (multipath or linear) (-x)
      M:M = Major and Minor of multipath device. (-m)
      PT = Path type (AA=Active/Active, AP=Active/Passive, SP=Single path) (-t)
      PC = Path count (number of active or passive paths to device). (-c)
      SZ = Size of device. (-s)
      DM = dm-X device. (-f)
      Devices = block/sub-devices of multipath device. (-d)
                (-m and -l changes the output of "Devices")
  - A single (optional) device can be specified on the command line. If
    specified only that device will show in output. If not specified then all
    devices with names will be listed (one per line).
  - Undocumented/nonstandard options viewable with --HELP.