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 The configuration layout is tree-based, similar to a filesystem, and is
16 navigated in a similar manner.
17
19 targetcli
20 targetcli [cmd]
22 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 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
38 To create an iSCSI target and share a file-backed LUN without any auth
39 checks:
40 $ 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 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 $ sudo systemctl enable target.service
55 See EXAMPLES below for more detailed information on commands and using
57 the shell.
58
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 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 Fileio also supports using an existing file, or creating a new file.
74 New files are sparsely allocated by default.
75 BLOCK
77 Allows a local disk block device to be shared.
78 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 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 It also supports "nullio" mode, which is not backed by any storage. It
90 discards all writes, and returns all-zeroes for reads.
91 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
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 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 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 iSCSI supports multiple WWN formats: iqn, naa, and eui. Other fabrics
121 support single formats only.
122
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
129 iSCSI has the most options for configuration.
130 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 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 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 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 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 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 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 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 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 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 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 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 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
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
217 Ensure fcoeadm -i shows a working endpoint.
218
220 SRP (SCSI RDMA Protocol) requires that RDMA-capable hardware is
221 present. It uses "ib" WWNs.
222
224 Storage objects may be re-exported as local SCSI devices with this fab‐
225 ric.
226
228 Other fabrics may be present. They are for specialized uses. Use at
229 your own risk.
230
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 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 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 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 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 acls/ create iqn.1994-05.com.redhat:4321576890
260 Creates an ACL (access control list) entry for the given iSCSI initia‐
261 tor.
262 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 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 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 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 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 The LUN should now be accessible via FCoE.
293
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 This command is executed from the configuration root node.
301 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 This command is executed from the configuration root node.
308 clearconfig
310 Clears the entire current local configuration. The parameter con‐
311 firm=true must also be given, as a precaution.
312 This command is executed from the configuration root node.
314 sessions [ list | detail ] [sid]
316 Lists the current open sessions or a specific session, with or without
317 details.
318 This command is executed from the configuration root node.
320 exit
322 Leave the configuration shell.
323
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 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 BACKSTORE-SPECIFIC
343 attribute
344 /backstore/<type>/<name> configuration node. Contains values relating
345 to the backstore and storage object.
346 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 parameter
355 /iscsi/<target_iqn>/tpgX configuration node. ISCSI-specific parameters
356 such as AuthMethod, MaxBurstLength, IFMarker, DataDigest, and similar.
357 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 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
368 /etc/target/saveconfig.json
369 /etc/target/backup/*
370
372 targetctl(8), tcmu-runner(8)
373
375 Written by Jerome Martin <jxm@risingtidesystems.com>.
376 Man page written by Andy Grover <agrover@redhat.com>.
377
379 Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>
380 or <https://github.com/open-iscsi/targetcli-fb/issues>
381 targetcli(8)