1targetcli(8)                System Manager's Manual               targetcli(8)
2
3
4

NAME

6       targetcli - administration shell for storage targets
7

DESCRIPTION

9       targetcli is a shell for viewing, editing, and saving the configuration
10       of the kernel's target subsystem, also known as  LIO.  It  enables  the
11       administrator to assign local storage resources backed by either files,
12       volumes, local SCSI devices, or ramdisk, and export them to remote sys‐
13       tems via network fabrics, such as iSCSI or FCoE.
14
15       There  is  a daemon component for targetcli, which will greatly improve
16       the overall execution time taken by targetcli commands  at  scale.  For
17       more  details about switching to daemonized mode refer to targetclid(8)
18       man page.
19
20       The configuration layout is tree-based, similar to a filesystem, and is
21       navigated in a similar manner.
22

USAGE

24       targetcli
25
26       targetcli [cmd]
27
28       Invoke  targetcli  as  root to enter the configuration shell, or follow
29       with a command to execute but do not enter the shell.  Use ls  to  list
30       nodes  below  the current path.  Moving around the tree is accomplished
31       by the cd command, or by entering the new  location  directly.  Objects
32       are  created  using  create,  removed using delete.  Use help <cmd> for
33       additional usage information. Tab-completion is available for  commands
34       and command arguments.
35
36       Configuration changes in targetcli are made immediately to the underly‐
37       ing kernel target configuration. Settings will not be  retained  across
38       reboot  unless saveconfig is either explicitly called, or implicitly by
39       exiting the shell with the global preference auto_save_on_exit  set  to
40       true, the default.
41

QUICKSTART

43       To  create an iSCSI target and share a file-backed LUN without any auth
44       checks:
45
46       $ sudo targetcli
47       /> backstores/fileio create test /tmp/test.img 100m
48       /> iscsi/ create iqn.2006-04.com.example:test-target
49       /> cd iscsi/iqn.2006-04.com.example:test-target/tpg1/
50       tpg1/> luns/ create /backstores/fileio/test
51       tpg1/> set attribute generate_node_acls=1
52       tpg1/> exit
53
54       Although by default targetcli  saves  the  running  configuration  upon
55       exit,  a  distribution-specific  service must be enabled to restore the
56       saved configuration  on  reboot.  See  distribution  documentation  for
57       specifics, but for example:
58
59       $ sudo systemctl enable target.service
60
61       See  EXAMPLES below for more detailed information on commands and using
62       the shell.
63

BACKSTORES

65       Backstores are different kinds of local storage resources that the ker‐
66       nel  target uses to "back" the SCSI devices it exports. The mappings to
67       local storage resources that each backstore creates are called  storage
68       objects.
69
70   FILEIO
71       Allows files to be treated as disk images. When storage objects of this
72       type are created, they can  support  either  write-back  or  write-thru
73       operation.  Using  write-back enables the local filesystem cache, which
74       will improve performance but increase the risk of data loss. It is also
75       possible to use fileio with local block device files, if buffered oper‐
76       ation is needed.
77
78       Fileio also supports using an existing file, or creating  a  new  file.
79       New files are sparsely allocated by default.
80
81   BLOCK
82       Allows a local disk block device to be shared.
83
84   PSCSI
85       Allows  a  local  SCSI device of any type to be shared. It is generally
86       advised to prefer the block backstore if sharing a block SCSI device is
87       desired.
88
89   RAMDISK
90       Allows  kernel memory to be shared as a block SCSI device. Since memory
91       is volatile, the contents of the ramdisk will be  lost  if  the  system
92       restarts, and this backstore is best used for testing only.
93
94       It  also supports "nullio" mode, which is not backed by any storage. It
95       discards all writes, and returns all-zeroes for reads.
96
97   USERSPACE-BACKED
98       Backstores starting with "user:" are not supported in the  kernel,  but
99       rely  on a userspace process to handle requests. See tcmu-runner(8) for
100       more information on creating backstores of this type.
101

TARGETS

103       Targets are instances of a fabric, which adapts the kernel target to  a
104       specific  transport  protocol  such  as iSCSI, Fibre Channel, or SBP-2.
105       Creating a target in targetcli enables that target  to  be  configured.
106       The name of the target, its WWN (world wide name), may link the config‐
107       uration to a specific hardware endpoint, like SRP for  example,  or  it
108       may not, like iSCSI.
109
110       Aside  from  "backstores",  all  other top-level configuration nodes in
111       targetcli are fabrics that may have targets created for  them.  Fabrics
112       that  require  hardware  are only listed if the hardware is present and
113       configured properly.
114
115   CREATING A TARGET
116       Use the create command within a fabric's node to create  a  target.  If
117       the fabric's targets are tied to hardware then targetcli will constrain
118       the WWN to available hardware WWNs. These can be shown via  tab-comple‐
119       tion.  If  the fabric is not tied to hardware, such as iSCSI, then tar‐
120       getcli will either auto-generate a WWN if none is given, or check  that
121       the  given  WWN  has the correct format. All WWNs are prefaced by their
122       type, such as "iqn", "naa", or "ib", and may be given with  or  without
123       colons.
124
125       iSCSI  supports  multiple WWN formats: iqn, naa, and eui. Other fabrics
126       support single formats only.
127

CONFIGURING A TARGET

129       Not all fabrics have the same capabilities. Targets on  different  fab‐
130       rics will have different configuration node layouts. iSCSI has the most
131       to configure; other fabrics present subsets of iSCSI's feature set.
132

CONFIGURING ISCSI

134       iSCSI has the most options for configuration.
135
136   TPGS
137       TPGs (Target Portal Groups) allow the iSCSI to  support  multiple  com‐
138       plete  configurations  within  one  target.  This is useful for complex
139       quality-of-service configurations. targetcli will automatically  create
140       one  TPG  when  the  target is created, and almost all setups only need
141       one.
142
143   PORTALS
144       An iSCSI target may be reached via multiple  IP  addresses  and  ports.
145       These addr:port pairs are called portals.  Both IPv4 and IPv6 addresses
146       are supported.
147
148       When a target is created, targetcli  automatically  creates  a  default
149       portal listening on all IPv4 addresses (shown as 0.0.0.0) on port 3260.
150       If a different configuration is  needed,  the  default  portal  can  be
151       removed and portals configured as desired.
152
153       If  the  hardware  supports it, iSER (iSCSI Extensions for RDMA) may be
154       enabled via the enable_iser command within each portal's node.  Or,  if
155       the  hardware  supports  it,  hardware  offload  may be enabled via the
156       enable_offload command within each portal's node.
157
158   LUNS
159       The kernel target exports SCSI Logical Units, also called  LUNs.   This
160       section  links  the previously-defined storage objects with the target,
161       and defines which number (the Logical Unit Number) the device will use.
162       Note  that  if ACLs are being used, a lun mapping must be created under
163       the ACL that refers back to the TPG LUN.
164
165   ACLS
166       ACLs (Access Control Lists) allow different configuration, depending on
167       the initiator that is connecting to the target. This includes both per-
168       initiator authentication settings as well  as  per-initiator  LUN  map‐
169       pings.
170
171       create <wwn> in the acls node creates an ACL for an initiator, and cre‐
172       ate within the ACL creates a LUN mapping. (This can either refer to the
173       TPG  LUN,  or  to the storage object, in which case the TPG LUN will be
174       configured as well.) Global setting auto_add_mapped_luns affects  this,
175       see below.
176
177   AUTHENTICATION
178       iSCSI supports authentication via the CHAP protocol, which uses a user‐
179       name and password. The initiator may be required to supply  valid  cre‐
180       dentials  to  the target, and the target may also be required to supply
181       credentials back to the initiator. The latter is referred to as  mutual
182       authentication.
183
184       Furthermore,  authentication credentials may be different for each ses‐
185       sion phase (Discovery or Normal), and authentication in a  Normal  ses‐
186       sion may be set at the TPG level, or per-ACL.
187
188       Discovery Authentication
189       iSCSI Discovery sessions allow the initiator to connect to a portal and
190       discover targets with the SendTargets command, but not access them. The
191       four  parameters  userid,  password, mutual_userid, and mutual_password
192       are configured via set  discovery_auth  command  within  the  top-level
193       iscsi configuration node. 1-way authentication is enabled if userid and
194       password are both set, and mutual authentication is enabled if all four
195       are set. Authentication is disabled by unsetting the parameters.
196
197       Normal Authentication
198       Similarly,  the  four  parameters  userid, password, mutual_userid, and
199       mutual_password are configured via set auth command within the TPG node
200       and  ACL  nodes.  However, LIO only uses one or the other, depending on
201       the TPG's generate_node_acls attribute setting.  If  generate_node_acls
202       is  1,  the TPG-wide settings will be used. If generate_node_acls is 0,
203       then the user-created ACLs' settings will be used.
204
205       Enable  generate_node_acls  with  set  attribute   generate_node_acls=1
206       within  the  TPG  node. This can be thought of as "ignore ACLs mode" --
207       both authentication and LUN mapping will then use the TPG settings.
208
209       No Authentication
210       Authentication  is  disabled  by  clearing  the  TPG   "authentication"
211       attribute:  set  attribute  authentication=0.  Although initiator names
212       are trivially forgeable, generate_node_acls still works here to  either
213       ignore user-defined ACLs and allow all, or check that an ACL exists for
214       the connecting initiator.
215

CONFIGURING FIBRE CHANNEL (QLA2XXX)

217       Operation  as  a  target  requires   that   /sys/module/qla2xxx/parame‐
218       ters/qlini_mode   report  "disabled".  This  may  require  passing  the
219       qlini_mode=disabled parameter to the qla2xxx module when it loads.
220

CONFIGURING FIBRE CHANNEL OVER ETHERNET (TCM_FC)

222       Ensure fcoeadm -i shows a working endpoint.
223

CONFIGURING SRP

225       SRP  (SCSI  RDMA  Protocol)  requires  that  RDMA-capable  hardware  is
226       present. It uses "ib" WWNs.
227

CONFIGURING LOOPBACK

229       Storage objects may be re-exported as local SCSI devices with this fab‐
230       ric.
231

CONFIGURING OTHER FABRICS

233       Other fabrics may be present. They are for  specialized  uses.  Use  at
234       your own risk.
235

EXAMPLES

237   DEFINING A STORAGE OBJECT WITHIN A BACKSTORE
238       backstores/fileio create disk1 /disks/disk1.img 140M
239       Creates  a  storage  object  named  disk1 with the given path and size.
240       targetcli supports common size abbreviations like 'M', 'G', and 'T'.
241
242   EXPORTING A STORAGE OBJECT VIA ISCSI
243       iscsi/ create
244       Creates an iSCSI target with a default WWN. It will also create an ini‐
245       tial target portal group called tpg1.
246
247       iqn.2003-01.org.linux-iscsi.test2.x8664:sn123456789012/tpg1/
248       An example of changing to the configuration node for the given target's
249       first target portal group (TPG). This is equivalent to giving the  com‐
250       mand prefixed by "cd". (Although more can be useful for certain setups,
251       most configurations have a single TPG per target. In this case, config‐
252       uring the TPG is equivalent to configuring the overall target.)
253
254       portals/ create
255       Add  a portal, i.e. an IP address and TCP port via which the target can
256       be contacted by initiators. Only required if the  default  0.0.0.0:3260
257       portal is not present.
258
259       luns/ create /backstores/fileio/disk1
260       Create  a  new  LUN in the TPG, attached to the storage object that has
261       previously been defined. The storage object  now  shows  up  under  the
262       /backstores configuration node as activated.
263
264       acls/ create iqn.1994-05.com.redhat:4321576890
265       Creates  an ACL (access control list) entry for the given iSCSI initia‐
266       tor.
267
268       acls/iqn.1994-05.com.redhat:4321576890 create 2 0
269       Gives the initiator access to the first exported LUN (lun0), which  the
270       initiator  will  see  as  lun2.  The  default  is to give the initiator
271       read/write access; if read-only access was desired, an  additional  "1"
272       argument  would be added to enable write-protect. (Note: if global set‐
273       ting auto_add_mapped_luns is true, this step is not necessary.)
274
275   EXPORTING A STORAGE OBJECT VIA FCOE
276       tcm_fc/ create 20:00:00:19:99:a8:34:bc
277       Create an FCoE target with the given WWN.  targetcli  can  tab-complete
278       the  WWN based on registered FCoE interfaces. If none are found, verify
279       that they are properly configured  and  are  shown  in  the  output  of
280       fcoeadm -i.
281
282       tcm_fc/20:00:00:19:99:a8:34:bc/
283       If  auto_cd_after_create  is  set to false, change to the configuration
284       node for the given target, equivalent to giving the command prefixed by
285       cd.
286
287       luns/ create /backstores/fileio/disk1
288       Create  a  new  LUN for the interface, attached to a previously defined
289       storage object. The storage object now shows up under  the  /backstores
290       configuration node as activated.
291
292       acls/ create 00:99:88:77:66:55:44:33
293       Create  an  ACL  (access control list), for defining the resources each
294       initiator may access. The default behavior is to auto-map existing LUNs
295       to the ACL; see help for more information.
296
297       The LUN should now be accessible via FCoE.
298

OTHER COMMANDS

300       saveconfig
301       Save  the current configuration settings to a file, from which settings
302       will be restored if the system is rebooted. By default, this will  save
303       the configuration to /etc/target/saveconfig.json.
304
305       This command is executed from the configuration root node.
306
307       restoreconfig
308       Restore  target  configuration  from  a  file,  the default is the file
309       listed under saveconfig.  This will fail if there is already an  estab‐
310       lished config, unless the clear_existing option is set to true.
311
312       This command is executed from the configuration root node.
313
314       clearconfig
315       Clears  the  entire  current  local  configuration.  The parameter con‐
316       firm=true must also be given, as a precaution.
317
318       This command is executed from the configuration root node.
319
320       sessions [ list | detail ] [sid]
321       Lists the current open sessions or a specific session, with or  without
322       details.
323
324       This command is executed from the configuration root node.
325
326       exit
327       Leave the configuration shell.
328

SETTINGS GROUPS

330       Settings  are  broken  into groups. Individual settings are accessed by
331       get <group> <setting> and set <group> <setting>=<value>, and  the  set‐
332       tings  of  an entire group may be displayed by get <group>.  All except
333       for global are associated with a particular configuration node.
334
335   GLOBAL
336       Shell-related user-specific settings are in  global,  and  are  visible
337       from  all  configuration  nodes. They are mostly shell display options,
338       but some starting with auto_ affect shell behavior and may  merit  cus‐
339       tomization.  These include auto_save_on_exit, which controls if exiting
340       targetcli saves the configuration; auto_add_mapped_luns,  to  automati‐
341       cally add existing LUNs to new ACLs, and new LUNS to existing ACLs; and
342       auto_cd_after_create, to change working path  to  newly-created  nodes.
343       Global  settings  are user-specific and are saved to ~/.targetcli/ upon
344       exit, unlike other groups, which are system-wide and kept in  /etc/tar‐
345       get/saveconfig.json.
346
347   BACKSTORE-SPECIFIC
348       attribute
349       /backstore/<type>/<name>  configuration  node. Contains values relating
350       to the backstore and storage object.
351
352   ISCSI-SPECIFIC
353       discovery_auth
354       /iscsi configuration node. Set the  normal  and  mutual  authentication
355       userid and password for discovery sessions, as well as enabling or dis‐
356       abling it. By default it is disabled -- no authentication  is  required
357       for discovery.
358
359       parameter
360       /iscsi/<target_iqn>/tpgX  configuration node. ISCSI-specific parameters
361       such as AuthMethod, MaxBurstLength, IFMarker, DataDigest, and similar.
362
363       attribute
364       /iscsi/<target_iqn>/tpgX configuration node.  Contains  implementation-
365       specific  settings  for  the TPG, such as authentication, to enforce or
366       disable authentication for the full-feature phase (i.e. non-discovery).
367
368       auth
369       /iscsi/<target_iqn>/tpgX/acls/<initiator_iqn> configuration  node.  Set
370       the userid and password for full-feature phase for this ACL.
371

FILES

373       /etc/target/saveconfig.json
374       /etc/target/backup/*
375

ENVIRONMENT

377   TARGETCLI_HOME
378       If set, this variable points to a directory that should be used instead
379       of ~/.targetcli
380

SEE ALSO

382       targetclid(8), targetctl(8), tcmu-runner(8)
383

AUTHOR

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

REPORTING BUGS

389       Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>
390       or <https://github.com/open-iscsi/targetcli-fb/issues>
391
392
393
394                                                                  targetcli(8)
Impressum