1targetcli(8) System Manager's Manual targetcli(8)
2
6 targetcli - administration shell for storage targets
7
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 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 The configuration layout is tree-based, similar to a filesystem, and is
21 navigated in a similar manner.
22
24 targetcli
25 targetcli [cmd]
27 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 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
43 To create an iSCSI target and share a file-backed LUN without any auth
44 checks:
45 $ 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 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 $ sudo systemctl enable target.service
60 See EXAMPLES below for more detailed information on commands and using
62 the shell.
63
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 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 Fileio also supports using an existing file, or creating a new file.
79 New files are sparsely allocated by default.
80 BLOCK
82 Allows a local disk block device to be shared.
83 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 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 It also supports "nullio" mode, which is not backed by any storage. It
95 discards all writes, and returns all-zeroes for reads.
96 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
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 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 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 iSCSI supports multiple WWN formats: iqn, naa, and eui. Other fabrics
126 support single formats only.
127
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
134 iSCSI has the most options for configuration.
135 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 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 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 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 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 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 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 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 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 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 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 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 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
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
222 Ensure fcoeadm -i shows a working endpoint.
223
225 SRP (SCSI RDMA Protocol) requires that RDMA-capable hardware is
226 present. It uses "ib" WWNs.
227
229 Storage objects may be re-exported as local SCSI devices with this fab‐
230 ric.
231
233 Other fabrics may be present. They are for specialized uses. Use at
234 your own risk.
235
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 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 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 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 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 acls/ create iqn.1994-05.com.redhat:4321576890
265 Creates an ACL (access control list) entry for the given iSCSI initia‐
266 tor.
267 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 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 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 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 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 The LUN should now be accessible via FCoE.
298
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 This command is executed from the configuration root node.
306 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 This command is executed from the configuration root node.
313 clearconfig
315 Clears the entire current local configuration. The parameter con‐
316 firm=true must also be given, as a precaution.
317 This command is executed from the configuration root node.
319 sessions [ list | detail ] [sid]
321 Lists the current open sessions or a specific session, with or without
322 details.
323 This command is executed from the configuration root node.
325 exit
327 Leave the configuration shell.
328
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 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 BACKSTORE-SPECIFIC
348 attribute
349 /backstore/<type>/<name> configuration node. Contains values relating
350 to the backstore and storage object.
351 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 parameter
360 /iscsi/<target_iqn>/tpgX configuration node. ISCSI-specific parameters
361 such as AuthMethod, MaxBurstLength, IFMarker, DataDigest, and similar.
362 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 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
373 /etc/target/saveconfig.json
374 /etc/target/backup/*
375
377 TARGETCLI_HOME
378 If set, this variable points to a directory that should be used instead
379 of ~/.targetcli
380
382 targetclid(8), targetctl(8), tcmu-runner(8)
383
385 Written by Jerome Martin <jxm@risingtidesystems.com>.
386 Man page written by Andy Grover <agrover@redhat.com>.
387
389 Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>
390 or <https://github.com/open-iscsi/targetcli-fb/issues>
391 targetcli(8)