Open-iSCSI: Difference between revisions
("Configuration" Section, to be more consistent with other articles) |
m (→Overview: style) |
||
(53 intermediate revisions by 18 users not shown) | |||
Line 1: | Line 1: | ||
[[Category:Storage]] | [[Category:Storage]] | ||
[[Category:Networking]] | [[Category:Networking]] | ||
[[ja:Open-iSCSI]] | |||
[[zh-hans:Open-iSCSI]] | |||
This article describes how to access an [[iSCSI]] target with the [https://github.com/open-iscsi/open-iscsi Open-iSCSI] initiator. | |||
{{Note|iSCSI is '''not''' encrypted. Transmitting data over an unsecured channel is not recommended.}} | |||
== Installation == | |||
[[Install]] the {{Pkg|open-iscsi}} package. | |||
This | {{Note|An older initiator, [https://sourceforge.net/projects/linux-iscsi/ Linux-iSCSI], was merged with Open-iSCSI in April 2005. This should not be confused with [http://linux-iscsi.org/ linux-iscsi.org], the website for the LIO [[iSCSI Target|target]].}} | ||
== | == Overview == | ||
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)] | |||
{{Text art|<nowiki> | |||
+--------------------------------------------------------+ | |||
{{ | | Targets & Sessions configuration files and directories | | ||
+-------------------------------------------------------+ | +--------------------------------------------------------+ | ||
| Targets & Sessions configuration | |||
+-------------------------------------------------------+ | |||
+--------------------------+ +----------------------------------+ | +--------------------------+ +----------------------------------+ | ||
Line 41: | Line 38: | ||
</nowiki>}} | </nowiki>}} | ||
From the Open-iSCSI [ | 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: | |||
{{Note|The database home changed from {{ic|/etc/iscsi/}} to {{ic|/var/lib/iscsi/}} in {{Pkg|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. | |||
{{ic|/etc/iscsi/}} should only contain {{ic|initiatorname.iscsi}} and {{ic|iscsid.conf}} | |||
}} | |||
* Discovery directory {{ic|/var/lib/iscsi/send_targets}} which has directories named after target addresses. | |||
* Discovery | * Node directory {{ic|/var/lib/iscsi/nodes}} which has directories named after IQN (ISCSI Unique Name) of particular device. | ||
* Node | |||
== 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| | [[Start]] {{ic|iscsid.service}} or {{ic|iscsid.socket}}. | ||
{{ | === ISCSI Qualified Name (IQN) === | ||
IQN is used for identifying every device. | |||
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 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 {{ic|/var/lib/iscsi/nodes/iqn.''node-name''/''node-ip-address'',''port'',1/default}} and add/adjust the options as necessary.[https://serverfault.com/a/790835]}} | |||
=== Target discovery === | === 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 === | === Delete obsolete targets === | ||
# iscsiadm -m discovery -p ''target_ip'' -o delete | |||
=== Login to available targets === | === Login to available targets === | ||
# iscsiadm -m node -L all | |||
or login to specific target | or login to specific target | ||
# iscsiadm -m node --targetname=''targetname'' --login | |||
logout: | logout: | ||
# iscsiadm -m node -U all | |||
=== Info === | === Info === | ||
For running session | For running session | ||
The last line of the above command will show the name of the attached | # 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 | For the known nodes | ||
# 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"}} | ||
# Finally resize the filesystem. {{bc|# resize2fs /dev/sdx}} | # Finally resize the filesystem. {{bc|# resize2fs /dev/sdx}} | ||
== Tips | == Tips and tricks == | ||
You can also check where the attached iSCSI devices are located in the /dev tree with | |||
=== Check for attached iSCSI devices === | |||
You can also check where the attached iSCSI devices are located in the {{ic|/dev/}} tree with: | |||
$ ls -l /dev/disk/by-path/ip-* | |||
=== Login to targets on boot === | |||
To log in to a target during boot, [[enable]] {{ic|iscsi.service}} and make sure the nodes have {{ic|1=node.startup = automatic}} in their configuration ({{ic|/var/lib/iscsi/nodes/iqn.''node-name''/''node-ip-address'',''port''}}). | |||
{{Note|1=The systemd unit name is {{ic|iscsi.service}} not {{ic|iscsi'''d'''.service}}.[https://bbs.archlinux.org/viewtopic.php?pid=1961776#p1961776]}} | |||
== Troubleshooting == | |||
=== Client IQN === | |||
At the server (target) you might need to include the client IQN from {{ic|/etc/iscsi/initiatorname.iscsi}} in the account configuration. | |||
=== Debugging the iSCSI daemon === | |||
To run the iSCSI daemon in debug mode (make sure you stopped {{ic|iscsid.service}} before) | |||
# iscsid -d 8 -c /etc/iscsi/iscsid.conf -i /etc/iscsi/initiatorname.iscsi -f | |||
Latest revision as of 17:39, 20 June 2023
This article describes how to access an iSCSI target with the Open-iSCSI initiator.
Installation
Install the open-iscsi package.
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:
/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
/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
).
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