Difference between revisions of "Open-iSCSI"

From ArchWiki
Jump to navigation Jump to search
("Configuration" Section, to be more consistent with other articles)
m (add an example to add node manually (without discovery))
 
(33 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 
[[Category:Storage]]
 
[[Category:Storage]]
 
[[Category:Networking]]
 
[[Category:Networking]]
{{Related articles start}}
+
[[ja:ISCSI イニシエータ]]
{{Related|iSCSI Target}}
+
[[zh-hans:ISCSI initiator]]
{{Related|iSCSI Boot}}
+
This article describes how to access an [[iSCSI]] target with the [https://github.com/open-iscsi/open-iscsi Open-iSCSI] initiator.
{{Related articles end}}
+
{{Note|ISCSI is NOT encrypted. Transmitting data over unsecured channel is not recommended.}}
  
With [[Wikipedia:iSCSI]] you can access storage over an IP-based network.
+
== Installation ==
 
 
The exported storage entity is the '''[[iSCSI Target|target]]''' and the importing entity is the '''initiator'''.
 
 
 
This article describes how to access an iSCSI target with the [http://open-iscsi.org/ Open-iSCSI] initiator.
 
  
== Installation ==
+
[[Install]] the {{Pkg|open-iscsi}} package from the [[official repositories]].
[[pacman|Install]] the {{Pkg|open-iscsi}} package from the [[official repositories]].
 
  
 
{{Note|An older initiator, [http://sourceforge.net/projects/linux-iscsi/ Linux-iSCSI], was merged with Open-iSCSI in April 2005.
 
{{Note|An older initiator, [http://sourceforge.net/projects/linux-iscsi/ Linux-iSCSI], was merged with Open-iSCSI in April 2005.
Line 19: Line 14:
  
 
== Overview ==
 
== Overview ==
The following diagram shows how the Components work together. A more detailed version can be found here: [http://www.open-iscsi.org/docs/open-iscsi-0.jpg Open-iSCSI modules]
+
 
{{bc|<nowiki>
+
The following diagram shows how the Components work together. A more detailed version can be found here: [https://archive.is/HHYKR/90a7a1c178a2c069a7cbc0b578b6fb5854f827fa.jpg Open-iSCSI modules (Outdated)]
  +-------------------------------------------------------+             
+
 
  | Targets & Sessions configuration Database (DBM based) |             
+
{{Text art|<nowiki>
  +-------------------------------------------------------+             
+
  +--------------------------------------------------------+             
 +
  | Targets & Sessions configuration files and directories |             
 +
  +--------------------------------------------------------+             
 
                                                                        
 
                                                                        
 
  +--------------------------+    +----------------------------------+  
 
  +--------------------------+    +----------------------------------+  
Line 41: Line 38:
 
</nowiki>}}
 
</nowiki>}}
  
From the Open-iSCSI [http://www.open-iscsi.org/docs/README README]:
+
From the Open-iSCSI [https://github.com/open-iscsi/open-iscsi README]:
 +
 
 +
Persistent configuration is implemented as a tree of files and directories, which are contained in two directories:
  
Persistent configuration is implemented as a DBM database, which contains two tables:
+
* Discovery directory {{ic|/etc/iscsi/send_targets}} which has directories named after target addresses.
* Discovery table (/etc/iscsi/send_targets)
+
* Node directory {{ic|/etc/iscsi/nodes}} which has directories named after IQN (ISCSI Unique Name) of particular device.
* Node table (/etc/iscsi/nodes)
 
  
 
== Configuration ==
 
== Configuration ==
 +
 
=== Start the Service ===
 
=== Start the Service ===
 +
 
{{ic|iscsid}} is managed by a systemd Unit.
 
{{ic|iscsid}} is managed by a systemd Unit.
  
Start {{ic|open-iscsi.service}} [[systemd#Using units|using systemd]].  
+
[[Start]] {{ic|iscsid.service}} or {{ic|iscsid.socket}}.
 +
 
 +
=== ISCSI Qualified Name (IQN) ===
  
{{Out of date|The following advice about /etc/conf.d/open-iscsi might be out of date, see discussion page}}  
+
IQN is used for identifying every device.
You only have to include the IP of the [[iSCSI Target|target]] as {{ic|SERVER}} in {{ic|/etc/conf.d/open-iscsi}} at the client.
+
 
 +
Open-ISCSI stores its initiator IQN in the {{ic|/etc/iscsi/initiatorname.iscsi}} file with a format {{ic|1=InitiatorName=''iqn''}}
 +
 
 +
During installation the initial IQN will be generated. If you wish to generate new IQN the {{ic|iscsi-iname}} utility can be used which prints out new IQN.
 +
 
 +
=== Authentication ===
 +
 
 +
If the ISCSI target requires authentication by the initiator, the configuration file {{ic|/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 won't) 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. }}
  
 
=== Target discovery ===
 
=== Target discovery ===
{{bc|# iscsiadm -m discovery -t sendtargets -p <portalip>}}
+
 
 +
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 ===
 
=== Delete obsolete targets ===
{{bc|# iscsiadm -m discovery -p <portalip> -o delete}}
+
 
 +
# iscsiadm -m discovery -p ''target_ip'' -o delete
  
 
=== Login to available targets ===
 
=== Login to available targets ===
{{bc|# iscsiadm -m node -L all}}
+
 
 +
# iscsiadm -m node -L all
 +
 
 
or login to specific target
 
or login to specific target
{{bc|<nowiki># iscsiadm -m node --targetname=<targetname> --login</nowiki>}}
+
 
 +
# iscsiadm -m node --targetname=''targetname'' --login
  
 
logout:
 
logout:
{{bc|# iscsiadm -m node -U all}}
+
 
 +
# iscsiadm -m node -U all
  
 
=== Info ===
 
=== Info ===
 +
 
For running session
 
For running session
{{bc|# iscsiadm -m session -P 3}}
+
 
 +
# iscsiadm -m session -P 3
 +
 
 
The last line of the above command will show the name of the attached dev e.g
 
The last line of the above command will show the name of the attached dev e.g
{{bc|Attached scsi disk '''sdd''' State: running}}
+
 
 +
Attached scsi disk '''sdd''' State: running
  
 
For the known nodes
 
For the known nodes
{{bc|# iscsiadm -m node}}
+
 
 +
# iscsiadm -m node
  
 
=== Online resize of volumes ===
 
=== 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.
 
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 {{bc|# iscsiadm -m node -R}}
 
# Rescan active nodes in current session {{bc|# iscsiadm -m node -R}}
 
# If you use multipath, you also have to rescan multipath volume information. {{bc|# multipathd -k"resize map sdx"}}
 
# If you use multipath, you also have to rescan multipath volume information. {{bc|# multipathd -k"resize map sdx"}}
Line 85: Line 143:
  
 
== Tips & Troubleshooting ==
 
== Tips & Troubleshooting ==
 +
 +
{{Style|Nonstandard section, see [[Help:Style#Standard sections]]. Create proper [[#Tips and tricks]] and [[#Troubleshooting]] sections and place each issue in a separate subsection.}}
 +
 
You can also check where the attached iSCSI devices are located in the /dev tree with {{ic|ls -lh /dev/disk/by-path/* | grep ip}}.
 
You can also check where the attached iSCSI devices are located in the /dev tree with {{ic|ls -lh /dev/disk/by-path/* | grep ip}}.
  
Line 90: Line 151:
  
 
Many of the {{ic|iscsiadm}} operations require that the iSCSI daemon {{ic|iscsid}} is running. To verify that this is the case,  
 
Many of the {{ic|iscsiadm}} operations require that the iSCSI daemon {{ic|iscsid}} is running. To verify that this is the case,  
[[systemd#Using units|check the status]] of the {{ic|open-iscsi.service}}.
+
[[systemd#Using units|check the status]] of the {{ic|iscsid.service}}.
 +
 
 +
To run the iSCSI daemon in debug mode (make sure you stopped {{ic|iscsid.service}} before)
  
== See also ==
+
# iscsid -d 8 -c /etc/iscsi/iscsid.conf -i /etc/iscsi/initiatorname.iscsi -f
* [[iSCSI Boot]] Booting Arch Linux with / on an iSCSI target.
 

Latest revision as of 07:40, 14 September 2019

This article describes how to access an iSCSI target with the Open-iSCSI initiator.

Note: ISCSI is NOT encrypted. Transmitting data over unsecured channel is not recommended.

Installation

Install the open-iscsi package from the official repositories.

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. A more detailed version can be found here: Open-iSCSI modules (Outdated)

 +--------------------------------------------------------+             
 | 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:

  • Discovery directory /etc/iscsi/send_targets which has directories named after target addresses.
  • Node directory /etc/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 won't) 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.

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

  1. Rescan active nodes in current session
    # iscsiadm -m node -R
  2. If you use multipath, you also have to rescan multipath volume information.
    # multipathd -k"resize map sdx"
  3. Finally resize the filesystem.
    # resize2fs /dev/sdx

Tips & Troubleshooting

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: Nonstandard section, see Help:Style#Standard sections. Create proper #Tips and tricks and #Troubleshooting sections and place each issue in a separate subsection. (Discuss in Talk:Open-iSCSI#)

You can also check where the attached iSCSI devices are located in the /dev tree with ls -lh /dev/disk/by-path/* .

At the server (target) you might need to include the client iqn from /etc/iscsi/initiatorname.iscsi in the acl configuration.

Many of the iscsiadm operations require that the iSCSI daemon iscsid is running. To verify that this is the case, check the status of the iscsid.service.

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