Open-iSCSI

This article describes how to access an
iSCSI
target with the
Open-iSCSI
initiator.
Note
iSCSI is
not
encrypted. Transmitting data over an unsecured channel is not recommended.
Installation
Install
the
open-iscsi
package.
Note
An older initiator,
Linux-iSCSI
, was merged with Open-iSCSI in April 2005. This should not be confused with
linux-iscsi.org
, the website for the LIO
target
.
Overview
The following diagram shows how the Components work together:
+--------------------------------------------------------+             
 | Targets & Sessions configuration files and directories |             
 +--------------------------------------------------------+             

 +--------------------------+     +----------------------------------+ 
 | iscsiadm                 |     | iscsid: iSCSI daemon             | 
 |                          |     |                                  | 
 |  * Command line tool     |<--->|  * Implements Session management | 
 |  * Manages database of   |     |  * Communicates with iscsiadm    | 
 |    sessions and targets  |     |    and iscsi kernel modules      | 
 +--------------------------+     +---------------+------------------+ 
                                                  |                    
 User space                                       |                    
- - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - -
 Kernel                                           v                    
         +-----------------------------------------------------------+ 
         | kernel modules: scsi_transport_iscsi, iscsi_tcp, libiscsi | 
         +-----------------------------------------------------------+
From the Open-iSCSI
README
:
Persistent configuration is implemented as a tree of files and directories, which are contained in two directories:
Note
The database home changed from
/etc/iscsi/
to
/var/lib/iscsi/
in
open-iscsi
2.1.9-2. The migration is not done automatically. Please disconnect targets,
stop
the service, migrate and connect again. Also verify filesystem permissions.
/etc/iscsi/
should only contain
initiatorname.iscsi
and
iscsid.conf
Discovery directory
/var/lib/iscsi/send_targets
which has directories named after target addresses.
Node directory
/var/lib/iscsi/nodes
which has directories named after IQN (ISCSI Unique Name) of particular device.
Configuration
Start the Service
iscsid
is managed by a systemd Unit.
Start
iscsid.service
or
iscsid.socket
.
ISCSI Qualified Name (IQN)
IQN is used for identifying every device.
Open-ISCSI stores its initiator IQN in the
/etc/iscsi/initiatorname.iscsi
file with a format
InitiatorName=
iqn
During installation the initial IQN will be generated. If you wish to generate new IQN the
iscsi-iname
utility can be used which prints out new IQN.
Authentication
If the ISCSI target requires authentication by the initiator, the configuration file
/etc/iscsi/iscsid.conf
may need to be updated.
The following parameters are used for authenticating a login session of an initiator to a target:
node.session.auth.authmethod = CHAP
node.session.auth.username =
initiators_username
node.session.auth.password =
initiators_password
If your target has two-way authentication enabled then those lines also need to be edited:
node.session.auth.username_in =
targets_username
node.session.auth.password_in =
targets_password
If your target requires authentication to get the list of its nodes (most will not) then following lines should be edited:
discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username =
initiators_username
discovery.sendtargets.auth.password =
initiators_password
If your target has two-way authentication enabled then those lines also need to be edited:
discovery.sendtargets.auth.username_in =
targets_username
discovery.sendtargets.auth.password_in =
targets_password
Warning
No two passwords may be the same. This means that you need four unique passwords in the configuration above.
Note
The authentication data is saved in per-node configuration files. To update them, edit
/var/lib/iscsi/nodes/iqn.
node-name
/
node-ip-address
,
port
,1/default
and add/adjust the options as necessary.
[1]
Target discovery
Request the target its nodes.
# iscsiadm --mode discovery --portal
target_ip
--type sendtargets
On success information about nodes and target will be saved on your initiator.
Add target manually
# iscsiadm -m node --target
targetname
--portal
target_ip
-o new
A possible scenario to use this is when server does not allow discovery.
Delete obsolete targets
# iscsiadm -m discovery -p
target_ip
-o delete
Login to available targets
# iscsiadm -m node -L all
or login to specific target
# iscsiadm -m node --targetname=
targetname
--login
logout:
# iscsiadm -m node -U all
Info
For running session
# iscsiadm -m session -P 3
The last line of the above command will show the name of the attached device e.g
Attached scsi disk
sdd
State: running
For the known nodes
# iscsiadm -m node
Online resize of volumes
If the iscsi blockdevice contains a partitiontable, you will not be able to do an online resize. In this case you have to unmount the filesystem and alter the size of the affected partition.
Rescan active nodes in current session
# iscsiadm -m node -R
If you use multipath, you also have to rescan multipath volume information.
# multipathd -k"resize map sdx"
Finally resize the filesystem.
# resize2fs /dev/sdx
Tips and tricks
Check for attached iSCSI devices
You can also check where the attached iSCSI devices are located in the
/dev/
tree with:
$ ls -l /dev/disk/by-path/ip-*
Login to targets on boot
To log in to a target during boot,
enable
iscsi.service
and make sure the nodes have
node.startup = automatic
in their configuration (
/var/lib/iscsi/nodes/iqn.
node-name
/
node-ip-address
,
port
).
Note
The systemd unit name  is
iscsi.service
not
iscsi
d
.service
.
[2]
Troubleshooting
Client IQN
At the server (target) you might need to include the client IQN from
/etc/iscsi/initiatorname.iscsi
in the account configuration.
Debugging the iSCSI daemon
To run the iSCSI daemon in debug mode (make sure you stopped
iscsid.service
before)
# iscsid -d 8 -c /etc/iscsi/iscsid.conf -i /etc/iscsi/initiatorname.iscsi -f