open-iscsi for Debian
-----------------------------------

The open-iscsi package contains the userspace portion the Open iSCSI
project. It depends on iSCSI modules which are already present in
current (>= 2.6.18) kernels.


Safety of package upgrades
-----------------------------------

When upgrading this package, iscsid will be restarted. This is
generally safe, in that the kernel will still keep iSCSI sessions open
even if iscsid exits. (The kernel will not, however, automatically
reconnect if the connection is dropped, because e.g. the target is
unreachable for a couple of seconds - that only happens if iscsid is
running.) iscsid will try to reconnect all currently open iSCSI
sessions once it starts up again - and as long as that succeeds, it
will be completely transparent for anything that is accessing iSCSI
storage (I/O will block for up to a couple of seconds). The package's
scripts (preinst, postinst) contain checks that make sure all iSCSI
sessions are in a good state before attempting the upgrade (and will
provide the option to abort upgrades if that is not the case).

HINT: It is advisable to check the validity of the configuration
before upgrading - to make sure that a restart of iscsid after the
upgrade will in fact work.


64 bit kernel with 32 bit userspace
-----------------------------------
open-iscsi running with a 64 bit kernel and 32 bit userspace
can run into a hang during the iSCSI login phase. This is a known
issue upstream. For details, please see Debian BTS #502845


Automatic login and mount
-----------------------------------

If you want to automatically connect to all discovered targets, change
the following line:
node.startup = manual
to:
node.startup = automatic

If you want to automatically mount filesystems on iSCSI volumes,
change node.startup to automatic as above, and also add _netdev to
the mount options (in /etc/fstab) for the filesystems you would like
to mount automatically when open-iscsi is started. On sysvinit systems
you should also make sure that HANDLE_NETDEV is set to 1 in
/etc/default/open-iscsi (not required for systemd systems).


iSCSI Qualified Names (IQN) and initiatorname.iscsi
-----------------------------------

The initiatorname.iscsi file defines the iSCSI Qualified Name (IQN) of the iSCSI 
initiator. This IQN is used by the initiator to identify itself to the target.

Example: InitiatorName=iqn.2004-10.com.ubuntu:01:lnx-debian

While this name can be adjusted to suit your needs, once set, it should not be 
changed. If you later change the InitiatorName, existing access control lists 
on the target may reject the initiator to log in. In case a name change is 
required, the access control lists on the target will need to be updated.


Root on iSCSI
-----------------------------------

The Debian open-iscsi package now supports root filesystem on iSCSI.  Support
for this is controlled by the existence of the /etc/iscsi/iscsi.initramfs file.

If you are booting from an iSCSI accelerator or NIC that supports iSCSI boot
natively, you can likely have your iSCSI target mounted without any manual
configuration. Either place the single line "ISCSI_AUTO=true" into
/etc/iscsi/iscsi.initramfs, or use the kernel boot line option "iscsi_auto".

If you use automatic configuration, and the iSCSI NIC is also the NIC that
has the default route, you need to install the busybox (or busybox-initramfs
on Ubunut) package, otherwise the default route will not be set when you
boot the system.

If manual configuration is necessary, there are two ways to include iSCSI boot 
options in your initramfs:

1) Touch /etc/iscsi/iscsi.initramfs and provide options on the command line.
   This provides flexibility, but if passwords are used, is not very secure.
   Available boot line options:
   	iscsi_initiator, iscsi_target_name, iscsi_target_ip,
	iscsi_target_port, iscsi_target_group, iscsi_username,
	iscsi_password, iscsi_in_username, iscsi_in_password
   See iscsistart --help for a description of each option

2) Provide iSCSI option in /etc/iscsi/iscsi.initramfs.
   Available options:
   	ISCSI_INITIATOR, ISCSI_TARGET_NAME, ISCSI_TARGET_IP,
	ISCSI_TARGET_PORT, ISCSI_TARGET_GROUP, ISCSI_USERNAME
	ISCSI_PASSWORD, ISCSI_IN_USERNAME, ISCSI_IN_PASSWORD

   Example Syntax:

   ISCSI_INITIATOR="iqn.2004-10.com.ubuntu:01:9b3e5634fdb9"
   ISCSI_TARGET_NAME=iqn.2008-01.com.example:storage.foo
   ISCSI_TARGET_IP=192.168.1.1
   ISCSI_TARGET_PORT=3260
   ISCSI_USERNAME="username"
   ISCSI_PASSWORD="password"
   ISCSI_IN_USERNAME="in_username"
   ISCSI_IN_PASSWORD="in_password"
   ISCSI_TARGET_GROUP=1

   Remember to set proper permissions if username/passwords are used.

If both facilities are used, command line options overwrite iscsi.initramfs
options.  Also remember that iSCSI requires a working network device, so
you'll need to get networking started via an ip= boot option (ex. ip=dhcp).
You also won't want to restart the device during boot, so set it to manual
mode in /etc/networking/interfaces.  Provide a root=/dev/sd* device as the
iSCSI disk will look like a local disk.

Note: If you need multiple sessions in the initramfs, you can provide multiple IPs
to the ISCSI_TARGET_IP variable.
Eg: ISCSI_TARGET_IP="192.168.1.1 192.168.2.1 192.168.3.1"
This will allow login into all the Target IPs in the initrafs.


QLogic/Broadcom (bnx2/bnx2x) Offloading
-----------------------------------

Cards managed by the bnx2 / bnx2x driver support hardware offloading of
iSCSI sessions. To enable support for this, please install the iscsiuio
package. Further details can be found in the package's README file,
located in /usr/share/doc/iscsiuio/README.gz.


Booting with Hardware Offloading
-----------------------------------

Booting from volumes accessed via hardware offloaded devices is
supported. For bnx2/bnx2x cards the iscsiuio package must be installed.
At the moment this is only supported when using automatic NIC
configuration at boot time when using iscsi_auto on the kernel command
line or ISCSI_AUTO=true in /etc/iscsi/iscsi.initramfs (see above).


initramfs integration
-----------------------------------

open-iscsi binaries are added to the initramfs, regardless of whether
/etc/iscsi/iscsi.initramfs exists, because kernel parameters could be used
to specify iSCSI parameters regardless of its existence.

If you don't have the root or /usr filesystem on iSCSI and want to keep the
size of your initramfs small, create

/etc/initramfs-tools/conf.d/open-iscsi

with the following contents:

NO_ISCSI_IN_INITRAMFS=yes
