targetcli(8)

NAME
targetcli

DESCRIPTION
targetcli is a shell for viewing, editing, and saving the configuration of the kernel's target subsystem, also known as TCM/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 systems via network fabrics, such as iSCSI or FCoE.

The configuration layout is tree-based, similar to a filesystem, and navigated in a similar manner.

USAGE
targetcli

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 underlying 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.

EXAMPLES
To export a storage resource, 1) define a storage object using a backstore, then 2) export the object via a network fabric, such as iSCSI or FCoE.

  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'.

In addition to the fileio backstore for file-backed volumes, other backstore types include iblock for block-device-backed volumes, and pscsi for volumes backed by local SCSI devices. rd_mcp backstore creates ram-based storage objects. See the built-in help for more details on the required parameters for each backstore type.

  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.

  EXPORTING A STORAGE OBJECT VIA ISCSI
iscsi/ create
Creates an iSCSI target with a default WWN. It will also create an initial 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 command prefixed by "cd". (Although more can be useful for certain setups, most configurations have a single TPG per target. In this case, configuring 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) for the given iSCSI initiator.

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 setting auto_add_mapped_luns is true, this step is not necessary.)

acls/iqn.1994-05.com.redhat:4321576890 set authentication=0
Purely for example, make the LUNs in the ACL accessible without authentication. See below for more information on configuring authentication.

OTHER COMMANDS
saveconfig
Save the current configuration settings to a file, from which settings will be restored if the system is rebooted.

This command must be executed from the configuration root node.

clearconfig
Clears the entire current local configuration. The parameter confirm=true must also be given, as a precaution.

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 settings 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 customization. Global settings are saved to ~/.targetcli/ upon exit, unlike other groups.

  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 disabling 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/*
/var/lib/target/*

AUTHOR
Written by Jerome Martin <jxm@risingtidesystems.com>.
Man page written by Andy Grover <agrover@redhat.com>.

REPORTING BUGS
Report bugs to <target-devel@vger.kernel.org>