suriadm - administer storage objects based on storage URIs
/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>
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 are defined in suri(5) manual page.
The following subcommands are supported:
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, and user.
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 charaters 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 occurence of "/dev" at the head of the path component if present is removed.
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.
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: create-size, file-permissions, mount-options, mountpoint-prefix, mapped-dev, target, lun, and luname.
Parses a URI and looks up an existing mapping between a storage URI and the object represented by a local system device paths. Default list of properties is displayed. Options –H and –o have the same meaning as for the parse subcommand. Option –p has the same meaning as for the map subcommand.
Creates the backing store for the storage URI then maps it. Option –p has the same meaning as for the map subcommand.
Unmaps the storage URI then destroys the backing store. Option –p has the same meaning as for the map subcommand.
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.
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.
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.
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.
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 3Example 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/c0t600144F0F4977D4000004F7EC8F00001d0s2Example 3 Mapping an iSCSI URI and Displaing 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/c6t49d0Example 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/c0t600144F0F4977D4000004F7EC8F00001d0s2Example 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.2100001d38089fb0Example 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-path /dev/dsk/c7t26d0s2 $ suriadm lookup-uri -t lu /dev/dsk/c7t26d0s2 lu:luname.naa.5000c5000288fa25 lu:initiator.naa.500605b000ae7010,target.naa.\ 5001636000019c11,naa.5000c5000288fa25Example 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/c7t26d0s2 lu:luname.naa.5000c5000288fa25 lu:initiator.naa.500605b000ae7010,target.naa.5001636000019c11,\ luname.naa.5000c5000288fa25 dev:dsk/c7t26d0s2Example 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-path \ lu:luname.naa.5000c5000288fa25 lu naa.5000c5000288fa25 /dev/dsk/c7t26d0s2Example 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.2000001d38089fb0Example 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" foundExample 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/nonexistent Failed to map "/dev/dsk/nonexistent" to URI: No such device: "/dev/dsk/nonexistent"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 diskExample 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/c0t0d0Example 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.0Example 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 ca012b66e90Example 17 Setting an Input Property on map
The following command shows how to set an input property on map.
$ suriadm map -p create-size=2G file://user1:group2@/export/file1
Command succeeded.
Command failed.
See attributes(5) for descriptions of the following attributes:
|
stmsboot(1M), svcadm(1M), attributes(5), suri(5), scsi_vhci(7D), libsuri(3LIB)
Small Computer System Interface-3 (SCSI-3)
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.