Difference between revisions of "ISCSI/LIO"

From ArchWiki
Jump to navigation Jump to search
m
 
(16 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[zh-cn:ISCSI Target]]
 
 
[[Category:Storage]]
 
[[Category:Storage]]
 
[[Category:Networking]]
 
[[Category:Networking]]
{{Related articles start}}
+
[[ja:ISCSI ターゲット]]
{{Related|iSCSI Initiator}}
+
[[zh-hans:ISCSI Target]]
{{Related|iSCSI Boot}}
+
[http://linux-iscsi.org/ LIO] (LinuxIO) is the in-kernel [[iSCSI]] target (since Linux 2.6.38).
{{Related articles end}}
 
With [[Wikipedia:iSCSI|iSCSI]] you can access storage over an IP-based network.
 
  
The exported storage entity is the '''target''' and the importing entity is the '''[[iSCSI Initiator|initiator]]'''. There are different modules available to set up the target:
+
== Installation ==
* The [http://stgt.berlios.de/ SCSI Target Framework (STGT/TGT)] was the standard before linux 2.6.38.
+
The iSCSI target fabric is included since Linux 3.1.
* The current standard is the [http://linux-iscsi.org/ LIO target].
 
* The [http://iscsitarget.sourceforge.net/ iSCSI Enterprise Target (IET)] is an old implementation and [http://scst.sourceforge.net/ SCSI Target Subsystem (SCST)] is the successor of IET and was a possible candidate for kernel inclusion before the decision fell for LIO.
 
 
 
== Setup with LIO Target ==
 
LIO target is included in the kernel since 2.6.38. However, the iSCSI target fabric is included since linux 3.1.
 
  
 
The important kernel modules are ''target_core_mod'' and ''iscsi_target_mod'', which should be in the kernel and loaded automatically.
 
The important kernel modules are ''target_core_mod'' and ''iscsi_target_mod'', which should be in the kernel and loaded automatically.
  
It is highly recommended to use the free branch versions of the packages: {{AUR|targetcli-fb}}, {{AUR|python-rtslib-fb}} and {{AUR|python-configshell-fb}}. The original {{AUR|targetcli}} is also available but has a different way of saving the configuration using the deprecated ''lio-utils'' and depends on ''epydoc''.
+
It is highly recommended to use the free branch versions of the packages: {{AUR|targetcli-fb}}, {{AUR|python-rtslib-fb}} and {{AUR|python-configshell-fb}}.
 
 
A systemd {{ic|target.service}} is included in {{AUR|python-rtslib-fb}} when you use the free branch and a {{ic|/etc/rc.d/target}} in {{AUR|lio-utils}} when you use the original ''targetcli'' or ''lio-utils'' directly.
 
 
 
You start LIO target with {{bc|# systemctl start target}}
 
This will load necessary modules, mount the configfs and load previously saved iscsi target configuration.
 
  
With {{bc|# targetcli status}} you can show some information about the running configuration (only with the free branch).
+
[[Start/enable]] the {{ic|target.service}}, included in {{AUR|python-rtslib-fb}}, to load necessary modules, mount the configfs and load previously saved iSCSI target configuration.
  
You might want to enable the lio target on boot with {{bc|# systemctl enable target}}
+
== targetcli ==
  
You can use '''targetcli''' to create the whole configuration or you can alternatively use the '''lio utils''' tcm_* and lio_* directly (deprecated).
+
Run {{ic|targetcli status}} as [[root user|root]] to see some information about the running configuration.
  
=== Using targetcli ===
+
You can use '''targetcli''' to create the whole configuration, see {{man|8|targetcli|url=}}.
The external manual is only available in the ''free branch''. [https://github.com/agrover/targetd targetd] is not in AUR yet, but this depends on the free branch.
 
  
 
The config shell creates most names and numbers for you automatically, but you can also provide your own settings.
 
The config shell creates most names and numbers for you automatically, but you can also provide your own settings.
 
At any point in the shell you can type {{ic|help}} in order to see what commands you can issue here.
 
At any point in the shell you can type {{ic|help}} in order to see what commands you can issue here.
{{Tip|You can use tab-completion in this shell}}
+
 
{{Tip|You can type {{ic|cd}} in this shell to view & select paths}}
+
{{Tip|In this shell you can use tab-completion and type {{ic|cd}} to view & select paths.}}
  
 
After starting the target (see above) you enter the configuration shell with {{bc|# targetcli}}
 
After starting the target (see above) you enter the configuration shell with {{bc|# targetcli}}
 
In this shell you include a block device (here: {{ic|/dev/disk/by-id/md-name-nas:iscsi}}) to use with
 
In this shell you include a block device (here: {{ic|/dev/disk/by-id/md-name-nas:iscsi}}) to use with
{{bc|/> cd backstores/block<br>/backstores/block> create md_block0 /dev/disk/by-id/md-name-nas:iscsi}}
 
{{Note|You can use any block device, also raid and lvm devices. You can also use files when you go to fileio instead of block.}}
 
  
You then create an iSCSI Qualified Name (iqn) and a target portal group (tpg) with {{bc|...> cd /iscsi<br>/iscsi> create}}
+
/> cd backstores/block
{{Note|With appending an iqn of your choice to {{ic|create}} you can keep targetcli from automatically creating an iqn}}
+
/backstores/block> create md_block0 /dev/disk/by-id/md-name-nas:iscsi
 +
 
 +
{{Note|You can use any block device, also RAID and LVM devices. You can also use files when you go to fileio instead of block.}}
 +
 
 +
You then create an iSCSI Qualified Name (IQN) and a target portal group (TPG) with:
 +
 
 +
...> cd /iscsi
 +
/iscsi> create
 +
 
 +
{{Note|With appending an IQN of your choice to {{ic|create}} you can keep targetcli from automatically creating an IQN.}}
  
 
In order to tell LIO that your block device should get used as ''backstore'' for the target you issue
 
In order to tell LIO that your block device should get used as ''backstore'' for the target you issue
 +
 
{{Note|Remember that you can type {{ic|cd}} to select the path of your <iqn>/tpg1}}
 
{{Note|Remember that you can type {{ic|cd}} to select the path of your <iqn>/tpg1}}
{{bc|.../tpg1> cd luns<br>.../tpg1/luns> create /backstores/block/md_block0}}
+
 
 +
.../tpg1> cd luns
 +
.../tpg1/luns> create /backstores/block/md_block0
  
 
Then you need to create a ''portal'', making a daemon listen for incoming connections:
 
Then you need to create a ''portal'', making a daemon listen for incoming connections:
{{bc|.../luns/lun0> cd ../../portals<br>.../portals> create}}
+
 
 +
.../luns/lun0> cd ../../portals
 +
.../portals> create
 +
 
 
Targetcli will tell you the IP and port where LIO is listening for incoming connections (defaults to 0.0.0.0 (all)).
 
Targetcli will tell you the IP and port where LIO is listening for incoming connections (defaults to 0.0.0.0 (all)).
 
You will need at least the IP for the clients. The port should be the standard port 3260.
 
You will need at least the IP for the clients. The port should be the standard port 3260.
  
In order for a client/[[iSCSI Initiator|initiator]] to connect you need to include the iqn of the initiator in the target configuration:
+
In order for a client/[[iSCSI Initiator|initiator]] to connect you need to include the IQN of the initiator in the target configuration:
{{bc|...> cd ../../acls<br>.../acls> create iqn.2005-03.org.open-iscsi:SERIAL}}
+
 
Instead of {{ic|iqn.2005-03.org.open-iscsi:SERIAL}} you use the iqn of an initiator.
+
...> cd ../../acls
 +
.../acls> create iqn.2005-03.org.open-iscsi:SERIAL
 +
 
 +
Instead of {{ic|iqn.2005-03.org.open-iscsi:SERIAL}} you use the IQN of an initiator.
 
It can normally be found in {{ic|/etc/iscsi/initiatorname.iscsi}}.
 
It can normally be found in {{ic|/etc/iscsi/initiatorname.iscsi}}.
 
You have to do this for every initiator that needs to connect.
 
You have to do this for every initiator that needs to connect.
Targetcli will automatically map the created lun to the newly created acl.
+
Targetcli will automatically map the created LUN to the newly created ACL.
{{Note|You can change the mapped luns and whether the access should be rw or ro. See {{ic|help create}} at this point in the targetcli shell.}}
+
 
 +
{{Note|You can change the mapped LUNs and whether the access should be rw or ro. See {{ic|help create}} at this point in the targetcli shell.}}
  
 
The last thing you have to do in targetcli when everything works is saving the configuration with:
 
The last thing you have to do in targetcli when everything works is saving the configuration with:
 +
 
  ...> cd /
 
  ...> cd /
 
  /> saveconfig
 
  /> saveconfig
 +
 
The will the configuration in {{ic|/etc/target/saveconfig.json}}.
 
The will the configuration in {{ic|/etc/target/saveconfig.json}}.
 
You can now safely start and stop {{ic|target.service}} without losing your configuration.
 
You can now safely start and stop {{ic|target.service}} without losing your configuration.
{{Tip|You can give a filename as a parameter to {{ic|saveconfig}} and also clear a configuration with {{ic|clearconfig}}}}
+
{{Tip|You can give a filename as a parameter to {{ic|saveconfig}} and also clear a configuration with {{ic|clearconfig}}.}}
 +
 
 +
=== Authentication ===
  
==== Authentication ====
 
 
Authentication per CHAP is enabled per default for your targets.
 
Authentication per CHAP is enabled per default for your targets.
 
You can either setup passwords or disable this authentication.
 
You can either setup passwords or disable this authentication.
  
===== Disable Authentication =====
+
==== Disable Authentication ====
Navigate targetcli to your target (i.e. /iscsi/iqn.../tpg1) and
 
.../tpg1> set attribute authentication=0
 
{{Warning|With this setting everybody that knows the iqn of one of your clients (initiators) can access the target. This is for testing or home purposes only.}}
 
===== Set Credentials =====
 
Navigate to a certain acl of your target (i.e. /iscsi/iqn.../tpg1/acls/iqn.../) and
 
...> get auth
 
will show you the current authentication credentials.
 
...> set auth userid=foo
 
...> set auth password=bar
 
Would enable authentication with foo:bar.
 
  
=== Using (plain) LIO utils ===
+
Navigate targetcli to your target (i.e. /iscsi/iqn.../tpg1) and:
You have to install {{AUR|lio-utils}} from [[AUR]] and the dependencies (python2).
 
  
=== Tips & Tricks ===
+
.../tpg1> set attribute authentication=0
* With {{ic|targetcli sessions}} you can list the current open sessions. This command is included in the {{AUR|targetcli-fb}} package, but not in ''lio-utils'' or the original ''targetcli''.
 
  
=== Upstream Documentation ===
+
{{Warning|With this setting everybody that knows the iqn of one of your clients (initiators) can access the target. This is for testing or home purposes only.}}
* [http://www.linux-iscsi.org/wiki/Targetcli targetcli]
 
* [http://www.linux-iscsi.org/wiki/Lio-utils_HOWTO LIO utils]
 
* You can also use {{ic|man targetcli}} when you installed the ''free branch'' version {{AUR|targetcli-fb}}.
 
  
== Setup with SCSI Target Framework (STGT/TGT) ==
+
==== Set Credentials ====
You will need the Package {{AUR|tgt}} from [[AUR]].
 
  
See: [[TGT iSCSI Target]]
+
Navigate to a certain ACL of your target (i.e. /iscsi/iqn.../tpg1/acls/iqn.../) and
  
== Setup with iSCSI Enterprise Target (IET) ==
+
...> get auth
You will need {{AUR|iscsitarget-kernel}} and {{AUR|iscsitarget-usr}} from [[AUR]].
 
  
=== Create the Target ===
+
will show you the current authentication credentials.
Modify /etc/iet/ietd.conf accordingly
 
  
==== Hard Drive Target ====
+
...> set auth userid=<username in target>
  Target iqn.2010-06.ServerName:desc
+
...> set auth password=<password in target>
  Lun 0 Path=/dev/sdX,Type=blockio
+
  ...> set auth mutual_userid=<username in initiator>  (optional)
 +
  ...> set auth mutual_password=<password in initiator>  (optional)
  
==== File based Target ====
+
The first two fields are the username and password of the target. The initiator will use this to log into the target. The last two fields (prefixed with "mutual_") are the username and password of the initiators (note that all initiators will have the same username and password). These two are optional parameters and it ensures that initiators will only accept connections from permitted targets.
Use "dd" to create a file of the required size, this example is 10GB.
 
  
dd if=/dev/zero of=/root/os.img bs=1G count=10
+
== Tips & Tricks ==
  
Target iqn.2010-06.ServerName:desc
+
* With {{ic|targetcli sessions}} you can list the current open sessions.
Lun 0 Path=/root/os.img,Type=fileio
 
  
=== Start server services ===
+
== See also ==
{{Out of date|Mentions rc.d scripts and rc.conf.}}
 
rc.d start iscsi-target
 
  
Also you can "iscsi-target" to DAEMONS in /etc/rc.conf so that it starts up during boot.
+
* [http://www.linux-iscsi.org/wiki/Targetcli targetcli]
 
 
== See also ==
 
* [[iSCSI Boot]] Booting Arch Linux with / on an iSCSI target.
 
 
* [[Persistent block device naming]] in order to use the correct block device for a target
 
* [[Persistent block device naming]] in order to use the correct block device for a target

Latest revision as of 19:30, 29 September 2018

LIO (LinuxIO) is the in-kernel iSCSI target (since Linux 2.6.38).

Installation

The iSCSI target fabric is included since Linux 3.1.

The important kernel modules are target_core_mod and iscsi_target_mod, which should be in the kernel and loaded automatically.

It is highly recommended to use the free branch versions of the packages: targetcli-fbAUR, python-rtslib-fbAUR and python-configshell-fbAUR.

Start/enable the target.service, included in python-rtslib-fbAUR, to load necessary modules, mount the configfs and load previously saved iSCSI target configuration.

targetcli

Run targetcli status as root to see some information about the running configuration.

You can use targetcli to create the whole configuration, see targetcli(8).

The config shell creates most names and numbers for you automatically, but you can also provide your own settings. At any point in the shell you can type help in order to see what commands you can issue here.

Tip: In this shell you can use tab-completion and type cd to view & select paths.

After starting the target (see above) you enter the configuration shell with

# targetcli

In this shell you include a block device (here: /dev/disk/by-id/md-name-nas:iscsi) to use with

/> cd backstores/block
/backstores/block> create md_block0 /dev/disk/by-id/md-name-nas:iscsi
Note: You can use any block device, also RAID and LVM devices. You can also use files when you go to fileio instead of block.

You then create an iSCSI Qualified Name (IQN) and a target portal group (TPG) with:

...> cd /iscsi
/iscsi> create
Note: With appending an IQN of your choice to create you can keep targetcli from automatically creating an IQN.

In order to tell LIO that your block device should get used as backstore for the target you issue

Note: Remember that you can type cd to select the path of your <iqn>/tpg1
.../tpg1> cd luns
.../tpg1/luns> create /backstores/block/md_block0

Then you need to create a portal, making a daemon listen for incoming connections:

.../luns/lun0> cd ../../portals
.../portals> create

Targetcli will tell you the IP and port where LIO is listening for incoming connections (defaults to 0.0.0.0 (all)). You will need at least the IP for the clients. The port should be the standard port 3260.

In order for a client/initiator to connect you need to include the IQN of the initiator in the target configuration:

...> cd ../../acls
.../acls> create iqn.2005-03.org.open-iscsi:SERIAL

Instead of iqn.2005-03.org.open-iscsi:SERIAL you use the IQN of an initiator. It can normally be found in /etc/iscsi/initiatorname.iscsi. You have to do this for every initiator that needs to connect. Targetcli will automatically map the created LUN to the newly created ACL.

Note: You can change the mapped LUNs and whether the access should be rw or ro. See help create at this point in the targetcli shell.

The last thing you have to do in targetcli when everything works is saving the configuration with:

...> cd /
/> saveconfig

The will the configuration in /etc/target/saveconfig.json. You can now safely start and stop target.service without losing your configuration.

Tip: You can give a filename as a parameter to saveconfig and also clear a configuration with clearconfig.

Authentication

Authentication per CHAP is enabled per default for your targets. You can either setup passwords or disable this authentication.

Disable Authentication

Navigate targetcli to your target (i.e. /iscsi/iqn.../tpg1) and:

.../tpg1> set attribute authentication=0
Warning: With this setting everybody that knows the iqn of one of your clients (initiators) can access the target. This is for testing or home purposes only.

Set Credentials

Navigate to a certain ACL of your target (i.e. /iscsi/iqn.../tpg1/acls/iqn.../) and

...> get auth

will show you the current authentication credentials.

...> set auth userid=<username in target>
...> set auth password=<password in target>
...> set auth mutual_userid=<username in initiator>  (optional)
...> set auth mutual_password=<password in initiator>  (optional)

The first two fields are the username and password of the target. The initiator will use this to log into the target. The last two fields (prefixed with "mutual_") are the username and password of the initiators (note that all initiators will have the same username and password). These two are optional parameters and it ensures that initiators will only accept connections from permitted targets.

Tips & Tricks

  • With targetcli sessions you can list the current open sessions.

See also