Add documentation for iscsi iface support

Closes-Bug: #1417631
Change-Id: I22945649d96be3f6aa1012f0ece096f77ec55879

doc/config-reference/ch_computeconfigure.xml

@@ -88,6 +88,7 @@
  <xi:include href="../common/section_compute_config-api.xml"/>
  <xi:include href="../common/section_compute-configure-ec2.xml"/>
  <xi:include href="../common/section_fibrechannel.xml"/>
  <xi:include href="compute/section_compute-iscsioffload.xml"/>
  <xi:include href="compute/section_compute-hypervisors.xml"/>
  <xi:include href="compute/section_compute-scheduler.xml"/>
  <xi:include href="compute/section_compute-cells.xml"/>

doc/config-reference/compute/section_compute-iscsioffload.xml

@@ -0,0 +1,111 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="iscsioffload">
    <title>iSCSI interface and offload support in Compute</title>
    <note>
        <para>iSCSI interface and offload support is only present since Kilo.
        </para>
    </note>
    <para>Compute supports <package>open-iscsi</package> iSCSI interfaces for
        offload cards.
        Offload hardware must be present and configured on every compute
        node where offload is desired. Once an <package>open-iscsi</package>
        interface is configured, the iface name (<literal>iface.iscsi_ifacename</literal>)
        should be passed to libvirt via the <literal>iscsi_iface</literal>
        parameter for use. All iscsi sessions will be bound to this iSCSI
        interface.
    </para>
    <para>Currently supported transports (iface.transport_name) are
      <simplelist type='inline'>
        <member>be2iscsi</member>
        <member>bnx2i</member>
        <member>cxgb3i</member>
        <member>cxgb4i</member>
        <member>qla4xxx</member>
        <member>ocs</member>
      </simplelist>. No configuration changes are needed outside of Compute node.
    </para>
    <para>iSER is currently supported via the separate iSER
        LibvirtISERVolumeDriver and will be rejected if used via the
        <literal>iscsi_iface</literal> parameter.
    </para>
    <section xml:id="iscsi-iface-config">
        <title>iSCSI iface configuration</title>
        <itemizedlist>
          <listitem>
            <para>Note the distinction between the transport name
                (<literal>iface.transport_name</literal>)
                and iface name (<literal>iface.iscsi_ifacename</literal>).
                The actual iface name must be specified via the
                <literal>iscsi_iface</literal> parameter to libvirt for
                offload to work.
            </para>
          </listitem>
          <listitem>
            <para>The default name for an iscsi iface (open-iscsi parameter
                <literal>iface.iscsi_ifacename</literal>) is in the format
                transport_name.hwaddress when generated by
                <application>iscsiadm</application>.
            </para>
          </listitem>
          <listitem>
            <para><application>iscsiadm</application> 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 :
              <screen><prompt>#</prompt> <userinput>iscsiadm -m iface</userinput>
   <computeroutput>default tcp,&lt;empty>,&lt;empty>,&lt;empty>,&lt;empty>
   iser iser,&lt;empty>,&lt;empty>,&lt;empty>,&lt;empty>
   bnx2i.00:05:b5:d2:a0:c2 bnx2i,00:05:b5:d2:a0:c2,5.10.10.20,&lt;empty>,&lt;empty>
   cxgb4i.00:07:43:28:b2:58 cxgb4i,00:07:43:28:b2:58,102.50.50.80,&lt;empty>,&lt;empty>
   qla4xxx.00:c0:dd:08:63:ea qla4xxx,00:c0:dd:08:63:ea,20.15.0.9,&lt;empty>,&lt;empty></computeroutput>
              </screen>
            </para>
            <para>The output is in the format :
                <emphasis role="italic">iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname.</emphasis>
            </para>
          </listitem>
          <listitem>
            <para>Individual iface configuration can be viewed via
              <screen><prompt>#</prompt> <userinput>iscsiadm -m iface -I <replaceable>IFACE_NAME</replaceable></userinput>
   <computeroutput># BEGIN RECORD 2.0-873
   iface.iscsi_ifacename = cxgb4i.00:07:43:28:b2:58
   iface.net_ifacename = &lt;empty>
   iface.ipaddress = 102.50.50.80
   iface.hwaddress = 00:07:43:28:b2:58
   iface.transport_name = cxgb4i
   iface.initiatorname = &lt;empty>
   # END RECORD</computeroutput>
              </screen>
            </para>
            <para>Configuration can be updated as desired via
              <screen><prompt>#</prompt> <userinput>iscsiadm -m iface-I <replaceable>IFACE_NAME</replaceable>--op=update -n iface.<replaceable>SETTING</replaceable> -v <replaceable>VALUE</replaceable></userinput>
              </screen>
            </para>
          </listitem>
          <listitem>
            <para>All iface configurations need a minimum of
                <literal>iface.iface_name</literal>,
                <literal>iface.transport_name</literal> and
                <literal>iface.hwaddress</literal> to be correctly configured
                to work.
                Some transports may require <literal>iface.ipaddress</literal>
                and <literal>iface.net_ifacename</literal> as well to bind
                correctly.
            </para>
            <para>Detailed configuration instructions can be found here
                <link
                    xlink:href="http://www.open-iscsi.org/docs/README">
                    http://www.open-iscsi.org/docs/README
                </link>
            </para>
          </listitem>
        </itemizedlist>
    </section>
</section>