From Fedora Project Wiki

(Add a really really quickstart section)
(create sparse file and remove some obsolete stuff)
 
(25 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= About =
{{admon/tip | Specialized hardware is not needed! | You can use this page to run and test the '''scsi-target-utils''' functions without any special hardware, using either physical or virtual machines that share a network.}}
 
== About ==


This page is intended to outline a series of steps need to quickly get a '''scsi-target-utils''' based iSCSI software target working.   
This page is intended to outline a series of steps need to quickly get a '''scsi-target-utils''' based iSCSI software target working.   


Most of these instructions can also be found in a README provided by the scsi-target-utils package (see ''/usr/share/doc/scsi-target-utils-0.9.2/README.iscsi'').
Most of these instructions can also be found in a README provided by the scsi-target-utils package (see {{filename|/usr/share/doc/scsi-target-utils-*/README.iscsi}}).


= Installation =
== Installation ==


Start by installing the '''scsi-target-utils''' package.
Start by installing the {{package|scsi-target-utils}} package using [[dnf|DNF]]:


<pre>
<pre>
# yum install scsi-target-utils
# dnf install scsi-target-utils
</pre>
</pre>


= Configuration =
== Configuration ==


== Firewall ==
=== Firewall ===


Ensure, port 3260 is available for incoming connection and there is no firewall in the way between target and test machine.  
Ensure, port 3260 is available for incoming connection and there is no firewall in the way between target and test machine.  


* Either stop your firewall: <pre># service iptables stop</pre>
* Either stop your firewall: <pre># service iptables stop</pre>
* Or, open up port 3260 for traffic using: <pre># system-config-firewall</pre>
* Or, open up tcp port 3260 for traffic using: <pre># system-config-firewall</pre>
* Or, modify your iptables configuration manually by  
* Or, modify your iptables configuration manually by  
*# editing ''/etc/sysconfig/iptables''  
*# editing ''/etc/sysconfig/iptables''  
*# Then restarting ''iptables'': <pre># service iptables restart</pre>
*# Then restarting ''iptables'': <pre># service iptables restart</pre>


== Backing Store ==
For firewalld:


When configured, the tgtd service will present a block device to iSCSI initiators.  You may use a LVM logical volume, a disk partition, a whole disk, or a loop back partition.  For this document, we will create a ''/dev/loop0'' loop back device.
* <pre>firewall-cmd --zone=FedoraServer --add-service=iscsi-target --permanent</pre>
* <pre>firewall-cmd --reload</pre>


# First, create a 8Gib file: <pre># dd if=/dev/zero of=/tmp/iscsi-disk1 bs=1M count=8000</pre>
=== Backing Store ===
# Next, create a loopback device: <pre># losetup /dev/loop0 /tmp/iscsi-disk1</pre>


== Selinux ==
When configured, the tgtd service will present a block device to iSCSI initiators.  You may use a LVM logical volume, a disk partition, a whole disk, or a file. For production use a LVM logical volume is typically used. For this document, we will create a file.


FIXME - detail any selinux considerations on the target.
# First, create a 8Gib file: <pre># truncate -s 8G /var/tmp/iscsi-disk1</pre>
 
=== Selinux ===
 
<pre>
# semanage fcontext -a -t tgtd_var_lib_t /var/tmp/iscsi-disk1
# restorecon -Rv  /var/tmp/iscsi-disk1
</pre>


== Service startup ==
=== Service startup ===


Configure the tgtd service to start on boot.  Type:
Configure the tgtd service to start on boot.  Type:


<pre>
<pre>
# service tgtd start
# systemctl enable --now tgtd
# chkconfig tgtd on
</pre>
</pre>


= Up and running in 3 steps =
== Up and running in 3 steps ==


For the fastest way to present a target device with 1 logical unit to any initiator ... follow these three steps:
For the fastest way to present a target device with 1 logical unit to any initiator ... follow these three steps:
Line 51: Line 59:
# First, [[#Create_a_new_target_device|create a target device]]
# First, [[#Create_a_new_target_device|create a target device]]
# Next, [[#Add_a_logical_unit|add a logical unit]]
# Next, [[#Add_a_logical_unit|add a logical unit]]
# Finally, [[#Permissions_-_Allow_all_initiators|enable the target to accept initiators]]  
# Finally, [[#Allow_all_initiators|enable the target to accept initiators]]  


That's it!
That's it!


= How to ... =
== How to ... ==


The following sections detail common actions you might perform using the ''tgtadm'' utility with the configuration used above.  All of the following steps are also detailed in the ''README.iscsi'' included in the ''scsi-target-utils'' package.
The following sections detail common actions you might perform using the ''tgtadm'' utility with the configuration used above.  All of the following steps are also detailed in the ''README.iscsi'' included in the ''scsi-target-utils'' package.


== List active targets ==
=== List active targets ===


At any time you can list the active targets by typing: <pre># tgtadm --lld iscsi --op show --mode target</pre>
At any time you can list the active targets by typing: <pre># tgtadm --lld iscsi --mode target --op show</pre>


== Create a new target device ==
=== Create a new target device ===


Create a target device: <pre># tgtadm --lld iscsi --op new --mode target --tid=1 --targetname iqn.2009-02.com.example:for.all</pre>
Create a target device: <pre># tgtadm --lld iscsi --mode target --op new --tid=1 --targetname iqn.2009-02.com.example:for.all</pre>


== Add a logical unit ==
{{Anchor|Add_a_logical_unit}}
=== Add a logical unit (LUN) ===


You can add a logical unit to an existing target device by typing:
You can add a logical unit to an existing target device by typing:


<pre>
<pre>
# tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 -b /dev/loop0
# tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 -b /var/tmp/iscsi-disk1
</pre>
</pre>
{{admon/warning|SELinux note|Note that <code>/var/tmp/iscsi-disk1</code> will need to exist, and have the correct SELinux label, or else you will get an unhelpful "<code>tgtadm: invalid request</code>" error. (See above.)}}


Repeat this process while changing the '''-b''' parameter to add more logical units.
Repeat this process while changing the '''-b''' parameter to add more logical units.


== Permissions - Allow all initiators ==
=== Permissions ===
 
The following sections detail various authentication and restrictions you can enabled using ''tgtadm''.
 
==== List all user accounts ====
 
To display a list of all configured user accounts, type:
<pre># tgtadm --lld iscsi --mode account --op show</pre>
 
{{Anchor|Allow_all_initiators}}
==== Add IP wildcard to allow all initiators ====


<pre>
<pre>
# tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
# tgtadm --lld iscsi --mode target --op bind --tid 1 -I ALL
</pre>
</pre>


== Permissions - IP-based restrictions ==
==== IP-based restrictions ====


If you've previously configured this target to accept '''ALL''' initiators, you'll need to remove that first.
If you've previously configured this target to accept '''ALL''' initiators, you'll need to remove that first.


<pre>
<pre>
# tgtadm --lld iscsi --op unbind --mode target --tid 1 -I ALL
# tgtadm --lld iscsi --mode target --op unbind --tid 1 -I ALL
</pre>
</pre>


Line 94: Line 115:


<pre>
<pre>
# tgtadm --lld iscsi --op bind --mode target --tid 1 -I 10.10.0.24
# tgtadm --lld iscsi --mode target --op bind --tid 1 -I 10.10.0.24
</pre>
</pre>


Line 100: Line 121:


<pre>
<pre>
# tgtadm --lld iscsi --op bind --mode target --tid 1 -I 10.10.0.0/24
# tgtadm --lld iscsi --mode target --op bind --tid 1 -I 10.10.0.0/24
</pre>
</pre>
==== User/Password authentication (CHAP) ====
There are two types of CHAP configurations supported for iSCSI authentication:
{| border=1
|-
! Authentication Type
! A.K.A.
! Description
|- class="alt"
| Initiator Authentication
| Forward, One-Way
| The initiator is authenticated by the target.
|-
| Target Authentication
| Reverse, Bi-directional, Mutual, Two-way
| The target is authenticated by the initiator.  This method also requires Initiator Authentication.
|-
|}
* ''Initiator Authentication'' is basic CHAP authentication.  A username and password is created on the target.  Each initiator logs into the target with this information.
* ''Target Authentication'' is an authentication method in addition to Initiator Authentication.  A separate "outgoing" username is created on the target.  This username/password pair is used by the target to log into each initiator.  Initiator Authentication must also be configured in this scenario.
===== CHAP Initiator Authentication =====
# First, create a user and password: <pre># tgtadm --lld iscsi --mode account --op new --user ''consumer'' --password ''Longsw0rd''</pre>
# Next, add the users to an existing target device: <pre># tgtadm --lld iscsi --mode account --op bind --tid 1 --user ''consumer''</pre>
# On the initiator's system, this username/password information is entered into {{filename|/etc/iscsi/iscsid.conf}} as:
#* For discovery authentication (not supported by tgt yet): ''discovery.sendtargets.auth.{username,password}''
#* For session authentication: ''node.session.auth.{username,password}''
===== CHAP Target Authentication =====
# First, create a user and password: <pre># tgtadm --lld iscsi --mode account --op new --user ''provider'' --password ''Shortsw0rd''</pre>
# Next, add the users to an existing target device: <pre># tgtadm --lld iscsi --mode account --op bind --tid 1 --user ''provider'' --outgoing</pre>
# On the initiator's system, this username/password information is entered into {{filename|/etc/iscsi/iscsid.conf}} as:
#* For discovery authentication (not supported by tgt yet): ''discovery.sendtargets.auth.{username_in,password_in}''
#* For session authentication: ''node.session.auth.{username_in,password_in}''
[[Category:QA|S]]

Latest revision as of 12:55, 12 April 2019

Specialized hardware is not needed!
You can use this page to run and test the scsi-target-utils functions without any special hardware, using either physical or virtual machines that share a network.

About

This page is intended to outline a series of steps need to quickly get a scsi-target-utils based iSCSI software target working.

Most of these instructions can also be found in a README provided by the scsi-target-utils package (see /usr/share/doc/scsi-target-utils-*/README.iscsi).

Installation

Start by installing the scsi-target-utils package using DNF:

# dnf install scsi-target-utils

Configuration

Firewall

Ensure, port 3260 is available for incoming connection and there is no firewall in the way between target and test machine.

  • Either stop your firewall:
    # service iptables stop
  • Or, open up tcp port 3260 for traffic using:
    # system-config-firewall
  • Or, modify your iptables configuration manually by
    1. editing /etc/sysconfig/iptables
    2. Then restarting iptables:
      # service iptables restart

For firewalld:

  • firewall-cmd --zone=FedoraServer --add-service=iscsi-target --permanent
  • firewall-cmd --reload

Backing Store

When configured, the tgtd service will present a block device to iSCSI initiators. You may use a LVM logical volume, a disk partition, a whole disk, or a file. For production use a LVM logical volume is typically used. For this document, we will create a file.

  1. First, create a 8Gib file:
    # truncate -s 8G /var/tmp/iscsi-disk1

Selinux

# semanage fcontext -a -t tgtd_var_lib_t /var/tmp/iscsi-disk1
# restorecon -Rv  /var/tmp/iscsi-disk1

Service startup

Configure the tgtd service to start on boot. Type:

# systemctl enable --now tgtd

Up and running in 3 steps

For the fastest way to present a target device with 1 logical unit to any initiator ... follow these three steps:

  1. First, create a target device
  2. Next, add a logical unit
  3. Finally, enable the target to accept initiators

That's it!

How to ...

The following sections detail common actions you might perform using the tgtadm utility with the configuration used above. All of the following steps are also detailed in the README.iscsi included in the scsi-target-utils package.

List active targets

At any time you can list the active targets by typing:

# tgtadm --lld iscsi --mode target --op show

Create a new target device

Create a target device:

# tgtadm --lld iscsi --mode target --op new --tid=1 --targetname iqn.2009-02.com.example:for.all

Add a logical unit (LUN)

You can add a logical unit to an existing target device by typing:

# tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 -b /var/tmp/iscsi-disk1
SELinux note
Note that /var/tmp/iscsi-disk1 will need to exist, and have the correct SELinux label, or else you will get an unhelpful "tgtadm: invalid request" error. (See above.)

Repeat this process while changing the -b parameter to add more logical units.

Permissions

The following sections detail various authentication and restrictions you can enabled using tgtadm.

List all user accounts

To display a list of all configured user accounts, type:

# tgtadm --lld iscsi --mode account --op show

Add IP wildcard to allow all initiators

# tgtadm --lld iscsi --mode target --op bind --tid 1 -I ALL

IP-based restrictions

If you've previously configured this target to accept ALL initiators, you'll need to remove that first.

# tgtadm --lld iscsi --mode target --op unbind --tid 1 -I ALL

Now, restrict access to a specific IP ...

# tgtadm --lld iscsi --mode target --op bind --tid 1 -I 10.10.0.24

Or, restrict access to a subnet ...

# tgtadm --lld iscsi --mode target --op bind --tid 1 -I 10.10.0.0/24

User/Password authentication (CHAP)

There are two types of CHAP configurations supported for iSCSI authentication:

Authentication Type A.K.A. Description
Initiator Authentication Forward, One-Way The initiator is authenticated by the target.
Target Authentication Reverse, Bi-directional, Mutual, Two-way The target is authenticated by the initiator. This method also requires Initiator Authentication.
  • Initiator Authentication is basic CHAP authentication. A username and password is created on the target. Each initiator logs into the target with this information.
  • Target Authentication is an authentication method in addition to Initiator Authentication. A separate "outgoing" username is created on the target. This username/password pair is used by the target to log into each initiator. Initiator Authentication must also be configured in this scenario.
CHAP Initiator Authentication
  1. First, create a user and password:
    # tgtadm --lld iscsi --mode account --op new --user ''consumer'' --password ''Longsw0rd''
  2. Next, add the users to an existing target device:
    # tgtadm --lld iscsi --mode account --op bind --tid 1 --user ''consumer''
  3. On the initiator's system, this username/password information is entered into /etc/iscsi/iscsid.conf as:
    • For discovery authentication (not supported by tgt yet): discovery.sendtargets.auth.{username,password}
    • For session authentication: node.session.auth.{username,password}
CHAP Target Authentication
  1. First, create a user and password:
    # tgtadm --lld iscsi --mode account --op new --user ''provider'' --password ''Shortsw0rd''
  2. Next, add the users to an existing target device:
    # tgtadm --lld iscsi --mode account --op bind --tid 1 --user ''provider'' --outgoing
  3. On the initiator's system, this username/password information is entered into /etc/iscsi/iscsid.conf as:
    • For discovery authentication (not supported by tgt yet): discovery.sendtargets.auth.{username_in,password_in}
    • For session authentication: node.session.auth.{username_in,password_in}