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(7) 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, file-permissions, group, hostname, initiator, is-slice, lun, luname, mapped-dev, mapped-devs, mount-options, mountpoint-prefix, mountpoint, path, port, removable, 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 iSCSI and logical unit URIs, all alphabetical characters in the URI are converted to lowercase characters.
Additionally for iSCSI URIs, the default iSCSI port number 3260 is removed.
For device URIs, all leading forward slashes that follow the URI type name and the occurrence of /dev at the head of the path component is removed.
For NFS URIs, a hostname is converted to lowercase and leading zeros are removed from numeric user/group IDs.
For file URIs, a hostname is removed and leading zeros are removed from numeric user/group IDs.
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 dev and lu 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, mountpoint-prefix, and removable.
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.
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.
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, iqn, and eui. Fibre-channel target ports are always NAA based names. iSCSI target ports are always IQN or EUI-64 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/c0t600144F0F4977D4000004F7EC8F00001d0Example 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/c0t600144F0F4977D4000004F7EC8F00001d0Example 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-devs /dev/dsk/c7t26d0 $ suriadm lookup-uri -t lu /dev/dsk/c7t26d0 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/c7t26d0 lu:luname.naa.5000c5000288fa25 lu:initiator.naa.500605b000ae7010,target.naa.5001636000019c11,\ luname.naa.5000c5000288fa25 dev:dsk/c7t26d0Example 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/c7t26d0Example 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/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 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.500000e012942880
$ suriadm lookup-uri -p lun=0 -p \ target=iqn.1986-03.com.sun:02:9548ddf8-e7ac335a760f iscsi://10.0.0.1/luname.naa.600144f0a5320b470000527d66740009 iscsi://10.0.0.1/target.iqn.1986-03.com.sun:02:9548ddf8-e7ac335a760f,lun.0
$ suriadm lookup-uri -p target=eui.bbbbbbbbbbff0011 -p lun=1 iscsi://10.0.0.1/luname.naa.600144f0a76c607200005bcf451b0002 iscsi://10.0.0.1/target.eui.bbbbbbbbbbff0011,lun.1Example 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.5000cca012b66e90Example 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/file1Example 18 Device based look-up of all iSCSI URIs over all available targets
$ suriadm lookup-uri -t iscsi /dev/dsk/c0t600144F0A76C607200005BCF451B0002d0 iscsi://10.10.10.10/luname.naa.600144f0a76c607200005bcf451b0002 iscsi://10.10.10.10/target.eui.bbbbbbbbbbff0011,lun.1 iscsi://10.10.10.10/target.iqn.1986-03.com.sun:02:60ae9e51-dbc79738b319,lun.1
Command succeeded.
Command failed.
See attributes(7) for descriptions of the following attributes:
|
attributes(7), libsuri(3LIB), scsi_vhci(4D), stmsboot(8), suri(7), svcadm(8)
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.
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.