==============================================
iSCSI interface and offload support in Compute
==============================================

.. note::

   iSCSI interface and offload support is only present since Kilo.

Compute supports open-iscsi iSCSI interfaces for offload cards.
Offload hardware must be present and configured on every compute
node where offload is desired. Once an open-iscsi interface is
configured, the iface name (``iface.iscsi_ifacename``) should be
passed to libvirt via the ``iscsi_iface`` parameter for use.
All iSCSI sessions will be bound to this iSCSI interface.

Currently supported transports (``iface.transport_name``) are
``be2iscsi``, ``bnx2i``, ``cxgb3i``, ``cxgb4i``, ``qla4xxx``, ``ocs``.
Configuration changes are required on the compute node only.

iSER is supported using the separate iSER LibvirtISERVolumeDriver
and will be rejected if used via the iscsi_iface parameter.

iSCSI iface configuration
~~~~~~~~~~~~~~~~~~~~~~~~~

* Note the distinction between the transport name (``iface.transport_name``)
  and iface name (``iface.iscsi_ifacename``). The actual iface name must be
  specified via the iscsi_iface parameter to libvirt for offload to work.
* The default name for an iSCSI iface (open-iscsi parameter
  ``iface.iscsi_ifacename``) is in the format transport_name.hwaddress
  when generated by ``iscsiadm``.
* ``iscsiadm`` can be used to view and generate current iface configuration.
  Every network interface that supports an open-iscsi transport can have one
  or more iscsi ifaces associated with it. If no ifaces have been configured
  for a network interface supported by an open-iscsi transport,
  this command will create a default iface configuration for that
  network interface. For example :

  .. code-block:: console

     # iscsiadm -m iface
     default tcp,<empty>,<empty>,<empty>,<empty>
     iser iser,<empty>,<empty>,<empty>,<empty>
     bnx2i.00:05:b5:d2:a0:c2 bnx2i,00:05:b5:d2:a0:c2,5.10.10.20,<empty>,<empty>

  The output is in the format:
  ``iface_name transport_name,hwaddress,ipaddress,
  net_ifacename,initiatorname``.

* Individual iface configuration can be viewed via

  .. code-block:: console

     # iscsiadm -m iface -I IFACE_NAME
     # BEGIN RECORD 2.0-873
     iface.iscsi_ifacename = cxgb4i.00:07:43:28:b2:58
     iface.net_ifacename = <empty>
     iface.ipaddress = 102.50.50.80
     iface.hwaddress = 00:07:43:28:b2:58
     iface.transport_name = cxgb4i
     iface.initiatorname = <empty>
     # END RECORD

  Configuration can be updated as desired via

  .. code-block:: console

     # iscsiadm -m iface-I IFACE_NAME--op=update -n iface.SETTING -v VALUE

* All iface configurations need a minimum of ``iface.iface_name``,
  ``iface.transport_name`` and ``iface.hwaddress`` to be correctly
  configured to work. Some transports may require ``iface.ipaddress``
  and ``iface.net_ifacename`` as well to bind correctly.

  Detailed configuration instructions can be found at
  http://www.open-iscsi.org/docs/README.