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       The configuration layout is tree-based, similar to a filesystem, and is
16       navigated in a similar manner.
17

USAGE

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

QUICKSTART

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

BACKSTORES

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

TARGETS

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

CONFIGURING A TARGET

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

CONFIGURING ISCSI

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

CONFIGURING FIBRE CHANNEL (QLA2XXX)

212       Operation   as   a  target  requires  that  /sys/module/qla2xxx/parame‐
213       ters/qlini_mode  report  "disabled".  This  may  require  passing   the
214       qlini_mode=disabled parameter to the qla2xxx module when it loads.
215

CONFIGURING FIBRE CHANNEL OVER ETHERNET (TCM_FC)

217       Ensure fcoeadm -i shows a working endpoint.
218

CONFIGURING SRP

220       SRP  (SCSI  RDMA  Protocol)  requires  that  RDMA-capable  hardware  is
221       present. It uses "ib" WWNs.
222

CONFIGURING LOOPBACK

224       Storage objects may be re-exported as local SCSI devices with this fab‐
225       ric.
226

CONFIGURING OTHER FABRICS

228       Other  fabrics  may  be  present. They are for specialized uses. Use at
229       your own risk.
230

EXAMPLES

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

OTHER COMMANDS

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

SETTINGS GROUPS

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

FILES

368       /etc/target/saveconfig.json
369       /etc/target/backup/*
370

SEE ALSO

372       targetctl(8), tcmu-runner(8)
373

AUTHOR

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

REPORTING BUGS

379       Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>
380       or <https://github.com/open-iscsi/targetcli-fb/issues>
381
382
383
384                                                                  targetcli(8)
Impressum