Linux iSCSI Target (tgt): Difference between revisions

From Alpine Linux
(Attempting to create this page on behalf of User:Forza, who was automagically blocked from doing so.)
 
(use path, cmd & cat template)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The Linux target framework (tgt) is a user space SCSI target framework that supports the iSCSI and iSER transport protocols and that supports multiple methods for accessing block storage. tgt consists of user-space daemon and tools. Being a user space server, it does not require a kernel module to run. In Alpine Linux, the package is called [https://pkgs.alpinelinux.org/packages?name=scsi-tgt*&branch=edge&repo=&arch=&maintainer= scsi-tgt]
The Linux target framework (tgt) is a user space SCSI target framework that supports the iSCSI and iSER transport protocols and that supports multiple methods for accessing block storage. tgt consists of user-space daemon and tools. Being a user space server, it does not require a kernel module to run. In Alpine Linux, the package is called {{pkg|scsi-tgt}}


== installation ==
== Installation ==
Install the utilities to configure tgt:
In Alpine, {{ic|scsi-tgt}} is split over several packages:
  # apk add scsi-tgt scsi-tgt-scripts
* {{pkg|scsi-tgt}} - the tgtd daemon.
  # rc-update add tgt-admin
* {{pkg|scsi-tgt-scripts}} - tgt-admin helper utility. Makes it easier to configure targets via config files.
  # service tgt-admin start
* {{pkg|scsi-tgt-doc}} - documentation, man pages and example configurations.
* {{pkg|scsi-tgt-openrc}} - init scripts for runnit tgt as a service.


{{note|Note that without setting up the configuration file {{ic|/etc/tgt/targets.conf}} first, the {{ic|tgtd}} daemon will run with an empty configuration}}
Only {{pkg|scsi-tgt}} is required to run the tgt target daemon. A running daemon can be configured with {{ic|tgtadm}} command line tool. However, if you want to use configuration files you need the {{ic|tgt-admin}} helper tool, which reads the config and emits appropriate {{ic|tgtadm}} commands. The tgt-admin tool is written in perl, and so depends on perl being installed, which is why we have it as a separate package.
 
This guide assumes that you want to configure iSCSI targets via a configuration file, and have it automatically start during boot.
 
To install scsi-tgt and the utilities to configure tgt:
{{cmd|# apk add scsi-tgt scsi-tgt-scripts}}
 
{{note|Note that without setting up the configuration file {{path|/etc/tgt/targets.conf}} first, the {{ic|tgtd}} daemon will run with an empty configuration}}
 
Once you have editited the configuration file, you can activate the service with
{{cmd|<nowiki># rc-update add tgt-admin
# service tgt-admin start
</nowiki>}}


=== Sample configuration ===
=== Sample configuration ===
Here is an example configuration for exporting a local image file as a iSCSI target (virtual SCSI disk):
Here is an example configuration for exporting a local image file as a iSCSI target (virtual SCSI disk):


File: /etc/tgt/conf.d/iscsi.conf
{{cat|/etc/tgt/conf.d/iscsi.conf|# tgt-admin configuration file
# tgt-admin configuration file
## By default, tgt-admin looks for its config file in /etc/tgt/targets.conf
## By default, tgt-admin looks for its config file in /etc/tgt/targets.conf
 
# Set the driver. If not specified, defaults to "iscsi".
# Set the driver. If not specified, defaults to "iscsi".
default-driver iscsi
default-driver iscsi
 
## Define a target
## Define a target
# iSCSI naming convention for iqn format:
# iSCSI naming convention for iqn format:
# https://www.rfc-editor.org/rfc/rfc3721#section-1.1
# https://www.rfc-editor.org/rfc/rfc3721#section-1.1
 
<target iqn.2023-07.net.tnonline.wiki:server.target1>
    ## General settings
    controller_tid 1
    vendor_id Forza
 
    ## iSCSI features
    HeaderDigest None
    DataDigest None
    ErrorRecoveryLevel 2
   
   
<target iqn.2023-07.net.tnonline.wiki:server.target1>
    ## Access control
      ## General settings
    initiator-address 192.168.0.10
    controller_tid 1
    incominguser user1 secretpass12
    vendor_id Forza
    ## iSCSI features
    HeaderDigest None
    DataDigest None
    ErrorRecoveryLevel 2
    ## Access control
    initiator-address 192.168.0.10
    incominguser user1 secretpass12
    ## iSCSI targets (exports)
    <backing-store "/media/target/diskimage_1.img">
        lun 1
        block-size 4096
        params thin_provisioning=1 rotation_rate=0 sense_format=1
        allow-in-use yes
        write-cache on
        scsi_sn 1001
        product_id MediaFiles
    </backing-store>
</target>


    ## iSCSI targets (exports)
    <backing-store "/media/target/diskimage_1.img">
        lun 1
        block-size 4096
        params thin_provisioning{{=}}1 rotation_rate{{=}}0 sense_format{{=}}1
        allow-in-use yes
        write-cache on
        scsi_sn 1001
        product_id MediaFiles
    </backing-store>
</target>
}}
[[File:ISCSI device in Windows Device Management.png|thumb|A Windows initiator connected to an Alpine Linux iSCSI target. The virtual disk looks like a locally connected HDD.]]


== tgt-admin ==
== tgt-admin ==
Line 54: Line 67:
{{ic|tgt-admin}} is a convenience script to configure the running {{ic|tgtd}} daemon. It is not needed if you want to manually configure {{ic|tgtd}} using the {{ic|tgtadm}} tool.
{{ic|tgt-admin}} is a convenience script to configure the running {{ic|tgtd}} daemon. It is not needed if you want to manually configure {{ic|tgtd}} using the {{ic|tgtadm}} tool.


Documentation can be found in the {{ic|scsi-tgt-doc}} package (man tgt-admin), but also on upstream's GitHub page https://github.com/fujita/tgt/tree/master/doc
Documentation can be found in the {{ic|scsi-tgt-doc}} package (man tgt-admin), but also on [https://github.com/fujita/tgt/tree/master/doc upstream's GitHub page]


Common {{ic|tgt-admin}} commands are:
Common {{ic|tgt-admin}} commands are:
* {{ic|tgt-admin --execute}}
* {{ic|tgt-admin --execute}}
Load new targets from  /etc/tgt/targets.conf. Existing targets won't be updated.
Load new targets from  {{path|/etc/tgt/targets.conf}}. Existing targets won't be updated.
* {{ic|tgt-admin --update <value>}}
* {{ic|tgt-admin --update <value>}}
Update selected targets. Targets in-use by initiators won't be updated.
Update selected targets. Targets in-use by initiators won't be updated.
Line 68: Line 81:
=== tgt-admin examples ===
=== tgt-admin examples ===
To see the status of the running configuration, use the {{ic|tgt-admin -s}} command:
To see the status of the running configuration, use the {{ic|tgt-admin -s}} command:
{{cmd|# tgt-admin -s
Target 1: iqn.2023-07.net.tnonline.wiki:server.target1
    System information:
        Driver: iscsi
        State: ready
    I_T nexus information:
    LUN information:
        LUN: 0
            Type: controller
            SCSI ID: IET    00010000
            SCSI SN: beaf10
            Size: 0 MB, Block size: 1
            Online: Yes
            Removable media: No
            Prevent removal: No
            Readonly: No
            SWP: No
            Thin-provisioning: No
            Backing store type: null
            Backing store path: None
            Backing store flags:
        LUN: 1
            Type: disk
            SCSI ID: IET    00010001
            SCSI SN: 1001
            Size: 107374 MB, Block size: 4096
            Online: Yes
            Removable media: No
            Prevent removal: No
            Readonly: No
            SWP: No
            Thin-provisioning: Yes
            Backing store type: rdwr
            Backing store path: /media/target/diskimage_1.img
            Backing store flags:
    Account information:
        user1
    ACL information:
        192.168.0.10
}}


# tgt-admin -s
If you want to see that native commands are needed you can use the {{ic|--verbose}} option.
Target 1: iqn.2023-07.net.tnonline.wiki:server.target1
 
    System information:
Here you can see the the actual commands used when issuing {{ic|tgt-admin --update ALL --verbose}}:
        Driver: iscsi
 
        State: ready
Removing target: iqn.2023-07.net.tnonline.wiki:server.target1
    I_T nexus information:
{{cmd|tgtadm -C 0 --mode target --op delete --tid{{=}}1}}
    LUN information:
        LUN: 0
            Type: controller
            SCSI ID: IET    00010000
            SCSI SN: beaf10
            Size: 0 MB, Block size: 1
            Online: Yes
            Removable media: No
            Prevent removal: No
            Readonly: No
            SWP: No
            Thin-provisioning: No
            Backing store type: null
            Backing store path: None
            Backing store flags:
        LUN: 1
            Type: disk
            SCSI ID: IET    00010001
            SCSI SN: 1001
            Size: 107374 MB, Block size: 4096
            Online: Yes
            Removable media: No
            Prevent removal: No
            Readonly: No
            SWP: No
            Thin-provisioning: Yes
            Backing store type: rdwr
            Backing store path: /media/target/diskimage_1.img
            Backing store flags:
    Account information:
        user1
    ACL information:
        192.168.0.10


If you want to see that native commands are needed you can use the {{ic|--verbose}} option.


Here you can see the the actuall commands used when issuing {{ic|tgt-admin --update ALL --verbose}}:
Adding target: iqn.2023-07.net.tnonline.wiki:server.target1
# Removing target: iqn.2023-07.net.tnonline.wiki:server.target1
{{cmd|tgtadm -C 0 --lld iscsi --op new --mode target --tid 1 -T iqn.2023-07.net.tnonline.wiki:server.target1
tgtadm -C 0 --mode target --op delete --tid=1
tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name DataDigest --value None
tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name ErrorRecoveryLevel --value 2
# Adding target: iqn.2023-07.net.tnonline.wiki:server.target1
tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name HeaderDigest --value None
tgtadm -C 0 --lld iscsi --op new --mode target --tid 1 -T iqn.2023-07.net.tnonline.wiki:server.target1
tgtadm -C 0 --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 -b "/media/target/diskimage_1.img"    --blocksize 4096
tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name DataDigest --value None
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params product_id{{=}}"MediaFiles"
tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name ErrorRecoveryLevel --value 2
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params "thin_provisioning{{=}}1 rotation_rate{{=}}0 sense_format{{=}}1"
tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name HeaderDigest --value None
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params scsi_sn{{=}}"1001"
tgtadm -C 0 --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 -b "/media/target/diskimage_1.img"    --blocksize 4096
}}
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun=1 --params product_id="MediaFiles"
Write cache is enabled (default) for lun 1.
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun=1 --params "thin_provisioning=1 rotation_rate=0 sense_format=1"
{{cmd|tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params vendor_id{{=}}"Forza"
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun=1 --params scsi_sn="1001"
tgtadm -C 0 --lld iscsi --mode account --op bind --tid 1 --user{{=}}user1
# Write cache is enabled (default) for lun 1.
tgtadm -C 0 --lld iscsi --op bind --mode target --tid 1 -I 192.168.0.10
tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun=1 --params vendor_id="Forza"
}}
tgtadm -C 0 --lld iscsi --mode account --op bind --tid=1 --user=user1
tgtadm -C 0 --lld iscsi --op bind --mode target --tid 1 -I 192.168.0.10  




[[Category:Storage]]
[[Category:Storage]]

Latest revision as of 15:06, 13 September 2023

The Linux target framework (tgt) is a user space SCSI target framework that supports the iSCSI and iSER transport protocols and that supports multiple methods for accessing block storage. tgt consists of user-space daemon and tools. Being a user space server, it does not require a kernel module to run. In Alpine Linux, the package is called scsi-tgt

Installation

In Alpine, scsi-tgt is split over several packages:

  • scsi-tgt - the tgtd daemon.
  • scsi-tgt-scripts - tgt-admin helper utility. Makes it easier to configure targets via config files.
  • scsi-tgt-doc - documentation, man pages and example configurations.
  • scsi-tgt-openrc - init scripts for runnit tgt as a service.

Only scsi-tgt is required to run the tgt target daemon. A running daemon can be configured with tgtadm command line tool. However, if you want to use configuration files you need the tgt-admin helper tool, which reads the config and emits appropriate tgtadm commands. The tgt-admin tool is written in perl, and so depends on perl being installed, which is why we have it as a separate package.

This guide assumes that you want to configure iSCSI targets via a configuration file, and have it automatically start during boot.

To install scsi-tgt and the utilities to configure tgt:

# apk add scsi-tgt scsi-tgt-scripts

Note: Note that without setting up the configuration file /etc/tgt/targets.conf first, the tgtd daemon will run with an empty configuration

Once you have editited the configuration file, you can activate the service with

# rc-update add tgt-admin # service tgt-admin start

Sample configuration

Here is an example configuration for exporting a local image file as a iSCSI target (virtual SCSI disk):

Contents of /etc/tgt/conf.d/iscsi.conf

# tgt-admin configuration file ## By default, tgt-admin looks for its config file in /etc/tgt/targets.conf # Set the driver. If not specified, defaults to "iscsi". default-driver iscsi ## Define a target # iSCSI naming convention for iqn format: # https://www.rfc-editor.org/rfc/rfc3721#section-1.1 <target iqn.2023-07.net.tnonline.wiki:server.target1> ## General settings controller_tid 1 vendor_id Forza ## iSCSI features HeaderDigest None DataDigest None ErrorRecoveryLevel 2 ## Access control initiator-address 192.168.0.10 incominguser user1 secretpass12 ## iSCSI targets (exports) <backing-store "/media/target/diskimage_1.img"> lun 1 block-size 4096 params thin_provisioning=1 rotation_rate=0 sense_format=1 allow-in-use yes write-cache on scsi_sn 1001 product_id MediaFiles </backing-store> </target>
A Windows initiator connected to an Alpine Linux iSCSI target. The virtual disk looks like a locally connected HDD.

tgt-admin

tgt-admin is a convenience script to configure the running tgtd daemon. It is not needed if you want to manually configure tgtd using the tgtadm tool.

Documentation can be found in the scsi-tgt-doc package (man tgt-admin), but also on upstream's GitHub page

Common tgt-admin commands are:

  • tgt-admin --execute

Load new targets from /etc/tgt/targets.conf. Existing targets won't be updated.

  • tgt-admin --update <value>

Update selected targets. Targets in-use by initiators won't be updated.

  • tgt-admin --show

Query tgtd for running configuration.

  • tgt-admin --pretend

Only print what would be done and not make any changes.

tgt-admin examples

To see the status of the running configuration, use the tgt-admin -s command:

# tgt-admin -s Target 1: iqn.2023-07.net.tnonline.wiki:server.target1 System information: Driver: iscsi State: ready I_T nexus information: LUN information: LUN: 0 Type: controller SCSI ID: IET 00010000 SCSI SN: beaf10 Size: 0 MB, Block size: 1 Online: Yes Removable media: No Prevent removal: No Readonly: No SWP: No Thin-provisioning: No Backing store type: null Backing store path: None Backing store flags: LUN: 1 Type: disk SCSI ID: IET 00010001 SCSI SN: 1001 Size: 107374 MB, Block size: 4096 Online: Yes Removable media: No Prevent removal: No Readonly: No SWP: No Thin-provisioning: Yes Backing store type: rdwr Backing store path: /media/target/diskimage_1.img Backing store flags: Account information: user1 ACL information: 192.168.0.10

If you want to see that native commands are needed you can use the --verbose option.

Here you can see the the actual commands used when issuing tgt-admin --update ALL --verbose:

Removing target: iqn.2023-07.net.tnonline.wiki:server.target1

tgtadm -C 0 --mode target --op delete --tid=1


Adding target: iqn.2023-07.net.tnonline.wiki:server.target1

tgtadm -C 0 --lld iscsi --op new --mode target --tid 1 -T iqn.2023-07.net.tnonline.wiki:server.target1 tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name DataDigest --value None tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name ErrorRecoveryLevel --value 2 tgtadm -C 0 --lld iscsi --mode target --op update --tid 1 --name HeaderDigest --value None tgtadm -C 0 --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 -b "/media/target/diskimage_1.img" --blocksize 4096 tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params product_id="MediaFiles" tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params "thin_provisioning=1 rotation_rate=0 sense_format=1" tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params scsi_sn="1001"

Write cache is enabled (default) for lun 1.

tgtadm -C 0 --lld iscsi --op update --mode logicalunit --tid 1 --lun 1 --params vendor_id="Forza" tgtadm -C 0 --lld iscsi --mode account --op bind --tid 1 --user=user1 tgtadm -C 0 --lld iscsi --op bind --mode target --tid 1 -I 192.168.0.10