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.




The initiator is is the client side of the iSCSI system, the consumer of storage presented by the iSCSI 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.


We start with several assumptions:

  1. You have a modest knowledge of Linux servers and networking.

  2. You have already installed Debian 9 Stretch on at least two (2) hosts, one for the initiator and one as the target.

  3. You have SSH access and sudoers/root privileges.

  4. Your target host contains two physical disks (/dev/sda and /dev/sdb, where /dev/sdb will be the storage node).

  5. You are using the following hostnames and IP addresses:
hostname IP Address

Setup Process (General)

  1. Connect to the target host (via ssh).

  2. Become root by executing sudo su -.

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

  4. Next connect, login and become root again (see steps 1-2).

  5. Install some basic packages on both the target and initiator hosts:

apt-get install net-tools nano -y

Setup: Target

  1. Format the /dev/sdb device: mkfs.ext3 /dev/sdb

  2. Next Mount the device: mount /dev/sdb /mnt

  3. Install TGTD (the iSCSI server). apt-get install tgt -y

  4. 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
    backing-store /dev/sdb
    incominguser incomingusername passsword
    outgoinguser outgoingusername mysecretpassword
  1. 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.

  2. Next restart tgt by executing service tgt restart

  3. 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:
    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:
        outgoingusername (outgoing)
    ACL information:

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

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

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

  2. Next discover the target:

root@initiator:~# iscsiadm -m discovery -t st -p,1

This creates a configuration file:

root@initiator:~# ls -la /etc/iscsi/nodes/\:lun0/\,3260\,1/default
-rw------- 1 root root 2073 Dec 31 14:42 /etc/iscsi/nodes/,3260,1/default

The contents of this file look like this...

root@initiator:~# cat /etc/iscsi/nodes/\:lun0/\,3260\,1/default
# BEGIN RECORD 2.0-874 =
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 =
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 =
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

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

  1. Append the authentication information to the file:
sed -i -e '/#\ END\ RECORD/d' /etc/iscsi/nodes/\:lun0/\,3260\,1/default

cat >> /etc/iscsi/nodes/\:lun0/\,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
  1. Next we need to change the startup from manual to automatic:
sed -i -e 's/node.startup = manual/node.startup = automatic/' /etc/iscsi/nodes/\:lun0/\,3260\,1/default
  1. Now you need to restart the iscsi daemon using service open-iscsi restart.

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