Iscsiuio Userspace Tool

Version 0.7.8.6

Jun 27, 2019

------------------------------------------------------

This tool is to be used in conjunction with the QLogic NetXtreme II Linux

driver (Kernel module name: 'bnx2' and 'bnx2x'), QLogic CNIC driver,

and the QLogic iSCSI driver (Kernel module name: 'bnx2i').

This user space tool is used in conjunction with the following

QLogic Network Controllers:

  bnx2:  BCM5706, BCM5708, BCM5709 devices

  bnx2x: BCM57710, BCM57711, BCM57711E, BCM57712, BCM57712E,

         BCM57800, BCM57810, BCM57840 devices

This utility will provide the ARP and DHCP functionality for the iSCSI offload.

The communication to the driver is done via Userspace I/O (Kernel module name

'uio').

There is one component to this application:

1.  'iscsiuio' - This is the daemon which aids in creating iSCSI offloaded

                      connections.

Dependencies:

=======================================

Linux Kernel Dependencies:

1.  QLogic CNIC driver (cnic)

1.  QLogic iSCSI offload driver (bnx2i)

2.  Userspace I/O driver (uio)

Directory Structure of this Package:

=======================================

<root>

  |

  +-doc (documentation directory: man pages)

  |

  +-src

     |

     +- uip - the uIP stack

     |

     +- unix - iscsiuio source

Compiling / Installing

=======================================

1.  Please untar the tarball.

2.  Run the configure script.  This will create the Makefiles and proper

    header files needed for the build.

3.  Run 'make'.  This will create the binary, 'iscsiuio'

4.  Run 'make install' to place the binaries in their installed location.

    (The default location is '/sbin')

iscsid IFACE Configuration File:

=======================================

The network interface configuration files are driven by the iscsid iface

files.  The configuration data is parsed by iscsid and passed to the uIP

stack when the connection is established.

One can use the following iscsiadm commands to create/set the configuration

using the iface files:

1.  Create the iface file:

      iscsiadm -m iface -I <iface name> --op=new

2.  Discover the targets associated with the new iface

     iscsiadm -m discovery -t st -p <iSCSI target IP address> -I <iface name>

3.  Update the iface file:

  To use a static IPv4 address:

      iscsiadm -m iface -I <iface name> --op=update --name=iface.ipaddress --value=<static IPv4 address ie: 192.168.0.1>

  To use a DHCP address:

      iscsiadm -m iface -I <iface name> --op=update --name=iface.ipaddress --value=0.0.0.0

  The following values are required.

  To specify the bnx2i as the transport:

      iscsiadm -m iface -I <iface name> --op=update --name=iface.transport_name --value=bnx2i

  To specify the network interface to offload with:

  a.  Specify the physical network interface name <ie. eth0, eth1, eth2 ...>

      iscsiadm -m iface -I <iface name> --op=update --name=iface.net_ifacename --value=<network interface name>

  b.  Specify the iSCSI MAC address of the iSCSI HBA

      iscsiadm -m iface -I <iface name> --op=update --name=iface.hwaddress --value=<MAC address of the iSCSI HBA>

4.  Now all the settings should be set so that one could connect to their

    desired iSCSI target.

      iscsiadm -m node -p <iSCSI target IP address> -T <target name> -I <iface name> --login

bnx2 Limitations:

=======================================

*  RX iSCSI ring:

      *  default ring size is 3 entries

      *  default buffer size is 0x400 bytes

*  TX iSCSI ring:

      *  default ring size of 1 entry

      *  default buffer size is 0x400 bytes

bnx2x Limitations:

=======================================

*  RX iSCSI ring:

      *  default ring size is 15 entries

      *  default buffer size is 0x400 bytes

*  TX iSCSI ring:

      *  default ring size of 1 entry

      *  default buffer size is 0x400 bytes

Other Limiations:

Any packets larger then the buffer size will not be sent/received by the

hardware and will be dropped.

IPv6 support:

IPv6 NDP (neighbor discovery protocol), DHCPv6 and Static IPv6 are now

supported.  The IPv6 address used for the connection will be matched against

the DHCPv6/static IPv6 address, the RA (router advertise) address, and the

assigned link local address.

VLAN support:

VLAN support is only supported when using static IP addresses.

Also, currently only 1 VLAN is supported per physical network interface.

Either non-VLAN offloaded traffic is allowed or VLAN offloaded traffic

is allowed.  The current implementation does not support both at the

same time.

Currently there is no explicit VLAN attributes in the iface file.

To configure the VLAN offload, the iface.hwaddress attribute or

physical net_ifacename (without the VLAN identifier) must be used

to specify the HBA device.  For the proper CNIC routing, the

corresponding L2 interface which has the associated VLAN interface must

have an IP address on the same subnet.

The following attributes need to be filled when offloading via the

VLAN interface:

	iface.iscsi_ifacename = <name of this iface file>

	iface.hwaddress = XX:XX:XX:XX:XX:XX

	iface.ipaddress = XX.XX.XX.XX

	iface.transport_name = bnx2i

Setting IP address:

On RHEL5.4, RHEL5.5+, RHEL6.0+, and SLES11SP1 distributions,

discovery login is done over the Linux TCP/IP stack and L2 network

interface.  The ethx interface corresponding to the HBA must

therefore be in the same IP subnet in order to reach the iSCSI

target during discovery.  However, the HBA's IP address should not

be the same as the L2 ethx's IP address.

Starting with RHEL6.1 and all other newer distributions, discovery

using SendTargets is done over the HBA interface, so there is no

need for the HBA and L2 network to be on the same subnet.  However,

if VLAN is used on the HBA, they still have to be on the same subnet

as described above.

Setting Netmask and Gateway addresses:

With the current limitations of the iface file, there are no entries

to allow the user to enter a netmask or gateway IP address.

The only way to explicitly configure these options is to use DHCP

addressing.  Then the netmask/gateway are set on the DHCP server.

These settings are then sent to uIP via the DHCPOFFERs.

If the netmask is not defined then the netmask are automatically

generated depending on the destination IP address.

Debugging:

=======================================

By default, the iscsiuio daemon does not output any messages to the log file,

'/var/log/iscsiuio.log'.  Message logging is only enabled when the daemon is

run under debug mode.

To run the daemon in debug mode please pass the parameter  '-d <debug level>'

where the following debug levels are defined:

DEBUG         4 - Print all messages

INFO          3 - Print messages needed to follow the uIP code (default)

WARN          2 - Print warning messages

ERROR         1 - Only print critical errors

A sample banner message:

INFO  [Mon Jun 20 11:23:14 2011]Started iSCSI uio stack: Ver 0.7.0.6

INFO  [Mon Jun 20 11:23:14 2011]Build date: Mon Jun 20 11:22:05 PDT 2011

INFO  [Mon Jun 20 11:23:14 2011]Debug mode enabled

These messages can be used to help debug any issues.

When debugging issues like the iscsid, the iscsiuio daemon can be run

in the foreground and the maximum debugging level should be used.

To place the daemon in foreground mode please pass the parameter '-f'

Note: The messages to the log file are not flushed unless debugging is enabled.

Note:  If the daemon iscsiuio is running, one will not be able to

       trample over the existing binary.  One might see the following message:

       'cannot create regular file `/sbin/iscsiuio': Text file busy'

       The solve this, please stop the iscsid service and then install.

Warning:  If full debug is enabled, this may quickly fill the partition

containing the iscsiuio logs.  This is because full debugging will log

packet activity which on a busy network will quickly fill the logs.

Note:  If the bnx2i and cnic drivers are unloaded, then iscsiuio will also

need to be restarted so that it can determine the iscsid version.