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.

WARNING!  Please unmount iSCSI-backed filesystems before upgrading the
open-iscsi package, as they are not automatically unmounted and the
restart of iscsid will break the iscsi block devices and prevent any
outstanding I/O from completing (and require a remount before the
filesystems will work again).


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.


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.1993-08.org.debian: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 touch /etc/iscsi/iscsi.initramfs and use the
kernel boot line option "iscsi_auto".

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.1993-08.org.debian: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.  Leave BOOT=local set in
/etc/initramfs-tools/initramfs.conf and 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.