targetcli(8)targetcli(8)NAMEtargetcli - administration shell for storage targets
DESCRIPTIONtargetcli is a shell for viewing, editing, and saving the configuration
of the kernel's target subsystem, also known as LIO. It enables the
administrator to assign local storage resources backed by either files,
volumes, local SCSI devices, or ramdisk, and export them to remote sys‐
tems via network fabrics, such as iSCSI or FCoE.
The configuration layout is tree-based, similar to a filesystem, and is
navigated in a similar manner.
USAGEtargetcli
targetcli [cmd]
Invoke targetcli as root to enter the configuration shell, or follow
with a command to execute but do not enter the shell. Use ls to list
nodes below the current path. Moving around the tree is accomplished
by the cd command, or by entering the new location directly. Objects
are created using create, removed using delete. Use help <cmd> for
additional usage information. Tab-completion is available for commands
and command arguments.
Configuration changes in targetcli are made immediately to the underly‐
ing kernel target configuration. Settings will not be retained across
reboot unless saveconfig is either explicitly called, or implicitly by
exiting the shell with the global preference auto_save_on_exit set to
true, the default.
QUICKSTART
To create an iSCSI target and share a file-backed LUN without any auth
checks:
$ sudo targetcli
/> backstores/fileio create test /tmp/test.img 100m
/> iscsi/ create iqn.2006-04.example.com:test-target
/> cd iscsi/iqn.2006-04.example.com:test-target/tpg1/
tpg1/> luns/ create /backstores/fileio/test
tpg1/> set attribute generate_node_acls=1
tpg1/> exit
See EXAMPLES below for more detailed information.
BACKSTORES
Backstores are different kinds of local storage resources that the ker‐
nel target uses to "back" the SCSI devices it exports. The mappings to
local storage resources that each backstore creates are called storage
objects.
FILEIO
Allows files to be treated as disk images. When storage objects of this
type are created, they can support either write-back or write-thru
operation. Using write-back enables the local filesystem cache, which
will improve performance but increase the risk of data loss. It is also
possible to use fileio with local block device files, if buffered oper‐
ation is needed.
Fileio also supports using an existing file, or creating a new file.
New files are sparsely allocated by default.
BLOCK
Allows a local disk block device to be shared.
PSCSI
Allows a local SCSI device of any type to be shared. It is generally
advised to prefer the block backstore if sharing a block SCSI device is
desired.
RAMDISK
Allows kernel memory to be shared as a block SCSI device. Since memory
is volatile, the contents of the ramdisk will be lost if the system
restarts, and this backstore is best used for testing only.
It also supports "nullio" mode, which is not backed by any storage. It
discards all writes, and returns all-zeroes for reads.
TARGETS
Targets are instances of a fabric, which adapts the kernel target to a
specific transport protocol such as iSCSI, Fibre Channel, or SBP-2.
Creating a target in targetcli enables that target to be configured.
The name of the target, its WWN (world wide name), may link the config‐
uration to a specific hardware endpoint, like SRP for example, or it
may not, like iSCSI.
Aside from "backstores", all other top-level configuration nodes in
targetcli are fabrics that may have targets created for them. Fabrics
that require hardware are only listed if the hardware is present and
configured properly.
CREATING A TARGET
Use the create command within a fabric's node to create a target. If
the fabric's targets are tied to hardware then targetcli will constrain
the WWN to available hardware WWNs. These can be shown via tab-comple‐
tion. If the fabric is not tied to hardware, such as iSCSI, then tar‐
getcli will either auto-generate a WWN if none is given, or check that
the given WWN has the correct format. All WWNs are prefaced by their
type, such as "iqn", "naa", or "ib", and may be given with or without
colons.
iSCSI supports multiple WWN formats: iqn, naa, and eui. Other fabrics
support single formats only.
CONFIGURING A TARGET
Not all fabrics have the same capabilities. Targets on different fab‐
rics will have different configuration node layouts. iSCSI has the most
to configure; other fabrics present subsets of iSCSI's feature set.
CONFIGURING ISCSI
iSCSI has the most options for configuration.
TPGS
TPGs (Target Portal Groups) allow the iSCSI to support multiple com‐
plete configurations within one target. This is useful for complex
quality-of-service configurations. targetcli will automatically create
one TPG when the target is created, and almost all setups only need
one.
PORTALS
An iSCSI target may be reached via multiple IP addresses and ports.
These addr:port pairs are called portals. This node allows these to be
configured. The common case is to listen on all IPs on port 3260, so
the create command here defaults to those values. Both IPv4 and IPv6
addresses are supported.
If the hardware supports it, iSER (iSCSI Extensions for RDMA) may be
enabled via the enable_iser command within each portal's node.
LUNS
The kernel target exports SCSI Logical Units, also called LUNs. This
section links the previously-defined storage objects with the target,
and defines which number (the Logical Unit Number) the device will use.
Note that if ACLs are being used, a lun mapping must be created under
the ACL that refers back to the TPG LUN.
ACLS
ACLs (Access Control Lists) allow different configuration, depending on
the initiator that is connecting to the target. This includes both per-
initiator authentication settings as well as per-initiator LUN map‐
pings.
create <wwn> in the acls node creates an ACL for an initiator, and cre‐
ate within the ACL creates a LUN mapping. (This can either refer to the
TPG LUN, or to the storage object, in which case the TPG LUN will be
configured as well.) Global setting auto_add_mapped_luns affects this,
see below.
AUTHENTICATION
iSCSI supports authentication via the CHAP protocol, which uses a user‐
name and password. The initiator may be required to supply valid cre‐
dentials to the target, and the target may also be required to supply
credentials back to the initiator. The latter is referred to as mutual
authentication.
Furthermore, authentication credentials may be different for each ses‐
sion phase (Discovery or Normal), and authentication in a Normal ses‐
sion may be set at the TPG level, or per-ACL.
Discovery Authentication
iSCSI Discovery sessions allow the initiator to connect to a portal and
discover targets with the SendTargets command, but not access them. The
four parameters userid, password, mutual_userid, and mutual_password
are configured via set discovery_auth command within the top-level
iscsi configuration node. 1-way authentication is enabled if userid and
password are both set, and mutual authentication is enabled if all four
are set. Authentication is disabled by unsetting the parameters.
Normal Authentication
Similarly, the four parameters userid, password, mutual_userid, and
mutual_password are configured via set auth command within the TPG node
and ACL nodes. However, LIO only uses one or the other, depending on
the TPG's generate_node_acls attribute setting. If generate_node_acls
is 1, the TPG-wide settings will be used. If generate_node_acls is 0,
then the user-created ACLs' settings will be used.
Enable generate_node_acls with set attribute generate_node_acls=1
within the TPG node. This can be thought of as "ignore ACLs mode" --
both authentication and LUN mapping will then use the TPG settings.
No Authentication
Authentication is disabled by clearing the TPG "authentication"
attribute: set attribute authentication=0. Although initiator names
are trivially forgeable, generate_node_acls still works here to either
ignore user-defined ACLs and allow all, or check that an ACL exists for
the connecting initiator.
CONFIGURING FIBRE CHANNEL (QLA2XXX)
Operation as a target requires that /sys/module/qla2xxx/parame‐
ters/qlini_mode report "disabled". This may require passing the
qlini_mode=disabled parameter to the qla2xxx module when it loads.
CONFIGURING FIBRE CHANNEL OVER ETHERNET (TCM_FC)
Ensure fcoeadm -i shows a working endpoint.
CONFIGURING SRP
SRP (SCSI RDMA Protocol) requires that RDMA-capable hardware is
present. It uses "ib" WWNs.
CONFIGURING LOOPBACK
Storage objects may be re-exported as local SCSI devices with this fab‐
ric.
CONFIGURING OTHER FABRICS
Other fabrics may be present. They are for specialized uses. Use at
your own risk.
EXAMPLES
DEFINING A STORAGE OBJECT WITHIN A BACKSTORE
backstores/fileio create disk1 /disks/disk1.img 140M
Creates a storage object named disk1 with the given path and size.
targetcli supports common size abbreviations like 'M', 'G', and 'T'.
EXPORTING A STORAGE OBJECT VIA ISCSI
iscsi/ create
Creates an iSCSI target with a default WWN. It will also create an ini‐
tial target portal group called tpg1.
iqn.2003-01.org.linux-iscsi.test2.x8664:sn123456789012/tpg1/
An example of changing to the configuration node for the given target's
first target portal group (TPG). This is equivalent to giving the com‐
mand prefixed by "cd". (Although more can be useful for certain setups,
most configurations have a single TPG per target. In this case, config‐
uring the TPG is equivalent to configuring the overall target.)
portals/ create
Add a portal, i.e. an IP address and TCP port via which the target can
be contacted by initiators. Sane defaults are used if these are not
specified.
luns/ create /backstores/fileio/disk1
Create a new LUN in the TPG, attached to the storage object that has
previously been defined. The storage object now shows up under the
/backstores configuration node as activated.
acls/ create iqn.1994-05.com.redhat:4321576890
Creates an ACL (access control list) entry for the given iSCSI initia‐
tor.
acls/iqn.1994-05.com.redhat:4321576890 create 2 0
Gives the initiator access to the first exported LUN (lun0), which the
initiator will see as lun2. The default is to give the initiator
read/write access; if read-only access was desired, an additional "1"
argument would be added to enable write-protect. (Note: if global set‐
ting auto_add_mapped_luns is true, this step is not necessary.)
EXPORTING A STORAGE OBJECT VIA FCOE
tcm_fc/ create 20:00:00:19:99:a8:34:bc
Create an FCoE target with the given WWN. targetcli can tab-complete
the WWN based on registered FCoE interfaces. If none are found, verify
that they are properly configured and are shown in the output of
fcoeadm -i.
tcm_fc/20:00:00:19:99:a8:34:bc/
If auto_cd_after_create is set to false, change to the configuration
node for the given target, equivalent to giving the command prefixed by
cd.
luns/ create /backstores/fileio/disk1
Create a new LUN for the interface, attached to a previously defined
storage object. The storage object now shows up under the /backstores
configuration node as activated.
acls/ create 00:99:88:77:66:55:44:33
Create an ACL (access control list), for defining the resources each
initiator may access. The default behavior is to auto-map existing LUNs
to the ACL; see help for more information.
The LUN should now be accessible via FCoE.
OTHER COMMANDS
saveconfig
Save the current configuration settings to a file, from which settings
will be restored if the system is rebooted. By default, this will save
the configuration to /etc/target/saveconfig.json.
This command is executed from the configuration root node.
restoreconfig
Restore target configuration from a file, the default is the file
listed under saveconfig. This will fail if there is already an estab‐
lished config, unless the clear_existing option is set to true.
This command is executed from the configuration root node.
clearconfig
Clears the entire current local configuration. The parameter con‐
firm=true must also be given, as a precaution.
This command is executed from the configuration root node.
sessions [ list | detail ] [sid]
Lists the current open sessions or a specific session, with or without
details.
This command is executed from the configuration root node.
exit
Leave the configuration shell.
SETTINGS GROUPS
Settings are broken into groups. Individual settings are accessed by
get <group> <setting> and set <group> <setting>=<value>, and the set‐
tings of an entire group may be displayed by get <group>. All except
for global are associated with a particular configuration node.
GLOBAL
Shell-related user-specific settings are in global, and are visible
from all configuration nodes. They are mostly shell display options,
but some starting with auto_ affect shell behavior and may merit cus‐
tomization. These include auto_save_on_exit, which controls if exiting
targetcli saves the configuration; auto_add_mapped_luns, to automati‐
cally add existing LUNs to new ACLs, and new LUNS to existing ACLs; and
auto_cd_after_create, to change working path to newly-created nodes.
Global settings are user-specific and are saved to ~/.targetcli/ upon
exit, unlike other groups, which are system-wide and kept in /etc/tar‐
get/saveconfig.json.
BACKSTORE-SPECIFIC
attribute
/backstore/<type>/<name> configuration node. Contains values relating
to the backstore and storage object.
ISCSI-SPECIFIC
discovery_auth
/iscsi configuration node. Set the normal and mutual authentication
userid and password for discovery sessions, as well as enabling or dis‐
abling it. By default it is disabled -- no authentication is required
for discovery.
parameter
/iscsi/<target_iqn>/tpgX configuration node. ISCSI-specific parameters
such as AuthMethod, MaxBurstLength, IFMarker, DataDigest, and similar.
attribute
/iscsi/<target_iqn>/tpgX configuration node. Contains implementation-
specific settings for the TPG, such as authentication, to enforce or
disable authentication for the full-feature phase (i.e. non-discovery).
auth
/iscsi/<target_iqn>/tpgX/acls/<initiator_iqn> configuration node. Set
the userid and password for full-feature phase for this ACL.
FILES
/etc/target/saveconfig.json
/etc/target/backup/*
AUTHOR
Written by Jerome Martin <jxm@risingtidesystems.com>.
Man page written by Andy Grover <agrover@redhat.com>.
REPORTING BUGS
Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>
or <https://github.com/agrover/targetcli-fb/issues>
targetcli(8)
