Hosts and Host Groups
A Host is the QuantaStor object that represents a client machine's storage identity -- one or more initiator ports, given a name you can recognise. Storage Volumes are not reachable by anybody until they are assigned to a Host or a Host Group, so adding a Host is the step between provisioning a volume and a server actually seeing a LUN. This page covers what a Host record is, the three kinds of initiator and where to find them, adding and removing initiators, Host Groups as a unit of assignment, removing a Host, and what to check when a client cannot see its LUN.
Assignment itself is documented on Storage Volumes, because it is an operation on a volume. This page owns the Host.
| Section | Purpose |
|---|---|
| What a Host is | What the record holds, and why an initiator identity needs a name |
| Where the controls are | The Host and Host Group toolbar groups |
| Initiators: IQN, NQN and WWPN | The three identifier types and where to read each one |
| Adding a host | The Add Host dialog, the uniqueness rules, and the FC initiator search |
| Modifying a host | What can be changed after the fact, and what cannot |
| Adding and removing initiators | Multi-initiator and multi-protocol hosts, and what removal does to access |
| Host Groups | Assigning to a cluster rather than to each node |
| CHAP and host credentials | Why CHAP is not a Host property |
| Removing a host | The group-membership guard, and what happens to assignments and sessions |
| When a client cannot see its LUN | A checklist, in the order worth checking |
| CLI quick reference | The host-* and host-group-* commands
|
What a Host is
A Host record is a name plus a list of initiator ports -- the identifiers a client presents when it logs in to the storage system. It also carries an optional description, an optional IP address and an operating-system type, none of which affect access; the initiator ports are the whole of the identity.
QuantaStor has no open-access mode. Every Storage Volume is its own target with an initiator access group, and only the initiators of assigned Hosts and Host Groups are placed in that group. So the Host object exists to name the initiator strings a volume may be served to. Everything else on the record is bookkeeping, there to help you recognise the host a year later.
Two consequences follow from that, and both are easy to trip over:
- A Host with no initiators is a valid record that grants nothing. Volumes can be assigned to it and the assignment appears in every list, but there is no initiator to place in any access group.
- An initiator string belongs to exactly one Host. Adding an initiator that already exists elsewhere is refused with A Host with the specified initiator '<value>' already exists, naming the value rather than the other host. That is deliberate -- two Host records sharing an initiator would make access ambiguous -- but it means a machine that has been re-registered under a new name has to have its initiator removed from the old record first.
Select the Hosts & Portal Groups section in the tree on the left. The Hosts tab in the centre lists every host, grouped by Host Group, with ungrouped hosts collected under <Individual Hosts>. The Volumes column counts the volumes assigned to that host directly; volumes assigned to a group the host belongs to are listed against the group in the Storage Volume Assignments pane with an Assignment Type of Host Group. The Initiator Ports pane lists every initiator on the system with the host it belongs to.
Where the controls are
Every Host and Host Group operation is on the toolbar; none of them is right-click only. Right-clicking a host offers most of its own operations -- Add Host, Remove Host, Modify Host, Add Initiator and Assign Volumes -- plus Properties...; Remove Initiator is on the toolbar only, and so is everything in the Host Group group.
| Toolbar group | Buttons |
|---|---|
| Host | Add, Assign, Add Initiator, Remove, Modify, Remove Initiator |
| Host Group | Create, Add/Remove Hosts, Assign, Delete, Modify |
Assign in either group opens the assignment dialog, which is documented under Assigning volumes to hosts. The Portal Group toolbar group beside them manages which target network ports a volume is reachable on and is not covered here.
Initiators: IQN, NQN and WWPN
An initiator port is identified by one of three strings, and QuantaStor works out which kind it is from the format rather than from which field you typed it into.
| Type | Looks like | Where to read it on the client |
|---|---|---|
| iSCSI IQN | iqn.1991-05.com.example:iscsihost-03fo1500 -- iqn.yyyy-mm.naming-authority:unique-name, per RFC 3720 |
On Linux, the InitiatorName= line in /etc/iscsi/initiatorname.iscsi. On a QuantaStor appliance acting as an initiator, sudo qs-util iscsiiqn prints it. On other platforms it is shown by the client's own iSCSI initiator configuration tool.
|
| NVMe-oF NQN | nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432 -- the format is defined in the NVMe Base Specification, chapter 4.5 |
On Linux, /etc/nvme/hostnqn.
|
| FC WWPN | 21:00:00:24:ff:12:34:56 -- a 16-digit hexadecimal worldwide port name, one per FC port on the HBA |
From the HBA's own tooling, or -- if the port is already zoned to this system -- from the Select Initiator search in the Add Host and Add Host Initiator dialogs. See Fibre Channel Target Port Management. |
QuantaStor does not discover iSCSI or NVMe initiator names for you. There is no scan that will find them: you read the name on the client and paste it in. Only Fibre Channel has a search, and only because an FC port that is zoned to this system announces itself to the fabric.
Two details of how the string is handled are worth knowing:
- A leading fragment before
iqn.is stripped. PastingInitiatorName=iqn.1991-05.com.microsoft:server01straight out ofinitiatorname.iscsistoresiqn.1991-05.com.microsoft:server01. This is a deliberate guard against a copy/paste that took too much. - An FC WWPN is normalised. Separators are stripped and the value is lower-cased, so a WWPN written with colons, with dashes, as bare hex, or with a
0xprefix all reach the same stored value.
A single Host may carry several initiators, of mixed types -- an iSCSI IQN for the software initiator, two WWPNs for a dual-port HBA and an NQN, all on one record -- which is how one Host object represents a machine that reaches the same volume over more than one protocol.
Adding a host
| Field | Notes |
|---|---|
| Host Name | Required. Pre-filled with a generated host-<n> name, selected so typing replaces it. Up to 128 characters of alphanumerics plus -, _ and .; it may not begin with one of those three characters, and it may not be formatted as a UUID -- that shape is reserved for object identifiers.
|
| Description | Optional free text, for your own benefit only. |
| Operating System Type | Windows, Mac OS X, Linux, Solaris, AIX, HP-UX, VMware, XenServer or Other. Defaults to Windows. This is a label -- it does not change how the volume is presented. |
| Initiator | A radio group over iSCSI Initiator (IQN), FC Initiator WWPN and NVMeoF Initiator (NQN). The selected row's field is enabled and the other two are greyed out, so exactly one initiator can be given here. Add the rest afterwards with Add Initiator. |
Select Initiator..., beside the WWPN field, is enabled only when the FC Initiator WWPN radio is selected. It opens Select FC Remote Initiator WWPN, which enumerates the FC remote initiator ports this system's FC target ports can see and offers them as a de-duplicated list, so you can pick a WWPN rather than transcribing one. If nothing is visible it closes with No FC Initiator WWPNs found -- as the button's own tooltip says, remote initiators may not be discoverable depending on the FC device and the fabric zoning. It needs FC target ports on this system; see Fibre Channel Target Port Management.
Three checks run when you click OK, and each has a distinct message:
- The initiator must be a recognisable IQN, NQN or WWPN. A string that is none of those is refused with Initiator port ID '<value>' is non-compliant, one must specify a valid IQN, NQN, or FC WWPN.
- The initiator must not already belong to another Host -- see What a Host is.
- The IP address, if given, must not already be in use by another Host or another initiator port.
Adding a host that already exists with the same name and the same initiator is not an error: the operation reports success and the task description reads Verified host '<name>' with initiator IQN '<value>' is already added. This makes qs host-add safe to run repeatedly from a provisioning script. If the initiator exists but the Host it pointed at has since been deleted, the orphaned initiator record is reclaimed silently.
Modifying a host
Pick the host at the top; the Host Settings fields fill in from it and you edit in place. Host Name, IP Address, Description and OS Type can all be changed at any time.
Initiators are not editable here. They are separate objects with their own add and remove operations -- see Adding and removing initiators.
Renaming a host is safe as far as access is concerned: volume assignments reference the host's identifier rather than its name, so nothing has to be re-assigned. The new name has to satisfy the same character rules as a new host's name.
Nothing stops you renaming two hosts to the same name. The rename path does not check for a duplicate, and once two hosts share a name every command that addresses one by name -- --host=<name>, --host-list -- becomes ambiguous. Keep host names unique yourself, and address a host by its identifier if you are unsure which one a name resolves to.
Adding and removing initiators
Add Host Initiator carries the same three-way radio group as Add Host, over a host selector. One initiator is added per invocation, so a dual-port HBA takes two passes. There is no limit on how many a host may have, and they may be of mixed types.
Remove Host Initiator has two selectors: choose the host, and the Initiator list is filtered to that host's own ports. A confirmation prompt names the initiator before anything happens.
What removal does, and does not do:
- The initiator is dropped from the access group of every volume the host can reach, within a few seconds. No new login from that initiator will be accepted.
- The volume-to-host assignments are left in place. Removing a host's last initiator leaves every assignment listed exactly as before -- the host simply has nothing to grant them to. Adding an initiator back restores access with no re-assignment step.
- An already established session is not torn down. Revocation applies to the next login; a client that is logged in keeps its LUN and keeps doing I/O until it logs out or the session is dropped from the volume's Sessions tab. See Sessions.
That first and second point together are the most common cause of "the assignment is right but the host sees nothing": the assignment list is not evidence that the host has a usable initiator. Check the Initiator Ports pane, not the assignment.
Host Groups
A Host Group is a named set of Hosts that volumes can be assigned to as a unit. It exists for one situation: a cluster, where every node must see the same LUNs. Create one Host Group per VMware cluster, Windows failover cluster, Proxmox cluster or similar, and assign volumes to the group instead of to each node.
Assignment to a group is not the same as assigning to each member, and the difference is the point of the object. A group assignment is a single access-control entry that names the group. It is expanded over the group's current membership every time the access groups are rebuilt, so:
- A host that joins a group immediately gains access to every volume assigned to that group, with no volume operation at all. Adding the fourth node to a cluster is one Add/Remove Hosts click, not one re-assignment per LUN.
- A host that leaves a group immediately loses that access. Its initiators are dropped from the access groups of the group's volumes within a few seconds. As with initiator removal, an established session survives until the client logs out.
- Unassigning the volume from the group removes it from every member at once.
A host may belong to at most one Host Group'. The Create Host Group and Add/Remove Hosts grids enforce this by only listing hosts that are ungrouped (or, in Add/Remove Hosts, already in the group being edited), and the service refuses a host that is already in another group with Host '<name>' is already in use by another host group '<group>. Where a machine genuinely needs two sets of LUNs, assign one set to the group and the other to the host directly -- the two kinds of assignment are independent and add together.
Creating a host group
Give the group a name and description and tick at least one host. At least one member is required -- an empty group is refused with You must select a least one host to create a group. A group name may not collide with another group name, nor with an existing host name: the create is refused with A host with the specified name [<name>] already exists, host group names cannot collide with host names. The check is one-way only -- a host may be created or renamed to the name of an existing group -- so choose a naming convention that keeps the two apart rather than relying on the check.
Create the hosts first. With no hosts on the system the dialog closes immediately with There are no hosts from which to create a group.
Adding and removing members
Pick the group and the grid shows its current members ticked, alongside every ungrouped host. The tick state you leave becomes the complete membership, so clearing a tick removes that host from the group. Untick nothing and you are only adding.
Because unticking removes, a confirmation lists the hosts marked for removal and asks Are you sure you want to remove n host group member(s)? before applying. At least one host must remain ticked; the dialog will not apply an empty membership.
The CLI is explicit rather than set-based, which is usually what a script wants: qs host-group-host-add and qs host-group-host-remove each take a --host-list and only touch the hosts named. Removing a host that is not in the group is refused rather than ignored.
Modifying and deleting a host group
Modify Host Group changes the Name and Description. Membership is not editable here -- use Add/Remove Hosts.
Delete Host Group shows the selected group's name and description read-only, then asks for confirmation. The member hosts are not deleted -- they are returned to <Individual Hosts> -- but every volume assignment made to the group is, so each former member loses access to the group's volumes. Where those hosts still need the storage, assign the volumes to them individually first.
CHAP and host credentials
CHAP is not a Host property. There is nowhere on a Host to set a CHAP username and password, and none of the Host dialogs offer one. CHAP is configured per Storage Volume, on the volume's Security Settings tab, where it can take its credential from the volume itself, from the owning user account, or from the tenant resource group -- see CHAP authentication. The credential authenticates the initiator to the target, and every initiator that reaches a given volume presents the same credential, so there is nothing per-host to configure.
What this means in practice is that a host is authorized by its initiator string and authenticated -- if you enable CHAP -- by a volume-scoped credential. The two are independent: CHAP does not widen access to an unassigned volume, and an assignment does not exempt an initiator from CHAP.
Management access to the Hosts and Host Groups operations is separate again, and is governed by RBAC: the Host and HostGroup object types each carry view, modify, assignVolume and unassignVolume permissions, plus add/remove/addInitiator/removeInitiator on Host and create/delete on HostGroup. Assign them to a role as described in Security Configuration.
Removing a host
Removing a Host deletes the record, its initiator ports and all of its volume assignments, then rebuilds the access groups so those initiators are no longer served. There is no need to unassign first.
One condition blocks the removal: a host that is a member of a Host Group is refused, with Specified host '<name>' is currently a member of host group '<group>', remove failed. Tick Force to remove it anyway, or take it out of the group first with Add/Remove Hosts. Having volumes assigned is not a blocking condition, with or without Force.
An established session is not dropped by the removal. A client that is logged in keeps its LUN and keeps doing I/O even though its host record and its access are gone; the revocation takes effect on the next login. To cut a connected client off, remove or unassign and drop the session from the volume's Sessions tab, or log the initiator out at the client. This is at odds with the warning the dialog displays and is tracked as a defect.
When a client cannot see its LUN
Work down this list. It is ordered by how often each one is the answer, and every step can be checked from the QuantaStor side except the last.
- Is the volume assigned at all? An unassigned volume is reachable by nobody. Check the Storage Volume Assignments pane, and remember that a volume assigned to a Host Group appears there against the group, not against each member -- with an Assignment Type of Host Group.
- Does the host have an initiator, and is it the right string? This is the most common cause by a distance. An assignment to a host with no initiators, or with a mistyped one, looks completely correct in every list. Compare the Initiator Ports pane character by character against what the client reports --
/etc/iscsi/initiatorname.iscsion Linux,/etc/nvme/hostnqnfor NVMe-oF -- rather than against what you believe it to be. A typo that happens to be short and hexadecimal is accepted as an FC WWPN rather than rejected, so a bad paste can produce a host that looks configured and serves nothing. - Is the host in the group you think it is? The Hosts grid groups its rows by Host Group; a host under <Individual Hosts> is in no group and gets no group assignments. Its Volumes count only counts its own direct assignments, so a host that reaches everything through a group legitimately shows a low number.
- Is the protocol enabled on a network port the client can reach? iSCSI and NVMe-oF/TCP are enabled per port, on the iSCSI Portal and NVMeoF Portal checkboxes -- see Network Ports. A port with the portal cleared will not accept a login through that address. For Fibre Channel the equivalent is a target-mode port and correct fabric zoning; see Fibre Channel Target Port Management.
- Is the volume restricted to a portal group? A volume can be bound to a Portal Group, which limits the target ports it is presented on. If the client is logging in through an address outside that group, the volume will not appear even though the assignment is correct. The Portal Group toolbar group is beside the Host Group one.
- Is the volume's pool online, and imported on the node the client is connecting to? Access groups are only built for volumes whose pool is available on the system doing the serving. A volume in an offline pool is skipped entirely, and in a grid a pool is only ever imported on one system at a time -- so after a high-availability failover the client must be logging in to the address the pool moved to, which is what the HA virtual interface is for.
- Did the client discover before the assignment was made? Most initiators cache their discovery results. Re-run discovery on the client after the assignment; on Linux that is
iscsiadm -m discovery -t sendtargets -p <address>, which lists only the targets this initiator is permitted to see. An empty result is itself informative -- it means the storage system does not currently recognise this initiator for any volume. - Is CHAP enabled on the volume, with a credential the client does not have? A CHAP failure looks like a target that is discoverable but will not log in. See CHAP authentication; note that QuantaStor uses uni-directional CHAP by default, so mutual-authentication settings on the initiator will fail.
Two things that look like problems and are not:
- An iSCSI LUN always appears at LUN 0. Each volume is its own iSCSI target with its own IQN, so there is nothing to renumber. LUN numbers only matter for Fibre Channel.
- A revoked host keeps working until it logs out. Unassigning a volume, removing an initiator, taking a host out of a group and removing the host all take effect on the next login, not on the session in front of you.
CLI quick reference
Every operation on this page has a CLI equivalent; full argument lists are in the QuantaStor CLI Command Reference.
qs host-add --hostname=host1 --iqn=iqn.1991-05.com.example:server01 --host-type=linux qs host-list qs host-get --host=host1 qs host-modify --host=host1 --hostname=host1-renamed --desc="build server" qs host-remove --host=host1 qs host-remove --host=host1 --flags=force qs host-initiator-add --host=host1 --iqn=21:00:00:24:ff:12:34:56 qs host-initiator-list --host=host1 qs host-initiator-get --iqn=iqn.1991-05.com.example:server01 qs host-initiator-remove --host=host1 --iqn=iqn.1991-05.com.example:server01 qs host-group-create --name=vmware-cluster1 --host-list=host1,host2 --desc="ESXi cluster" qs host-group-list qs host-group-get --host-group=vmware-cluster1 qs host-group-host-add --host-group=vmware-cluster1 --host-list=host3 qs host-group-host-remove --host-group=vmware-cluster1 --host-list=host3 qs host-group-modify --host-group=vmware-cluster1 --name=esxi-cluster1 qs host-group-delete --host-group=esxi-cluster1
--iqn is the initiator argument for all three types -- pass an IQN, an NQN or a WWPN to it and the service classifies the value by its format. --host and --host-group accept a name or an identifier, and qs host-initiator-get is the reverse lookup: give it an initiator string and it tells you which host owns it, which is the quickest way to find out why an initiator was refused as a duplicate.
Assignment is on the volume side: qs volume-assign --volume=vol1 --host-list=host1 takes host or host group names in --host-list, and qs volume-assign-list shows every assignment on the system. See Storage Volumes.
Related pages
- Storage Volumes -- the volumes hosts are given access to, assignment, access modes and CHAP
- Network Ports -- which ports carry iSCSI and NVMe-oF/TCP, and the per-port portal settings
- Fibre Channel Target Port Management -- FC target-mode ports, and finding initiator WWPNs on the fabric
- NVMe-oF Target Configuration -- presenting volumes over NVMe over Fabrics
- Security Configuration -- RBAC roles and the Host and HostGroup permissions
- Storage Pools -- the pools the volumes are provisioned from
Verified against QuantaStor 6.9.0. </content>