iSCSCI setup guide for Debian Linux

Scope and Purpose

To document how to setup an iSCSI service in Debian Linux. The process is similar for Ubuntu Linux.
This document does not cover replication of data between two or more nodes.
This document is limited to iSCSI service setup. It is not a production-quality setup, and it does not cover storage concerns such as RAID, LVM or other areas you probably want to consider as you evolve toward production.

Definitions

Initiator

The initiator is is the client side of the iSCSI system, the consumer of storage presented by the iSCSI target.

Target

The target is the storage (server) side. Usually iSCSI is presented by SAN hardware. But in other cases, you can build your own storage area network (SAN) using Linux. This is great for home or business use. Years ago, I was able to create a really large, low-cost storage system using the same technologies presented here. It's been in production for ten (10) years now as the backend of a very large database.

Assumptions

We start with several assumptions:

You have a modest knowledge of Linux servers and networking.
You have already installed Debian 9 Stretch on at least two (2) hosts, one for the initiator and one as the target.
You have SSH access and sudoers/root privileges.
Your target host contains two physical disks (/dev/sda and /dev/sdb, where /dev/sdb will be the storage node).
You are using the following hostnames and IP addresses:

hostname	IP Address
Target	192.168.0.105
Initiator	192.168.0.103

Setup Process (General)

Connect to the target host (via ssh).
Become root by executing sudo su -.
Update the system using apt-get update -y --fix-missing && apt-get upgrade -y && shutdown -r now. This will update packages on the host, upgrade the system then reboot if no errors occur.
Next connect, login and become root again (see steps 1-2).
Install some basic packages on both the target and initiator hosts:

apt-get install net-tools nano -y

Setup: Target

Format the /dev/sdb device: mkfs.ext3 /dev/sdb
Next Mount the device: mount /dev/sdb /mnt
Install TGTD (the iSCSI server). apt-get install tgt -y
Next we need to configure our iSCSI targets. These are found in /etc/tgt/conf.d/ and they are consumed by /etc/tgt/targets.conf. The following is an example (/etc/tgt/conf.d/tgt_lun0.conf):

cat > /etc/tgt/conf.d/tgt_lun0.conf << EOF_LUN0_CONF
<target iqn.2010-09.samcaldwell.net:lun0>
    backing-store /dev/sdb
    initiator-address 192.168.0.103
    incominguser incomingusername passsword
    outgoinguser outgoingusername mysecretpassword
</target>
EOF_LUN0_CONF

Note that in the above that we have two clear text credentials. This is obviously insecure and should not be done in production. However this is a discussion beyond the scope of this document.
Next restart tgt by executing service tgt restart
Now you should be able to use tgtadm --mode target --op show and view the iSCSI target:

root@target:~# tgtadm --mode target --op show
Target 1: iqn.2010-09.samcaldwell.net:lun0
    System information:
        Driver: iscsi
        State: ready
    I_T nexus information:
    LUN information:
        LUN: 0
            Type: controller
            SCSI ID: IET     00010000
            SCSI SN: beaf10
            Size: 0 MB, Block size: 1
            Online: Yes
            Removable media: No
            Prevent removal: No
            Readonly: No
            SWP: No
            Thin-provisioning: No
            Backing store type: null
            Backing store path: None
            Backing store flags:
    Account information:
        incomingusername
        outgoingusername (outgoing)
    ACL information:
        192.168.0.103

We now have a working iSCSI target. We can reach this target from the initiator at 192.168.0.103.

WARNING: Be careful here when evolving your setup toward production. There is very little security in this setup. I would recommend that any initiator-target iSCSI connections be secured via IPSEC or TLS VPN connections.

Setup: Initiator

On the intiator machine, install the iSCSI software: apt-get install open-iscsi -y.
Next discover the target:

root@initiator:~# iscsiadm -m discovery -t st -p 192.168.0.105
192.168.0.105:3260,1 iqn.2010-09.samcaldwell.net:lun0

This creates a configuration file:

root@initiator:~# ls -la /etc/iscsi/nodes/iqn.2010-09.samcaldwell.net\:lun0/192.168.0.105\,3260\,1/default
-rw------- 1 root root 2073 Dec 31 14:42 /etc/iscsi/nodes/iqn.2010-09.samcaldwell.net:lun0/192.168.0.105,3260,1/default
root@initiator:~#

The contents of this file look like this...

root@initiator:~# cat /etc/iscsi/nodes/iqn.2010-09.samcaldwell.net\:lun0/192.168.0.105\,3260\,1/default
# BEGIN RECORD 2.0-874
node.name = iqn.2010-09.samcaldwell.net:lun0
node.tpgt = 1
node.startup = manual
node.leading_login = No
iface.iscsi_ifacename = default
iface.transport_name = tcp
iface.vlan_id = 0
iface.vlan_priority = 0
iface.iface_num = 0
iface.mtu = 0
iface.port = 0
iface.tos = 0
iface.ttl = 0
iface.tcp_wsf = 0
iface.tcp_timer_scale = 0
iface.def_task_mgmt_timeout = 0
iface.erl = 0
iface.max_receive_data_len = 0
iface.first_burst_len = 0
iface.max_outstanding_r2t = 0
iface.max_burst_len = 0
node.discovery_address = 192.168.0.105
node.discovery_port = 3260
node.discovery_type = send_targets
node.session.initial_cmdsn = 0
node.session.initial_login_retry_max = 8
node.session.xmit_thread_priority = -20
node.session.cmds_max = 128
node.session.queue_depth = 32
node.session.nr_sessions = 1
node.session.auth.authmethod = None
node.session.timeo.replacement_timeout = 120
node.session.err_timeo.abort_timeout = 15
node.session.err_timeo.lu_reset_timeout = 30
node.session.err_timeo.tgt_reset_timeout = 30
node.session.err_timeo.host_reset_timeout = 60
node.session.iscsi.FastAbort = Yes
node.session.iscsi.InitialR2T = No
node.session.iscsi.ImmediateData = Yes
node.session.iscsi.FirstBurstLength = 262144
node.session.iscsi.MaxBurstLength = 16776192
node.session.iscsi.DefaultTime2Retain = 0
node.session.iscsi.DefaultTime2Wait = 2
node.session.iscsi.MaxConnections = 1
node.session.iscsi.MaxOutstandingR2T = 1
node.session.iscsi.ERL = 0
node.conn[0].address = 192.168.0.105
node.conn[0].port = 3260
node.conn[0].startup = manual
node.conn[0].tcp.window_size = 524288
node.conn[0].tcp.type_of_service = 0
node.conn[0].timeo.logout_timeout = 15
node.conn[0].timeo.login_timeout = 15
node.conn[0].timeo.auth_timeout = 45
node.conn[0].timeo.noop_out_interval = 5
node.conn[0].timeo.noop_out_timeout = 5
node.conn[0].iscsi.MaxXmitDataSegmentLength = 0
node.conn[0].iscsi.MaxRecvDataSegmentLength = 262144
node.conn[0].iscsi.HeaderDigest = None
node.conn[0].iscsi.DataDigest = None
node.conn[0].iscsi.IFMarker = No
node.conn[0].iscsi.OFMarker = No
# END RECORD
root@initiator:~#

But there is no authentication information in this file. That part you'll need to add.

Append the authentication information to the file:

sed -i -e '/#\ END\ RECORD/d' /etc/iscsi/nodes/iqn.2010-09.samcaldwell.net\:lun0/192.168.0.105\,3260\,1/default

cat >> /etc/iscsi/nodes/iqn.2010-09.samcaldwell.net\:lun0/192.168.0.105\,3260\,1/default << EOF_ISCI_CONF
node.session.auth.authmethod = CHAP                    #Enable CHAP Authentication
node.session.auth.username = incomingusername          #Target to Initiator authentication
node.session.auth.password = password                  #Target to Initiator authentication
node.session.auth.username_in = outgoingusername       #Initiator to Target authentication
node.session.auth.password_in = mysecretpassword       #Initiator to Target authentication
# END RECORD
EOF_ISCI_CONF

Next we need to change the startup from manual to automatic:

sed -i -e 's/node.startup = manual/node.startup = automatic/' /etc/iscsi/nodes/iqn.2010-09.samcaldwell.net\:lun0/192.168.0.105\,3260\,1/default

Now you need to restart the iscsi daemon using service open-iscsi restart.
You should be able to use lsblk to see a new block device on your system (which may appear as /dev/sdb--though the device name will not necessarily have anything to do with the device name on the target host). You can now treat this as you would any SAN storage.

Troubleshooting commands

See active connections

from initiatoriscsiadm -m session

From target: tgtadm --mode conn --op show --tid 1

samcaldwell.net A Blog site about scotch, tech and hacking. ...often at the same time.

iSCSCI setup guide for Debian Linux

Scope and Purpose

Related

Definitions

Initiator

Target

Assumptions

Setup Process (General)

Setup: Target

Setup: Initiator

Troubleshooting commands

See active connections

Scope and Purpose

Related

Definitions

Initiator

Target

Assumptions

Setup Process (General)

Setup: Target

Setup: Initiator

Troubleshooting commands

See active connections

social