suri - storage URIs
Storage URIs uniquely identify storage objects across different nodes.
Aside from the dev URI which may reference individual slices, all other URI types always represent an entire disk. Such disk is represented as a device path without a slice, for example, /dev/dsk/c0t0d0 or /dev/dsk/c0t5000c5000288fa25d0. Such a device path without a slice may not exist for all disks on the system and the consumer of storage URIs must be prepared for that. Note that zpool(8) always accept cXtXdX device paths for existing block devices even for non-existent /dev/dsk/cXtXdX links.
All storage URI types do not support creating storage objects. See below, for each type description. For URI types that support storage object creation, use suriadm create subcommand with the –p create-size option. Storage objects can be created manually as well. It is not supported for storage objects to get created as part of the mapping process.
The following Storage URIs are supported.
dev:<local-path-under-/dev> dev://<absolute-path-to-device> dev:<absolute-path-to-device>
Examples:
dev:dsk/c0t0d0s0 dev:///dev/dsk/c0t0d0s0 dev:/dev/dsk/c0t0d0s0 dev:chassis/SYS/HD1/disk
The device URI specifies an object in the form of an existing device. All forms of the dev URI are functionally equivalent. The dev:dsk format with no authority section and an implied /dev/ path prefix is usually preferred. The path must always identify a device within the /dev name space.
Components of the device path may only include characters from the POSIX.1-2008 Portable Filename Character Set, 0-9a-zA-Z._-.
The dev URI type does not support the create operation.
lu:luname.naa.<ID> lu:luname.eui.<ID> lu:initiator.naa.<ID>,target.naa.<ID>,luname.naa.<ID> lu:initiator.naa.<ID>,target.naa.<ID>,luname.eui.<ID>
Examples:
lu:luname.naa.5000c5000288fa25 lu:luname.eui.0021280001cf80f6 lu:initiator.naa.2100001d38089fb0,target.naa.2100001d38089fb0,luname.naa.5000c5000288fa25 lu:initiator.naa.2100001d38089fb0,target.naa.2100001d38089fb0,luname.eui.0021280001cf80f6
Logical unit URI specifies a logical unit attached via Fibre Channel or serial-attached SCSI. In the luname-only URI form, the ID describes a logical unit name. In the initiator, target, luname form, an initiator specifies an initiator port and a target specifies a target port, and together they specify a path to the logical unit whose name must match the URI's luname part as in the luname-only form.
IDs are represented by using the SCSI-3 VPD page (0x83) logical unit names formatted as hexadecimal numbers (64/128 bits). IDs are case insensitive. Only logical unit names based on NAA or EUI-64 identifiers are supported. See NOTES for information on identifier formats.
In general it is recommended using multipathing in conjunction with luname-only URIs. If multipathing is disabled and a luname-only URI is used, a random path to the specified logical unit will be chosen. To avoid this random path assignment an initiator, target, luname URI form can be used to select a specific path to a logical unit. If multipathing is enabled and an initiator, target, luname URI form is used then the multipathing framework controls which paths are used to access the logical unit and the URI is only used to identify the unit, not the access path.
If an initiator or/and a target IDs are not matched but the logical unit is found based on a logical unit name, the unit will be accessed via an alternate path.
The lu URI type does not support the create operation.
iscsi:///luname.naa.<ID> iscsi:///luname.eui.<ID> iscsi://<host>[:<port>]/luname.naa.<ID> iscsi://<host>[:<port>]/luname.eui.<ID> iscsi:///target.<IQN>,lun.<LUN> iscsi:///target.eui.<ID>,lun.<LUN> iscsi://<host>[:<port>]/target.<IQN>,lun.<LUN> iscsi://<host>[:<port>]/target.eui.<ID>,lun.<LUN>
IQN stands for iSCSI Qualified Name, which has the form iqn.YYYY-MM.<org-naming-auth>[:<string-defined-by-org>]. IQN format is defined and elaborated with examples in RFC 3721 on Internet Small Computer Systems Interface (iSCSI) Naming and Discovery. It is recommended that <string-defined-by-org> be a Universally Unique Identifier (UUID).
The use of the target,lun form of the iSCSI URI will only be transferable between hosts if the mapping from the initiator, target, and LUN to the logical unit name is configured to be independent of the initiator.
Examples:
iscsi:///luname.eui.0021280001cf80f6 iscsi:///luname.naa.600144f03d70c80000004ea57da10001 iscsi://[::1]/luname.naa.600144f03d70c80000004ea57da10001 iscsi://127.0.0.1/luname.naa.600144f03d70c80000004ea57da10001 iscsi://127.0.0.1:3260/luname.naa.600144f03d70c80000004ea57da10001 iscsi://hostname:3260/luname.eui.0021280001cf80f6 iscsi://hostname:3260/luname.naa.600144f03d70c80000004ea57da10001 iscsi://127.0.0.1/target.iqn.com.sun:02:d0f2d311-f703,lun.0 iscsi://127.0.0.1/target.eui.bbbbbbbbbbff0011,lun.0 iscsi://127.0.0.1:3260/target.iqn.com.sun:02:d0f2d311-f703,lun.3 iscsi://127.0.0.1:3260/target.eui.bbbbbbbbbbff0011,lun.3 iscsi:///target.iqn.com.sun:02:d0f2d311-f703,lun.6 iscsi:///target.eui.bbbbbbbbbbff0011,lun.6 iscsi://[::1]/target.iqn.com.sun:02:d0f2d311-f703,lun.2 iscsi://[::1]/target.eui.bbbbbbbbbbff0011,lun.2 iscsi://hostname:3260/target.iqn.com.sun:4db41b76-e3d7-cd2f-bf2d-9abef784d76c,lun.0 iscsi://hostname:3260/target.eui.bbbbbbbbbbff0011,lun.0
The iSCSI URI specifies an object based on a logical unit number accessible via iSCSI protocol. Optional hostname[:<port>] authority section provides information for a consumer to set up a send-targets discovery address. IPv6 addresses must be enclosed in square brackets.
Format of an ID is explained in the Logical Unit URI section. See NOTES for information on NAA and EUI-64 based identifier formats.
The iscsi URI type does not support the create operation.
nfs://<user>:<group>@<host>[:<port>]/<nfs-share-path>/<file>
Examples:
nfs://admin:staff@host/export/test/nfs_file nfs://admin:staff@host:1000/export/test/nfs_file
The NFS URI specifies an object based on a labeled lofi device created on the given NFS file. The NFS file will be accessed with credentials derived from user and group. User and group can be given as usernames or userids. The host can be given as an IPv4 address, IPv6 address, or as a hostname. IPv6 addresses must be enclosed in square brackets.
Components of the NFS share path may only include characters from the POSIX.1-2008 Portable Filename Character Set, 0-9a-zA-Z._-.
The nfs URI type supports the create operation.
file://<user>:<group>@<host>/<file-path>
Examples:
file://admin:staff@/filepath file://admin:staff@localhost/filepath
The file URI specifies an object based on a labeled lofi device created on the given local file. The file will be accessed with credentials derived from user and group. User and group can be given as usernames or userids. The host does not need to be specified, but must be localhost when given.
Components of the file path may only include characters from the POSIX.1-2008 Portable Filename Character Set, 0-9a-zA-Z._-.
The file URI type supports the create operation, and may also be mapped to a removable/read-only device.
To avoid errors by generating URIs manually, the suriadm(8) subcommand lookup-uri is recommended to be used to generate URIs based on existing system device paths, logical unit names, or other information. For more information, see the suriadm(8) man page. Such information is identified beforehand through other means. For Fibre Channel devices, fcadm(8) can be used. For Serial Attached SCSI devices, sasinfo(8) can be used. For iSCSI devices, iscsiadm(8) can be used.
See attributes(7) for descriptions of the following attributes:
|
attributes(7), fcadm(8), iscsiadm(8), lofi(4D), sasinfo(8), suriadm(8), zpool(8)
Small Computer System Interface-3 (SCSI-3)
RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
NAA stands for Name Address Authority and it is a field within an identifier that specifies the format and length of that identifier. NAA identifier format is defined in SCSI Primary Commands - 3 specification, section 7.6.3.6 NAA identifier format. WWN (World Wide Name) identifiers use an NAA identifier format. EUI-64 stands for 64-bit extended unique identifier and its format is defined by IEEE.