Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Add documentation for iscsi iface support
Closes-Bug: #1417631 Change-Id: I22945649d96be3f6aa1012f0ece096f77ec55879
- Loading branch information
Showing
with
112 additions
and 0 deletions.
| @@ -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,<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> | ||
| cxgb4i.00:07:43:28:b2:58 cxgb4i,00:07:43:28:b2:58,102.50.50.80,<empty>,<empty> | ||
| qla4xxx.00:c0:dd:08:63:ea qla4xxx,00:c0:dd:08:63:ea,20.15.0.9,<empty>,<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 = <empty> | ||
| iface.ipaddress = 102.50.50.80 | ||
| iface.hwaddress = 00:07:43:28:b2:58 | ||
| iface.transport_name = cxgb4i | ||
| iface.initiatorname = <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> |