Introduction
This page summarises configuring iSCSI on Debian 6 and 7. Thanks to HowtoForge's excellent "Using iSCSI On Debian Squeeze (Initiator And Target)" from which most of the information was learned.
Overview
iSCSI allows a server to provide a virtual block device over a network to a client. The virtual block device can then be treated like a real block device – for example it can be partitioned and file systems created in the partitions.
In iSCSI terminology the server is a "target" and the client is an "initiator". On this page they are called server/target and client/initiator.
Links
HowtoForge's "Using iSCSI On Debian Squeeze (Initiator And Target)": http://www.howtoforge.com/using-iscsi-on-debian-squeeze-initiator-and-target
Open-iSCSI: http://www.open-iscsi.org/ including a README: http://www.open-iscsi.org/docs/README
iSCSI Enterprise Target: http://iscsitarget.sourceforge.net/
Planning
You will need:
- A user name and password (for the iSCSI configuration so a free choice. There may be a limit of 16 characters on the password).
- A server/target computer:
- root access.
- The IP address. If there is more than one, the one that will be used by the client/initiator to access it.
- A local block device to be made available to the initiator (client) via iSCSI. May be a file, a HDD (whole device or partition), an LVM volume or a RAID device.
- A client/initiator computer
- root access.
Setting up the target (server)
Installation
aptitude -y install iscsitarget iscsitarget-dkms
Configuration
Optionally backup the configuration files that will be changed: /etc/default/iscsitarget and /etc/iet/ietd.conf.
sed -i 's/ISCSITARGET_ENABLE=false/ISCSITARGET_ENABLE=true/' /etc/default/iscsitarget
The next step sets up to serve a single LVM volume, /dev/vg0/lv0. Values that need to be changed are red. The user and password values are need when configuring the client/initiator. Values that are arbitrary strings (so could be changed) are in blue.
user=someone
password=secret
local_device=/dev/vg0/lv0
oIFS=$IFS; array=($(hostname --long)); IFS=$oIFS
for ((i=${#array[*]};i>0;i--)); do backwards_fqdn+=.${array[i-1]}; done
( echo "Target iqn.$(date +%Y-%m)$backwards_fqdn:storage.lun0"
echo " IncomingUser $user $password"
echo " OutgoingUser"
echo " Lun 0 Path=$local_device,Type=fileio"
echo " Alias LUN0"
) > /etc/iet/ietd.conf
It can be useful to know the Target value just created when configuring the client/initiator. It can be displayed with
head -1 /etc/iet/ietd.conf
Further devices can be added by editing /etc/iet/ietd.conf, replicating and modifying the first stanza.
Setting up the initiator (client)
Installation
aptitude -y install open-iscsi
Configuration
Optionally backup the configuration file that will be changed: /etc/iscsi/iscsid.conf.
sed -i 's/node.startup = manual/node.startup = automatic/' /etc/iscsi/iscsid.conf
In the next step, the iSCSI daemon is used to generate an initial configuration. Values that need to be changed are red. Starting the daemon will generate error messages because there's no configuration yet.
target_ip=192.168.10.27
/etc/init.d/open-iscsi restart
iscsiadm -m discovery -t st -p $target_ip
This should create a sub-directory of /etc/iscsi/nodes/ with the same name as the Target created when configuring the server/target.
Within that sub-directory there should be a further sub-directory with name beginning with the server/target's IP address.
Note: if the server/target has two IP address (accessible by the client/initiator?) there will be two such sub-sub-directories. It may be possible to configure a client/initiator to work this way but initial explorations did not identify how to do so. In this case, delete the sub-sub-directory for the IP address you do not want to use.
In the next step, the user name and password are added to the configuration.
Change to the new /etc/iscsi/nodes/<target>/<IP address ...> directory. In the commands below, the sed command should be on a single line.
user=someone
password=secret
sed -i "s/^node.session.auth.authmethod = None$/node.session.auth.authmethod = CHAP\nnode.session.auth.username = $user\nnode.session.auth.password = $password/" default
Testing
/etc/init.d/open-iscsi restart
The output should include:
Login to [iface: default, target: <target>, portal: <ip address>,<port>]: successful
and a new /dev/sd[a-z]+ device file should have appeared.
Further configuration
The new /dev/sd[a-z]+ block device can be configured as desired.
If it is configured with file system(s) to be mounted at boot there are special considerations for /etc/fstab:
- LABEL or UUID must be used. This is in case the /dev/sd[a-z]+ name assigned by udev changes from boot to boot.
- The options must include _netdev. This ensures that mounting is deferred until the networking daemons (including open-iscsi) are running.
- The sixth field (fs_passno) must be set to 0. This disables fsck when mounting via fstab, necessary because it does not work.
If fscking is required ... TODO
Issue investigation
How to identify a /dev/sd[a-z]+ as an iSCSI device
The easiest way is to list /dev/disk/by-path/
If lshw is installed, more information is available by
lshw -class disk -class storage
hdparm doesn't work.
When smartctl was tried there was a kernel iSCSI target abort task on the target/initiator.