Manual Pages for UNIX Operating System command usage for man mpathadm

System Administration Commands                       mpathadm(1M)



NAME
     mpathadm - multipath discovery and administration

SYNOPSIS
     mpathadm subcommand direct-object [options] [operand]


DESCRIPTION
     The mpathadm  command  enables  multipathing  discovery  and
     management.  The mpathadm command is implemented as a set of
     subcommands, many with their own options, that are described
     in  the  section for that subcommand. Options not associated
     with a particular subcommand are  described  under  OPTIONS.
     The  mpathadm  subcommands operate on a direct-object. These
     are described in  this  section  for  each  subcommand.  The
     direct-objects, initiator-port, target-port, andlogical-unit
     in the subcommands are consistent with SCSI standard defini-
     tions.


     The mpathadm command  supports  the  following  subcommands,
     which are described in detail in subsections that follow.

     list        Display a list of  discovered  instances  for  a
                 given object.


     show        Display  information  about   a   given   object
                 instance.


     modify      Modify properties of an object.


     enable      Enable an object.


     disable     Disable an object.


     failover    Cause target port group failover for a  logical-
                 unit.


     override    Set a path to be used  over  other  paths  on  a
                 logical-unit.



     The mpathadm subcommands operate on a  direct-object.  These
     are described in this section for each subcommand.




SunOS 5.11           Last change: 4 May 2009                    1






System Administration Commands                       mpathadm(1M)



  list Subcommand
     The syntax for the list subcommand is:

       # mpathadm list direct-object [operands...]



     The list subcommand  displays  data  for  following  direct-
     objects:

     mpath-support [mpath-support-name, ...]

         List the multipathing support that can  be  administered
         by  this  CLI.  This  presents  itself  in the form of a
         library name registered through the MPAPI framework.  If
         no  mpath-support  name mpath-support-name is specified,
         all registered multipathing support  libraries  will  be
         displayed.


     initiator-port [initiator-port-name, ...]

         List the initiator ports that  are  discovered  on  this
         system.  If  no  initiator-port-name  is  specified, all
         discovered initiator ports are displayed.


     {logical-unit | lu} [options] [logical-unit-name, ...]

         List the information on multipath logical units.  If  no
         logical-unit-name  is specified, all discovered logical-
         units will be displayed.

         Options for list logical-unit are as follows:

         -n, --name name

             Return the logical unit name that is associated with
             the  given  name  string. This name can be extracted
             from the output of the mpathadm show lu command.


         -t, --target-port target-port-name

             Return the list of  logical  units  names  that  are
             associated with the given target-port-name.



  show Subcommand
     The syntax for the show subcommand is:




SunOS 5.11           Last change: 4 May 2009                    2






System Administration Commands                       mpathadm(1M)



       # mpathadm show direct-object [operands...]



     The show subcommand displays detailed information  for  fol-
     lowing the direct-objects:

     mpath-support [mpath-support-name, ...]

         Show  the  detailed  information  on  the  given  mpath-
         support-name  if  the  name  exists. If the given mpath-
         support-name supports only a limited set of device  pro-
         ducts,  the  list  of  device products will be listed as
         part of the output.


     initiator-port initiator-port-name[,initiator-port-name,
     ...]

         Show the detailed information for the  given  initiator-
         port-name.


     {logical-unit | lu} [logical-unit-name, ...]

         Display the detailed information  on  multipath  logical
         unit(s),  including  path and target port group informa-
         tion. Note that the name property in  the  logical  unit
         information  represents  the  identifier  for  this LUN,
         derived from the hardware, and used by this  system.  If
         the name is derived from SCSI Inquiry Vital Product Data
         (VPD) page 83h, the name  type  property  represents  an
         associated  identifier  type  defined  by the SCSI stan-
         dards.


  modify Subcommand
     The syntax for the modify subcommand is:

       # mpathadm modify direct-object [options] [operands...]



     The modify subcommand modifies characteristics of  the  fol-
     lowing direct-objects:

     mpath-support [options] mpath-support-name, ...

         Configuration management of an mpath-support. Options to
         modify mpath-support are as follows:





SunOS 5.11           Last change: 4 May 2009                    3






System Administration Commands                       mpathadm(1M)



         -a, --autofailback on | off

             Set autofailback. Applicable only when mpath-support
             provides auto failback support.


         -p, --autoprobe on | off

             Set autoprobing. Applicable only when  mpath-support
             provides auto probing support.


         -b, --loadbalance loadbalance-type

             Change the default load balance type.  The  loadbal-
             ance  type  is  one of the supported types listed in
             the show mpath-support output.



     {logical-unit | lu} [options] logical-unit-name, ...

         Configuration management of a logical unit.  Options  to
         modify logical-unit are as follows:

         -a, --autofailback on | off

             Set autofailback. Applicable only when mpath-support
             provides auto failback support


         -p, --autoprobe on | off

             Set autoprobing. Applicable only when  mpath-support
             provides auto probing support.


         -b, --loadbalance loadbalance-type

             Set load balance type for the logical unit. Applica-
             ble  only  when  load  balance configuration is sup-
             ported at the logical unit level.



  enable Subcommand
     The syntax for the enable subcommand is:

       # mpathadm disable [options]






SunOS 5.11           Last change: 4 May 2009                    4






System Administration Commands                       mpathadm(1M)



     The enable subcommand supports the following  direct-objects
     to be enabled:

     path -i initiator-port-name -t target-port-name
     -l logical-unit-name

         The path that consists of the specified initiator  port,
         target port, and logical unit will be enabled.


  disable Subcommand
     The syntax for the disable subcommand is:

       # mpathadm disable [options]



     The disable subcommand supports the following direct-objects
     to be disabled:

     path -i initiator-port-name -t target-port-name
     -l logical-unit-name

         The path that consists of the specified initiator  port,
         target port, and logical unit will be disabled.


  failover Subcommand
     The syntax for the failover subcommand is:

       # mpathadm failover direct-object [operand]



     The failover subcommand supports failover for the  following
     direct-objects:

     {logical-unit | lu} logical-unit-name

         The target port  group  will  failover  when  the  given
         logical-unit  is  asymmetric and supports explicit state
         change. The currently active target port group  will  be
         changed to the standby state and the standby target port
         group will be active.


  override Subcommand
     The syntax for the override subcommand is:

       # mpathadm override [options]





SunOS 5.11           Last change: 4 May 2009                    5






System Administration Commands                       mpathadm(1M)



     The override subcommand controls whether or not the  follow-
     ing direct-objects override another:

     path {-i initiator-port-name -t target-port-name | -c}
     -l logical-unit-name

         Cause a path that consists of  the  specified  initiator
         port,  target  port,  and logical unit to override other
         paths on the logical unit. Once a path  overrides  other
         paths,  the mpath-support uses only that path regardless
         of any other path selection configuration. The -c option
         cancels  the  setting.  The  path  that  consists of the
         specified initiator port, target port, and logical  unit
         will be disabled.

         Options for override path are as follows:

         -i, --initiator-port initiator-port-name

             Represent the initiator  port  element  of  a  path.
             Options -t and -l must also be included.


         -t, --target-port target-port-name

             Represent the target port element of a path. Options
             -i and -l must also be included.


         -l, --logical-unit logical-unit

             Represent  the  logical  unit  element  of  a  path.
             Options -i and -t must also be included.


         -c, --cancel

             Cancels overriding setting  for  the  given  logical
             unit. Option -l must also be included.



OPTIONS
     The following options are supported:

     -V, --version    Display the version information.


     -?, --help       Display context help. Can be used following
                      an mpathadm command with no arguments, fol-
                      lowing a subcommand, or following a subcom-
                      mand  direct-object  combination.  Responds



SunOS 5.11           Last change: 4 May 2009                    6






System Administration Commands                       mpathadm(1M)



                      with help information appropriate for  your
                      entry. For example, if you enter:

                        # mpathadm add mpath-support-help


                      ... mpathadm responds with a display of the
                      options  available  for that combination of
                      subcommand and direct-object.


EXAMPLES
     Example 1 Obtaining a List of Multipathing Support


     The following command uses the list subcommand to  list  all
     currently registered mpath-support libraries.


       # mpathadm list mpath-support
       mpath-support: libmpscsi_vhci.so



     Example 2 Displaying the Properties  of  a  Particular  Mul-
     tipathing Support


     The following command uses the show  subcommand  to  display
     the  properties  for  a  currently  registered mpath-support
     library.


       # mpathadm show mpath-support libmpscsi_vhci.so
       mpath-support: libmpscsi_vhci.so
              Vendor:  Sun Microsystems
              Driver Name:  scsi_vhci
              Default Load Balance:  round-robin
              Supported Load Balance Types:
                     round-robin
                  logical-block
       Allows To Activate Target Port Group Access:  yes
       Allows Path Override:  no
       Supported Auto Failback Config:     1
       Auto Failback: on
       Failback Polling Rate (current/max):  0/0
       Supported Auto Probing Config:     0
       Auto Probing:  NA
       Probing Polling Rate (current/max):  NA/NA
       Supported Devices:
              Vendor:  SUN
              Product:  T300



SunOS 5.11           Last change: 4 May 2009                    7






System Administration Commands                       mpathadm(1M)



              Revision:
              Supported Load Balance Types:
                     round-robin
              Vendor:  SUN
              Product:  T4
              Revision:
              Supported Load Balance Types:
                     round-robin



     Example 3 Obtaining a List  of  Initiator  Ports  Discovered
     Through the mpath-support Libraries


     The following command uses the list  initiator-port  subcom-
     mand  to display a list of initiator ports discovered by the
     currently registered mpath-support libraries.


       # mpathadm list initiator-port
       Initiator-Port: iqn.1986-03.com.sun:01:080020b7ac2b.437a3b3e,4000002a0000
       Initiator-Port: 2000000173018713
       Initiator-Port: 2000000173818713



     Example 4 Displaying the Properties of a Particular  Initia-
     tor Port


     The following command uses the show  initiator-port  subcom-
     mand  to  display  the  properties of a particular initiator
     port discovered using the list initiator-port subcommand  in
     an example above.


       # mpathadm show initiator-port 2000000173018713
       initiator-port:      2000000173018713
               Transport Type:   Fibre Channel
               OS device File:   devices/pci@1f,4000/pci@2/SUNW,qlca@5/fp@0,0:fc



     Example 5 Displaying the Properties of a Particular  Logical
     Unit


     The following command uses the show logical-unit  subcommand
     to  display  the  properties  of  the  logical unit with the
     specified name.




SunOS 5.11           Last change: 4 May 2009                    8






System Administration Commands                       mpathadm(1M)



       # mpathadm show lu /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2
       Logical Unit: /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2
                   mpath-support libmpscsi_vhci.so
                   Vendor: SUN
                   Product: T4
                   Revision: 0301
            Name Type: SCSI Inquiry VPD Page 83 type 3
            Name: 60003ba27d2120004204ac2b000dab00
            Asymmetric: yes
            Current Load Balance: round-robin
            Logical Unit Group ID: NA
            Aauto Failback: on
            Auto Probing: NA

       Paths:
            Initiator Port Name: 2000000173818713
            Target Port Name: 20030003ba27d212
            Override Path: NA
            Path State: OK
            Disabled: no

            Initiator Port Name: 2000000173018713
            Target Port Name: 20030003ba27d095
            Override Path: NA
            Path State: OK
            Disabled: no

       Target Port Group:
            ID: 2
            Explicit Failover: yes
            Access State: standby
            Target Ports:
                      Name: 20030003ba27d212
                    Relative ID: 0

            ID: 5
            Explicit Failover: yes
            Access State: active
            Target Ports
                      Name: 20030003ba27d095
                    Relative ID: 0



     Example 6 Enabling a Path


     The following command uses the  enable  path  subcommand  to
     enable  the  path  with the specified initiator port, target
     port, and logical unit.





SunOS 5.11           Last change: 4 May 2009                    9






System Administration Commands                       mpathadm(1M)



       # mpathadm enable path -i 2000000173018713 -t 20030003ba27d095    \
       -l /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2



     Example 7 Modifying mpath-support To Turn On autofailback

       # mpathadm modify mpath-support -a on libmpscsi_vhci.so



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     _______________________________________________________________
   |        ATTRIBUTE TYPE       |          ATTRIBUTE VALUE       |
   | ____________________________|________________________________|_
   |  Availability               |  system/library/storage/libmpapi|
   | ____________________________|________________________________|_
   |                             |  system/library/storage/libmpapi|
   |                             |  (exec_attr(4) entry)          |
   |_____________________________|________________________________|
   | Interface Stability         | Committed                      |
   |_____________________________|________________________________|


SEE ALSO
     stmsboot(1M), libMPAPI(3LIB), exec_attr(4), attributes(5)
























SunOS 5.11           Last change: 4 May 2009                   10