Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

suriadm(8)

Name

suriadm - administer storage objects based on storage URIs

Synopsis

/usr/sbin/suriadm command [options] [operands]
/usr/sbin/suriadm parse [-H] [-o <p>,<p>,...] <URI>
/usr/sbin/suriadm normalize <URI>
/usr/sbin/suriadm map [-H] [-o <p>,<p>,...] [-p <prop>=<value>] <URI>
/usr/sbin/suriadm lookup-mapping [-H] [-o <p>,<p>,...] [-p <prop>=<value>] <URI>
/usr/sbin/suriadm unmap [-p <prop>=<value>] <URI>
/usr/sbin/suriadm create [-H] [-o <p>,<p>,...] [-p <prop>=<value>] <URI>
/usr/sbin/suriadm destroy [-p <prop>=<value>] <URI>
/usr/sbin/suriadm lookup-uri [-t <uri-type>] <device-path>
/usr/sbin/suriadm lookup-uri [-t <uri-type>] 
    -p mapped-dev=<device-path>
/usr/sbin/suriadm lookup-uri [-t <uri-type>] -p luname=<luname>
/usr/sbin/suriadm lookup-uri [-t <uri-type>] -p target=<target> 
    -p lun=<LUN>

Description

The suriadm command line administration tool allows system users to manage storage objects via storage URIs. The command allows to parse, map, unmap, query the state of mappings and look up storage URIs.

Supported Storage URIs

Supported storage URIs are defined in suri(7) manual page.

Sub Commands

The following subcommands are supported:

parse [–H] [–o <p>,<p>,...] <URI>

Parses a given URI and displays a default list of properties. With –H, a header is omitted from the output. With –o, only properties from the list provided are displayed. The –o option implies output on one line, with property values separated by tabs, meant to be further processed by another command.

Allowed property names for the –o option are: create-size, create-supported, group, file-permissions, hostname, initiator, luname, lun, mapped-dev, mapped-devs, mount-options, mountpoint, mountpoint-prefix, path, port, target, teardown-supported, uri, uri-type, user, and is-slice.

normalize <URI>

Parses and normalizes a storage URI string based on normalization specifications for the URI type. Displays the normalized URI and does not accept any options.

For an iSCSI or a logical unit URI this subcommand converts all the alphabetical characters in the URI to lower case characters.

For iSCSI URIs this subcommand also removes the presence of the default iSCSI port "3260" in the URI.

For device URI type, all leading forward slashes that follow the URI type name and the occurrence of "/dev" at the head of the path component if present is removed.

map [–H] [–o p,p,...] [–p <prop>=<value>] URI

Parses a storage URI, configures the storage subsystem if necessary to instantiate all devices corresponding to the URI provided, and displays device paths. If devices are already instantiated, the map operation only looks up device paths.

A storage object being mapped must exist beforehand, else the operation fails. See the "create" subcommand on how to create a storage object. For more information on what storage URI types support the create operation, see the suri(7) man page.

For an iSCSI URI, this subcommand will add a send-targets discovery address(es) a hostname resolves to if a URI authority section is present.

For logical unit and dev URI types, this subcommand has no effect on system configuration. Options –H and –o have the same meaning as the parse subcommand. The property mapped-devs shows all the device paths corresponding to the URI provided, and the property mapped-dev shows only the first device path of mapped-devs.

Allowed input property names for the –p option are: mount-options and mountpoint-prefix.

lookup-mapping [–H] [–o <p>,<p>,...]
[–p <prop>=<value>] <URI>

Parses a URI and looks up for existing mappings between a storage URI and the objects represented by local system device paths. Default list of properties does not display any properties or accept any options. Options –H and –o have the same meaning as for the parse subcommand. Option –p has the same meaning as for the map subcommand.

create [–H] [–o <p>,<p>,...] [–p <prop>=<value>] <URI>

Creates the backing store for the storage URI then maps it. Option –p has the same meaning as for the map subcommand.

Allowed input property names for the –p option are: create-size and file-permissions.

destroy [–p <prop>=<value>] <URI>

Unmaps the storage URI then destroys the backing store. Option –p has the same meaning as for the map subcommand.

unmap [–p <prop>=<value>] <URI>

Parses and unmaps an object presumably mapped before. Option –p has the same meaning as for the map subcommand.

For an iSCSI URI, this subcommand removes discovery addresses to which a hostname from a URI authority section resolves, if present.

For logical unit and dev URI types, this subcommand has no effect on system configuration.

lookup-uri [–t <uri-type>] <device-path>
lookup-uri [–t <uri-type>] –p mapped-dev=<device-path>

Looks up and displays URIs based on a local system device path. Allowed URI types for –t are dev, lu, and iscsi. If the –t option is not specified, the output consists of all URIs that match the device path for any URI type. Using the property option "–p" is optional.

lookup-uri [–t <uri-type>] –p luname=<luname>

Looks up and displays LU and iSCSI URIs based on a logical unit name. Allowed URI types for –t are lu and iscsi. If the –t option is not specified the output consists of all URIs that identify the logical unit matched by a given logical unit name.

If the logical unit name does not have an implicit ID type (as in IQN based name) the ID type must be explicitly stated. See EXAMPLES.

lookup-uri [–t <uri-type>] –p target=<target> –p lun=<LUN>

Looks up and displays URIs based on a target port and LUN. Allowed URI types for –t are lu and iscsi. If the –t option is not specified, the output consists of all URIs that identify the logical unit matched by the specified target and LUN. In general only one URI type will be present in the output even without the –t option.

The target must consists of an identifier type and the identifier, separated by a period. Supported ID types are "naa" and "iqn". Fibre-channel target ports are always NAA based names. iSCSI target ports are always IQN based names. See EXAMPLES.

LUN is a decimal number.

Examples

Example 1 Parsing a URI and Displaying Properties

The following command parses and iSCSI URI and displays a default list of properties.

$ suriadm parse iscsi://10.0.0.1:3260/luname.naa.0123456789abcdef
PROPERTY           VALUE
uri-type           iscsi
hostname           10.0.0.1
port               3260
luname             naa.0123456789abcdef
target             -
lun                -
$ suriadm parse iscsi://10.0.0.1:3260/target.iqn.1990-12.com.sun\ 
:cng-002,lun.3 
PROPERTY           VALUE 
uri-type           iscsi 
hostname           10.0.0.1 
port               3260 
luname             - 
target            iqn.1990-12.com.sun:cng-002 
lun               3
Example 2 Mapping an iSCSI URI and Displaying a Device Name

The following command maps an iSCSI URI and displays the mapped local system device names. The effect of this command is to automatically add a send-targets discovery address if one is not already present.

$ suriadm map iscsi://127.0.0.1/luname.naa.\
600144F0F4977D4000004F7EC8F00001
PROPERTY        VALUE
mapped-devs      /dev/dsk/c0t600144F0F4977D4000004F7EC8F00001d0
Example 3 Mapping an iSCSI URI and Displaying Device Names when the device is accessible by means of multiple paths.

The following command displays all the device names, when there is multiple device paths corresponding to a URI.

$suriadm map iscsi://localhost/luname.naa.\
600144F0F42B0A00000053BC37270001
PROPERTY        VALUE
mapped-devs     /dev/dsk/c6t46d0
                /dev/dsk/c6t45d0
                /dev/dsk/c6t48d0
                /dev/dsk/c6t47d0
                /dev/dsk/c6t49d0
Example 4 Looking Up Mapping

The following command looks up an existing iSCSI mapping.

$ suriadm lookup-mapping iscsi://127.0.0.1/\
luname.naa.600144F0F4977D4000004F7EC8F00001
PROPERTY        VALUE
mapped-devs     /dev/dsk/c0t600144F0F4977D4000004F7EC8F00001d0
Example 5 Parsing a Logical Unit URI

The following command parses an initiator/target/luname logical unit URI.

$ suriadm parse lu:initiator.naa.2101001b32ae7ab5,\
target.naa.2100001d38089fb0,luname.naa.500000e012942880
PROPERTY        VALUE
uri-type        lu
luname          naa.500000e012942880
initiator       naa.2101001b32ae7ab5
target          naa.2100001d38089fb0
Example 6 Mapping a Logical Unit URI, Looking Up URIs

The following command sequence maps a logical unit URI, then looks up the matched logical unit URIs based on a found device name.

$ suriadm map lu:luname.naa.5000c5000288fa25
PROPERTY        VALUE
mapped-devs     /dev/dsk/c7t26d0

$ suriadm lookup-uri -t lu /dev/dsk/c7t26d0
lu:luname.naa.5000c5000288fa25
lu:initiator.naa.500605b000ae7010,target.naa.\
5001636000019c11,naa.5000c5000288fa25
Example 7 Looking Up Matching URIs

The following command looks up all URIs that match a specific device name without specifying a URI type.

$ suriadm lookup-uri /dev/dsk/c7t26d0
lu:luname.naa.5000c5000288fa25
lu:initiator.naa.500605b000ae7010,target.naa.5001636000019c11,\
luname.naa.5000c5000288fa25
dev:dsk/c7t26d0
Example 8 Parsing a URI, Displaying Selected Properties

The following command parses a URI and displays only selected properties, all on the same line, separated by tabs, and with no header.

$ suriadm map -Ho uri-type,luname,mapped-dev \
lu:luname.naa.5000c5000288fa25
lu      naa.5000c5000288fa25    /dev/dsk/c7t26d0
Example 9 Looking Up Logical Unit URIs

The following command looks up logical unit URIs for a device accessible by means of multiple paths.

$ suriadm lookup-uri -t lu /dev/dsk/c11t2000001D38089FB0d0
lu:luname.naa.2000001d38089fb0
lu:initiator.naa.2101001b32ae7ab5,target.naa.2100001d38089fb0,luname.\
naa.2000001d38089fb0
lu:initiator.naa.2100001b328e7ab5,target.naa.2200001d38089fb0,luname.\
naa.2000001d38089fb0
Example 10 Trying to Parse Incorrect URI

The following command attempts to parse a syntactically incorrect URI.

$ suriadm parse lu:luname.naa.0123456789
Failed to parse URI "lu:luname.naa.0123456789": GUID part
in "luname.naa.GUID" not 16 or 32 character hexadecimal
number: "0123456789"
Example 11 Trying to Map LU URI with Inaccessible LU

The following command attempts to map an LU URI with a logical unit name not accessible from the system.

$ suriadm map lu:luname.naa.0123456789abcdef
Failed to map URI "lu:luname.naa.0123456789abcdef": No such
logical unit "naa.0123456789abcdef" found
Example 12 Looking Up URI for Non-Existent Device Path

The following command attempts to lookup a URI for a non-existent device path.

$ suriadm lookup-uri /dev/dsk/non-existent
Failed to map "/dev/dsk/non-existent" to URI: No such device:
"/dev/dsk/non-existent"
Example 13 Looking Up dev URI

The following command sequence illustrates the fact that the dev URI is the only URI type that accepts a disk pathname that specifies a slice.

$ suriadm lookup-uri -t dev /dev/dsk/c0t500000E012942880d0s0
dev:dsk/c0t500000E012942880d0s0

$ suriadm lookup-uri -t iscsi \
  /dev/dsk/c0t600144F03E0A0C0000004FAB3B660001d0s0
Failed to look up "iscsi" URI for device: \
  "/dev/dsk/c0t600144F03E0A0C0000004FAB3B660001d0s0": \
  Device path with slice does not represent entire disk
Example 14 Normalizing a URI

The following command normalizes an iSCSI URI.

$ suriadm normalize
  iscsi://10.0.0.1:3260/luname.naa.0123456789ABCDEF 
  iscsi://10.0.0.1/luname.naa.0123456789abcdef

The following invocations normalize dev URIs.

$ suriadm normalize dev:/dev/dsk/c0t0d0
dev:dsk/c0t0d0
$ suriadm normalize dev:///dev/dsk/c0t0d0
dev:dsk/c0t0d0
Example 15 Getting URIs Based on Target and LUN

The following command shows how to get URIs based on target and LUN.

$ suriadm lookup-uri -p target=naa.2100001d38089fb0 -p lun=0
lu:luname.naa.500000e012942880 
lu:initiator.naa.2101001b32ae7ab5,target.naa.2100001d38089fb0,luname.naa.50000 
0e012942880
$ suriadm lookup-uri -p lun=0 -p \
target=iqn.1986-03.com.sun:02:9548ddf8-dc44-63a1-b773-e7ac335a760f 
iscsi://10.0.0.1/luname.naa.600144f0a5320b470000527d66740009 
iscsi://10.0.0.1/target.iqn.1986-03.com.sun:02:9548ddf8-dc44-63a1-b773-e7ac335 
a760f,lun.0
Example 16 Getting LU URIs Based on a Logical Unit Name

The following command shows how to get LU URIs based on a logical unit name:

$ suriadm lookup-uri -t lu -p luname=naa.5000cca012b66e90
lu:luname.naa.5000cca012b66e90
lu:initiator.naa.5080020000fafcf8,target.naa.5000cca012b66e91,luname.naa.5000c
ca012b66e90
Example 17 Setting an Input Property on map

The following command shows how to set an input property on map.

$ suriadm create -p create-size=2G file://user1:group2@/export/file1

Exit Status

0

Command succeeded.

>0

Command failed.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library/storage/suri
Interface Stability
Committed

See Also

libsuri(3LIB), scsi_vhci(4D), attributes(7), suri(7), stmsboot(8), svcadm(8)

Small Computer System Interface-3 (SCSI-3)

Notes

When an iSCSI URI is used, the svc:/network/iscsi/initiator service must be enabled, unless a parse operation is being performed. If this service is disabled and an iSCSI URI is being processed, the iSCSI initiator service will be automatically enabled temporarily. The service is never disabled through the suriadm command.

When a /dev/chassis form of a dev URI is used, the svc:/system/devchassis:daemon service must be enabled, unless a parse operation is being performed. If the service is disabled and a /dev/chassis form of a dev URI is being processed, the service will be automatically enabled temporarily. The service is never disabled through the suriadm command.