Setting iSCSI targets

StorPool storage can provide block storage services to clients using the following protocols:

  • StorPool Block protocol

    It requires a StorPool driver on the client to access the storage cluster. Supported only for Linux hosts.

  • iSCSI protocol

    It is vendor-neutral and can be used by clients with different operating systems and software stacks, like Linux, MS Windows, VMware ESXi, Xen (and Xen-based Linux distributions), and so on.

This document describes how to configure and use StorPool cluster using the iSCSI protocol.

A quick overview of iSCSI

The iSCSI remote block device access protocol, as implemented by the StorPool iSCSI service, is a client-server protocol allowing clients (referred to as “initiators”) to read and write data to disks (referred to as “targets”) exported by iSCSI servers.

iSCSI is implemented in StorPool with Portal Groups and Portals:

  • A portal is one instance of the storpool_iscsi service, which listens on a TCP port (usually 3260), on a specified IP addresses. Every portal has its own set of “targets” (exported volumes) that it provides service for.

  • A portal group is the “entry point” to the iSCSI service - a “floating” IP address that’s on the first storpool_iscsi service in the cluster and is always kept active (by automatically moving to the next instance if the one serving it is stopped/dies). All initiators connect to that IP and get redirected to the relevant instance to communicate with their target.

Prerequisites

  • You have performed the steps described in Initial iSCSI configuration.

  • You are familiar with the iSCSI protocol and the main concepts. For details, see iSCSI overview.

  • The storpool_iscsi service is enabled and configured on the storage nodes. For details, see storpool_iscsi.

  • The iSCSI base IQN is defined.

    To use the iSCSI protocol, the storage cluster needs to have a base name IQN defined. It is used for creating the IQN of the exported iSCSI targets. This parameter is global for the storage cluster and has to be defined when the initial iSCSI configuration is created. It can’t be changed if there are active iSCSI LUN exports and iSCSI connections. To define the base name IQN:

    StorPool> iscsi config setBaseName iqn.2019-08.com.example:cluster-1
OK

Defining a portal group

To define a portal group:

StorPool> iscsi config portalGroup examplepg create
OK

To configure IP networks and VLAN for the portal group:

StorPool> iscsi config portalGroup examplepg addNet 192.168.41.201/24 vlan 41

When multipath is used, two networks are defined for each portal group - one network per path. The command for the second network is the same as for the first network:

StorPool> iscsi config portalGroup examplepg addNet 192.168.42.201/24 vlan 42

StorPool automatically assigns the first defined network of the portal group to the first interface of the storpool_iscsi service, and the second network to the second interface.

Note

Both networks may use the same or different VLANs

To change a network for a portal group, you need to remove the old network configuration and add a new one:

StorPool> iscsi config portalGroup examplepg delNet 192.168.42.247/24
StorPool> iscsi config portalGroup examplepg addNet 10.2.112.200/24 vlan 51

Note that before deleting the network of a portal group you need to delete all portals using this network. For details, see ‘Defining Portals’ below.

Multi-tenant configuration

You can define multiple portal groups. Each portal group has to use different VLANs and IP networks. Using multiple portal groups you can isolate groups of initiators at the network level. This can be useful for multi-tenant deployments, when one StorPool storage serves multiple isolated tenants. Each tenant uses dedicated VLANs and IP addresses to communicate with StorPool storage cluster.

Defining portals

For maximum performance and availability one portal is defined for each storage node; however, you can define fewer portals. For each portal you need to have storpool_iscsi service installed and enabled on the selected node. In order to enable the portal to be used in the selected portal group, you need to define the portal IP address.

StorPool> iscsi config portal create portalGroup examplepg address 192.168.41.11 controller 1

Consider the following:

  • The last parameter controller defines the node ID where the portal is running.

  • The portal IP address shall match the portal group network. You don’t need to specify the network mask and the VLAN, since they are already set in the portal group definition.

When multipath is used, you need to define two addresses per each portal - one per path:

StorPool> iscsi config portal create portalGroup examplepg address 192.168.42.11 controller 1

Configuring initiators

Before an iSCSI initiator can use StorPool storage, it needs to be registered in the storage cluster with its IQN. To do this:

StorPool> iscsi config initiator iqn.2019-08.com.example:host1 create

Restricting the IP addresses

You can optionally restrict the IP addresses from which the initiator with this IQN can register:

StorPool> iscsi config initiator iqn.2019-08.com.example:host1 addNet 192.168.41.131/32

You can specify an individual IP address (like 192.168.41.131/32) or an IP prefix (like 192.168.41.128/25). You can add more than one IP address or prefix per initiator. If you don’t specify an IP address, the initiator will be allowed to connect from any IP address.

Allowed IP prefix can be added with a separate command, like in the example above, or the prefix can be specified in the initiator create command like this:

StorPool> iscsi config initiator iqn.2019-08.com.example:host1 create net 192.168.41.131/32

Note that if the initiators are in a different IP subnet than the portals, and also the iSCSI connection is routed via a router or layer 3 switch, then you need to enable routed iSCSI as described in Advanced iSCSI setup.

Setting chap authentication

You can configure optional chap authentication by adding parameters chap <user> <password> when registering the initiator:

StorPool> iscsi config initiator iqn.2019-08.com.example:host1 create chap example_user StrongPassword

Note that once the initiator is registered in StorPool, chap authentication cannot be changed without un-registering the initiator first.

Removing initiators

You can remove initiators from the StorPool configuration:

StorPool> iscsi config initiator iqn.2019-08.com.example:host1 delete

Note that before you deleting an initiator you need to remove all exports for this initiator. For details, see ‘Export targets’ below.

Configuring iSCSI targets

For each volume that is accessible over iSCSI an iSCSI target needs to be defined. StorPool supports one LUN per target, so each volume is accessible as a separate target. The targets are defined by their IQN.

Creating iSCSI targets

StorPool> iscsi config target create example-volume

The last parameter is the name of an existing volume. To create a volume, see Volumes.

The iSCSI target is created with IQN composed by concatenating the base name and the volume name; for example, iqn.2019-08.com.example:cluster-1:example-volume.

Note that volume names exported via iSCSI shall have names consisting of only characters valid for IQN: [0-9a-z\.:-]. The underscore is a valid character for volume name - but not for IQN - and it cannot be used in volumes exported via iSCSI. Uppercase characters are also not allowed.

Also, note that a target has to be removed before the backing volume can be deleted or renamed.

Removing iSCSI targets

You can remove an iSCSI target as shown below:

StorPool> iscsi config target delete example-volume

Note that before you are able to remove an iSCSI target, you need to remove all exports for this initiator. For details, see the section on exporting targets below.

Exporting iSCSI targets

An iSCSI target needs to be exported over a specified portal group to be accessible by an iSCSI initiator. When a target is exported, the initiator can discover it and can login to create a session with it to use it. When exporting a target, the administrator can define:

  • The portal group that exports the target (mandatory)

  • The initiator that can access the target (optional)

StorPool> iscsi config export portalGroup examplepg volume example-volume initiator iqn.2019-08.com.example:host1

The ‘initiator’ parameter is optional. When omitted, any initiator with access to the network defined for the portal group can discover and use it.

Note that one target can be exported to multiple initiators simultaneously, but via one portal group only.

Un-exporting iSCSI targets

To un-export a target:

StorPool> iscsi config export portalGroup examplepg volume example-volume initiator iqn.2019-08.com.example:host1

You can omit the initiator parameter if the target was exported to any initiator:

StorPool> iscsi config export portalGroup examplepg volume example-volume

Obtaining details

To list all registered initiators:

StorPool> iscsi initiator list

To list all iSCSI targets:

StorPool> iscsi target list

This shows the volume name, target IQN, and the current controller that serves the target.

To list iSCSI exports with associated portal groups and initiators:

StorPool> iscsi initiator list exports

If the initiator IQN is displayed as *, then the target is exported to any initiator.

To list all active iSCSI sessions:

StorPool> iscsi sessions list

To dump the full iSCSI configuration, including the configured portal groups, portals, list of registered initiators, targets, and exports:

StorPool> iscsi config

The iSCSI configuration is dumped in JSON format.