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.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 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.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. 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