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>

                                                                                                    targetcli(8)