Feature: iSCSI Initiator

andreasn edited this page Sep 25, 2015 · 14 revisions

Cockpit should allow people to configure the iSCSI initiator on the host.


  • iSCSI is a way of mounting remote block devices.
  • Scope: This feature is only client side.
  • "iSCSI initiator" is the client side. "iSCSI target" is the server side.

Previous art


User stories, workflow that will drive design.

User stories:

Robert is a sysadmin in a data-center. Robert runs a central SAN which exports it's LUNs via iSCSI and many hosts accessing that SAN. Robert wants to use the iSCSI initiator to discover targets on the remote target, and set the CHAP username and password to be able to connect to one of the discovered LUNs and attach it to the local host.

George runs a startup he quickly needs to expand the storage of his heavily overloaded VM. George get's some iSCSI storage from his favorite online cloud storage provider. Now George want's to discover and attach the remote storage to his local machine. To do this, George first needs to discover the remote portal, to see what LUNs are available. To leverage multiple paths (multipath) he might want to choose specific NIC 8residing on different subnets) for connecting to the remote portal. Once he can list the remote targets, he selects the new one and attaches it to the local host. From this point on George can handle it like a regular device.


Add multiple workflows here, for the various tasks that need to be accomplished.


  • Robert needs to setup a new hypervisor for one of his colleagues
  • He orders a new physical machine, and the day it arrives he sets it up
  • In his setup, the VMs running on the hypervisor, are not stored locally on the hypervisor, but centrally on a SAN
  • After setting up the host, he now needs to attach a LUN from the SAN
  • He opens Cockpit, and goes to the iSCSI Initiator page
  • He enters the credentials (username and password) of the (on the SAN) freshly created CHAP user
  • He then enters the FQDN and port of the SAN portal, and clicks "Discover targets" to find the available LUNs
  • After finding the relevant LUN, he attaches it to the host
  • Finally he configures the hypervisor to use the freshly attached LUN for storing and retrieving the VM images


  • George needs to connect to a remote portal, discover and attach LUNs
  • One of his existing servers has storage issues, and he want's to extend the existing Volume Group with some volumes he is attaching via iSCSI
  • To do this, George opens cockpit and navigates to the Storage page he selects the
  • He enters the Address and credentials for the remote iSCSI portal, and hits the <Discover> button (optionally he can choose the discovery method)
  • A throbber indicates that remote LUNs are discovered, and LUN's are appearing in a list of available LUNs as they are discovered
  • George scans for the right LUN and selects the <Attach> button to the right, to attach the remote LUN to the local host.
  • A throbber is indicating that the attach process is in progress. Once that is done, the button turns into a <Detach> button and another field is added, showing and linking to the device name of the local device.
  • The attached device is now also appearing in the regular storage device list and can be used to extend the existing Volume Group



Technical Notes


Please give feedback on the above!

  • Is the user expected to reconfigure the LUN? Or just remove it if he no longer needs it?
    • We might want to expose finer configurations for a LUN, but I think that detaching (removing) a LUN should be covered. I included this in the George story.
  • How is the user expected to diagnose an issue with the LUN after configuration (eg: networking issue). Is this out of scope?
    • We should expose all errors which are currently exposed by the iscsi initiator i.e. if connecting to remote target fails. We can even link to the relevant journal part (journal for the iscsi initiator unit) in case that an error comes up in the flow.
    • I would not (yet) help to diagnose the issue.
  • Is it out of scope to format and prepare such a device mounted from a LUN? Does this feature always assume that the iSCSI LUN has been formatted with a readable file system by the SAN administrator (elsewhere).
    • In the scope of the iSCSI related flows, I'd only assume that there is a block device. I would not assume that there is a filesystem on it, sometimes the block device might be used directly for i.e. a PG database.
    • For further consumption of the new device I could imagine that the device pops up in the storage device list, and there we offer all the functionality to further consume the device. I.e. the storage page offers to create a LVM PV, format it with a filesystem, …. We can then also offer follow up functionality per device type, i.e. offer to create a new LVM VG for a PV, or extend an existing VG (if one exists), for filesystems we can offer to mount them (permanently), fsck them, …
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.