Linux iSCSI Target (TCM)

Since kernel 2.6.38 Linux has a new generic Target Core module, merged from LIO [[1]], and since 3.1 there is iSCSI support. This how-to quickly explains how to use it.

Install the utilities to configure Target Core:

 # apk add targetcli
 # rc-update add targetcli
 # rc-update add dbus
 # service targetcli start
 # service dbus start

In contrast with plain text files as usual, all configuration is done in ConfigFS via targetcli shell (you can use tab for command auto-completion and "ls" for inspecting current config):

 # targetcli
 Welcome to the targetcli shell::
 Copyright (c) 2011 by RisingTide Systems LLC.

 For help on commands, type 'help'.

 /> ls
 o- / ..................................................................... [...]
 o- backstores .......................................................... [...]
 | o- fileio ............................................... [0 Storage Object]
 | o- iblock ............................................... [0 Storage Object]
 | o- pscsi ................................................ [0 Storage Object]
 | o- rd_dr ................................................ [0 Storage Object]
 | o- rd_mcp ............................................... [0 Storage Object]
 o- ib_srpt ........................................................ [0 Target]
 o- iscsi .......................................................... [0 Target]
 o- loopback ....................................................... [0 Target]
 o- qla2xxx ........................................................ [0 Target]
 /> 

You can create a file to be exported as a target:

 /> cd backstores/fileio
 /backstores/fileio> create file_backstore file1 1M
 Generating a wwn serial.
 Not using buffered mode.
 Created fileio file_backstore.
 /backstores/fileio>

Or you can use a block device:

 /> cd backstores/blockio
 /backstores/blockio> create block0 /dev/sda1

You can use any block device, including RAID and LVM2. Now create an iSCSI Target and a Target Portal Group (tpg) (the iqn is automatically created. You can also specify one by hand):

 /> cd /iscsi
 /iscsi> create
 Created target iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8.
 Selected TPG Tag 1.
 Successfully created TPG 1.

Now you have to tell Target Core to use the previously create backstore for the target now created:

 /iscsi> cd iqn.2003-01.org.linux-iscsi.rtsnode1.x8664:sn.83a8cde7aca8/tpg1/luns
 ../tpg1/luns> create lun=0 storage_object=/backstores/blockio/block0
 Successfully created LUN 0.

Now create the iSCSI portal:

 ../tpg1/luns> cd ../portals
 ../tpg1/portals> create ip_address=192.168.1.10
 Using default IP port 3260
 Successfully created network portal 192.168.1.10:3260.

By default authentication is enabled. To disable it:

 ../tpg1> set attribute authentication=0
 Parameter authentication is now '0'.
 ../tpg1> set attribute generate_node_acls=1
 Parameter generate_node_acls is now '1'.

Finally save the configuration:

 /> saveconfig
 Existing file /etc/target/saveconfig.json backed up to saveconfig.json.backup
 Configuration saved to /etc/target/saveconfig.json

For real use, you should always track changes to the saveconfig file and make sure (there's a flag for it) to not save config if you are in an error situation. By default, targetcli creates a config backup if you exit, meaning you might lose the working config at the time. So better to be prepared. Errors don't simply appear, but i.e. if you're missing a HBA on boot, these settings will not be loaded and thus not be in the configuration upon save.