bionic (8) targetcli.8.gz

Provided by: targetcli-fb_2.1.43-1_all bug

NAME

       targetcli - administration shell for storage targets

DESCRIPTION

       targetcli 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 systems 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.

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.

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.com.example:test-target
       /> cd iscsi/iqn.2006-04.com.example:test-target/tpg1/
       tpg1/> luns/ create /backstores/fileio/test
       tpg1/> set attribute generate_node_acls=1
       tpg1/> exit

       Although by default targetcli saves the running configuration upon exit, a distribution-specific  service
       must  be  enabled  to  restore  the  saved  configuration  on  reboot. See distribution documentation for
       specifics, but for example:

       $ sudo systemctl enable target.service

       See EXAMPLES below for more detailed information on commands and using the shell.

BACKSTORES

       Backstores are different kinds of local storage resources that the kernel 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 operation 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.

   USERSPACE-BACKED
       Backstores  starting  with  "user:"  are  not supported in the kernel, but rely on a userspace process to
       handle requests. See tcmu-runner(8) for more information on creating backstores of this type.

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  configuration  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-
       completion.  If  the  fabric  is  not  tied  to hardware, such as iSCSI, then targetcli 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  fabrics  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 complete 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.  Both IPv4 and IPv6 addresses are supported.

       When a target is created, targetcli  automatically  creates  a  default  portal  listening  on  all  IPv4
       addresses  (shown  as  0.0.0.0) on port 3260.  If a different configuration is needed, the default portal
       can be removed and portals configured as desired.

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

       create <wwn> in the acls node creates an ACL for an initiator, and create 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 username and  password.  The  initiator
       may  be required to supply valid credentials 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 session phase  (Discovery  or  Normal),
       and authentication in a Normal session 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/parameters/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 fabric.

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 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.  Only
       required if the default 0.0.0.0:3260 portal is not present.

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

   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/rtslib-fb-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 established 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  confirm=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 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.   These   include  auto_save_on_exit,  which  controls  if  exiting  targetcli  saves  the
       configuration; auto_add_mapped_luns, to automatically 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/rtslib-fb-target/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 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/rtslib-fb-target/saveconfig.json
       /etc/rtslib-fb-target/backup/*

SEE ALSO

       targetctl(8), tcmu-runner(8)

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/open-iscsi/targetcli-fb/issues>

                                                                                                    targetcli(8)