FAQ / What is COMSTAR/stmf and what is the Interchangeble Naming Scheme (INS)

It may be helpful to use this FAQ in conjunction with the diagram of the help FAQ.

1 Formal Definitions

1.0 Mapping

A mapping, map or function is a pair of sets (A x B, f), where f is a subset of the cartesian product A x B, such that for any pair of members of f if the first elements are equal then so are the second.  A is referred to as the domain and B is referred to as the codomain.

1.1 Injective Mapping

An injective, 1-1 or one-to-one mapping is a mapping, say f, such that for every pair of members of f if the second elements are equal then so are the first.

1.2 Surjective Mapping

A surjective or onto mapping is a mapping, say f, such that for every member of the codomain, say b, there exists a member of f such that b is the second element.

1.3 Bijective Mapping

An injective and surjective mapping.

2 COMSTAR Definitions

2.0 Target

A target is either an IQN, WWN or EUI of a device on the server.

2.1 Host

A host is either an IQN, WWN or EUI of a device of a client. Hosts are also known as initiators.

2.2 Target and Host group

A target group is an stmf structure that characterizes a set of targets. Similarly for host groups.  Host groups can sometimes be referred to as initiator groups.

2.3 View Entry

A view entry is an stmf structure that characterizes a member of T x H x Z*, where T is the set of target groups, H is the set of host groups and Z* is the set of non-negative integers.  The third element of the view, the natural number, is referred to as the logical unit number (LUN); the use of this term will become clear in 2.7.  A view entry is sometimes referred to as a mapping or map; the use of this term will become clear in 2.8.  Also a view entry is sometimes abbreviated to simply a view (as in stmfadm commands) though technically the view is the set of view entries, this latter use of the term “view” will not be used for Mapping Manager FAQ.  For information on view entry index numbers see 2.7.

2.4 Volume (zpool)

A volume or zpool is a zfs pool.

2.5 Zvol

A zvol is a zfs volume.

2.6 Guid

A guid is a global unique identifier for LUs (see below).

2.7 Logical Unit (LU)

A logical unit (LU) is an stmf structure that contains a set of view entries as well as a guid, and possibly meta-data for a zvol.  If an LU does not contain meta-data for a zvol, it is unregistered.  The structure (if registered) therefore specifies which initiators can use which targets to access the zvol corresponding to the contained zvol meta-data.  The set of LUNs from the view entries provide SCSI identifiers for the LUs and thus the underlying zvol, which need not all be the same and thus can provide multiple SCSI identifiers for the underlying zvol.  LUs are identified by guid, and hence different LUs cannot have the same guid.  For obvious reasons two LUs should not each have view entries which share a LUN.

NOTE: stmf uses view entry index numbers to reference view entries. These are not part of the iSCSI/SCSI protocols, but rather a convenience number to reference view entries.

2.8 Mapping zvols (and other objects) into COMSTAR

Clearly the guids induce a bijective mapping from a subset of the zvols to the set of registered LUs.  The existence of a view entry in a LU is necessary for clients to use the underlying zvol, therefore when a view entry is added we expose a member of this mapping to client(s)* and hence give them access to the corresponding zvol.  This process has been termed mapping zvols into COMSTAR since this is how it appears at the front end.  By convention the creation of a view entry in order to expose a member of the mapping is sometimes abbreviated to simply creation of a mapping.  Similarly to zvols, we can also say we map target groups into COMSTAR and map host groups into COMSTAR

*except in the trivial case where the target group or host group are empty.

3 Additional Information (inc TPGs)

3.0 Targets, Initiators and LUNs

Initiators and targets can be both virtual and physical.  An initiator is the endpoint that initiates a SCSI session, that is, sends a SCSI command.  This command will be sent to a target.  So targets and initiators can be considered as destination and source addresses respectively, except the target need not actually address a storage device (zvol) on the network to exist and a target and initiator pair may also impliment authentication (CHAP).  In an iSCSI environment, LUNs are essentially numbered disk drives. An initiator negotiates with a target to establish connectivity to a LUN; the result is an iSCSI connection that emulates a connection to a SCSI hard disk. Initiators treat iSCSI LUNs the same way as they would a raw SCSI or IDE hard drive; for instance, rather than mounting remote directories as would be done in NFS or CIFS environments, iSCSI systems format and directly manage filesystems on iSCSI LUNs.  In COMSTAR a LUN is assigned to a target, using stmf, when a view is added to a logical unit (see definition of view entry).  Since COMSTAR handles ZFS, it is necessary to have virtual targets as zvols are essentially virtual disks.

Since multiple views can be added to a single LU, it may seem confusing that they can have more than one LUN.  This can be resolved by recalling that a LUN is a SCSI identifier for a zvol, NOT an identifier for a LU.  Moreover recall multiple LUs should not have overlapping sets of LUNs so there should be an (injective) one-to-one mapping from LUs to zvols.

3.1 Role of Target Groups

When target groups are mapped into COMSTAR, they provide targets for a zvol so they can be accessed via iSCSI/fibre channel.  The reason why they are called groups, though in general they will only contain a single target, is for migration of targets.

3.2 Role of Host Groups

When host groups are mapped into COMSTAR, they control which initiators can access which zvols.  The reason why they are called groups, though in many applications they will only contain a single initiator (to avoid corruption), is because there are some applications where locking will be done on the data in the zvol.  Therefore multiple clients will be able to access the same zvol and not corrupt it.

3.3 Target Portal Groups

When a target is created it can be assigned a target portal group, which is just a list of IPv4 addresses.  This specifies that only IP’s in this list can be used to access the target.

3.4 From Administrator to Client – A Full Example

In this example we will explain the full processes involved in setting up and accessing data in the COMSTAR framework.

3.4.0 Setup

Assume there is only one client for simplicity.

Step 0: The administrator creates a zpool with a zvol, say zvol1.

Step 1: An initiator, say i1, is created on the client and a target, say t1, is created on the server.  For simplicity assume both are iqns.

Step 2: The administrator creates a target group, say tg1, with a single member t1.

Step 3: The administrator creates a host group, say hg1, with a single member i1.

Step 4: The Administrator creates a LU, say LU1, using the path of zvol1, this effectively creates the LU which currently has no view entries; it just has a guid.

Step 5: The administrator creates a view entry for LU1 which has as fields: target group = tg1, host group = hg1, and lets assume stmf choose the LUN.  The “mapping” has been created!

3.4.1 Accessing The zvol1

Step 1: Client runs format to look for available “disks”.

Step 2: i1, the initiator, probes for a list of available targets over IP.

Step 3: If the initiator is in a host group the server generates a list, T say, of targets which the client can access.  Targets which are listed:

a) have to be a member of a target group which is in a view which contains the host group,

b) must have the (server side) IP being used listed in the target portal group associated the target.

The client then selects a target from this list.

Step 4: The server sends a list of zvols the client can attempt to access.  zvols which are listed must be referenced (by guid) by a view, where the view’s target group contains the chosen target and the initiator is in the view’s host group.

Step 5: The client can then select a zvol to mount, the SCSI protocol uses the LUN in the corresponding view, and a target in the intersection of T and the target group of the view.

Step 6: The client may have to authenticate.

Step 7: The initiator can then initiate SCSI commands to the LUN.

Step 8: stmf then issues the underlying in/out commands to the kernel using the meta-data.  The meta-data is determined by which LU the view is a member.

Step 9: ZFS handles the in/out commands on zvol1.


Posted in: Mapping Manager - mapmgr