1iscsitadm(1M) System Administration Commands iscsitadm(1M)
2
3
4
6 iscsitadm - administer iSCSI targets
7
9 iscsitadm create [-? | --help] object [-? | --help]
10 [options] operand
11
12
13 iscsitadm modify [-? | --help] object [-? | --help]
14 [options] operand
15
16
17 iscsitadm delete [-? | --help] object [-? | --help]
18 [options] operand
19
20
21 iscsitadm list [-? | --help] object [-? | --help] [options]
22 operand
23
24
25 iscsitadm show [-? | --help] admin
26
27
28 iscsitadm show [-? | --help] object [-? | --help] [options]
29 [operand]
30
31
32 iscsitadm -? --help
33
34
36 The iscsitadm command enables you to manage Internet SCSI (iSCSI) tar‐
37 get nodes. It is a companion to iscsiadm(1M), which enables you to man‐
38 age iSCSI initiator nodes.
39
40
41 The iscsitadm command has the following subcommands:
42
43 create Creates a target using a local target as a reference.
44
45
46 modify Modifies a target or a list of targets.
47
48
49 delete Deletes a target or a list of targets.
50
51
52 list Lists names and information about targets.
53
54
55 show Displays target-related statistics.
56
57
58
59 The preceding subcommands work on the following objects:
60
61 target An iSCSI target node, or list of target nodes.
62
63
64 initiator An iSCSI initiator node, or list of initiator nodes.
65
66
67 admin Stores administrative information, such as server loca‐
68 tions and passwords.
69
70
71 tpgt Stands for TargetPortGroupTag. A number that represents a
72 list of connections that an initiator can use for a given
73 target.
74
75
76 stats Displays statistics; can accept interval and count values.
77 Used only with the show subcommand.
78
79
80
81 These objects are discussed in greater detail under the options
82 descriptions for each subcommand.
83
84
85 As indicated in the SYNOPSIS, iscsitadm has two levels of help. If you
86 invoke -? or --help following a subcommand, the command displays avail‐
87 able operands, options, and objects. If you invoke an help option fol‐
88 lowing an object, iscsitadm displays options and operands.
89
91 The iscsitadm options and objects are discussed below in the context of
92 each subcommand. Note that the help options (-? or --help) are invoked
93 as shown in the SYNOPSIS. See EXAMPLES.
94
95 create Options
96 The following are the options and objects for the create subcommand:
97
98 target --size|-z lun_size [--lun number]
99 [--type disk|tape|raw] [--backing-store|-b pathname] local_name
100
101 Create a target using local_name as a reference. local_name is only
102 used within the context iscsitgtd. --size is a multiplier and is
103 specified as a number followed by a single letter. The letter is
104 one of:
105
106 k kilobyte
107
108
109 m megabyte
110
111
112 g gigabyte
113
114
115 t terabyte
116
117 --lun specifies the logical unit number. --type specifies which
118 type of emulation will occur for the LUN. disk and tape are the
119 familiar devices. raw indicates that the emulator will use the
120 uSCSI interface and pass the command blocks directly to and from
121 the device. The use of raw also implies the option --backing-store
122 will be entered. The argument to this option is the full pathname
123 to the device node normally found in /dev. If you use --backing-
124 store, the size of the store is determined by a SCSI READ_CAPACITY
125 command or, if the backing store is a regular file, by stat(2).
126
127 If local_name already exists, a new target name is not generated
128 for this LUN. The LUN is created within the local_name storage
129 hierarchy. You can use the --backing-store option to specify a dif‐
130 ferent location for the data. If you use --backing-store, it is up
131 to you to allocate actual storage instead of having the target cre‐
132 ate the data file.
133
134
135 initiator --iqn|-n iSCSI_node_name local_initiator
136
137 To use access control lists you must know the name of the initia‐
138 tor. Since the iSCSI initiator name can be quite long (223 bytes)
139 and made up of a long list of numbers, it is best to enter this
140 information once and then refer to the initiator using a simplified
141 name of local_initiator.
142
143
144 tpgt tpgt_number
145
146 If a host has multiple NICs, you might want to limit the number of
147 connections that an initiator can use for a given target. To estab‐
148 lish this limit, you must first create a TargetPortGroupTag (TPGT),
149 which can be any number from 1 to 65535. Once this tag is created,
150 the IP addresses of the NICs can be added to the TPGT, using the
151 modify subcommand. Then, the TPGT can itself be added to the tar‐
152 get.
153
154
155 modify Options
156 The following are the options and objects for the modify subcommand:
157
158 target --tpgt|-p local_tpgt local_target
159
160 Specifies one or more target portal groups to use when initiators
161 reference local_target during discovery.
162
163
164 target --acl|-l local_initiator local_target
165
166 Adds to the list a local initiator that can access local_target. By
167 adding an initiator to a target all initiators from that point on
168 must be in the ACL.
169
170
171 target --alias|-a TargetAlias local_target
172
173 Sets the alias if it was not done during the creation of the target
174 or change an existing target's alias.
175
176
177 target --maxrecv|-m value local_target
178
179 Sets the MaxRecvDataSegmentLength, which can be any value between
180 512 to (2^24 - 1). You can use this option to limit the amount of
181 memory used by the target.
182
183
184 initiator --chap-secret|-C local_initiator
185
186 Prompts the user to enter the value, using getpassphrase(3C). Asso‐
187 ciates the secret used for CHAP authentication during login with
188 local_initiator.
189
190
191 initiator --chap-name|-H value local_initiator
192
193 Specifies the CHAP username used during authentication.
194
195
196 tpgt --ip-address|-i address tpgt_number
197
198 Adds the NIC's address to tpgt_number.
199
200
201 admin --base-directory|-d directory
202
203 Sets the location of where to store the data files that represent
204 the individual LUNs. This should be done before any other function
205 is performed. Otherwise, an error will be generated when attempting
206 to set a persistent value.
207
208
209 admin --chap-secret|-C
210
211 Upon entering this option, you will be prompted to enter the value
212 using getpassphrase(3C). For bidirectional authentication, this is
213 the value used to generate a response to the initiator's challenge.
214
215
216 admin --chap-name|-H value
217
218 Specifies the user name portion of the CHAP protocol.
219
220
221 admin --radius-access|-R enable | disable
222
223 Enables or disables the use of the RADIUS server. Even with a
224 RADIUS server address defined, the use of that server must be
225 enabled. If the server becomes inaccessible and you need to fall
226 back on configuration file access, you can use this option to dis‐
227 able the server.
228
229
230 admin --radius-server|-r hostname:port
231
232 Location of RADIUS server. hostname can be either a resolvable name
233 or an IP address.
234
235
236 admin --radius-secret|-P
237
238 Used to initiate contact with the RADIUS server. Interaction with
239 server uses getpassphrase(3C).
240
241
242 admin --isns-access|-S enable | disable
243
244 Enables or disables access to an iSNS server. iSNS servers broad‐
245 cast their locations.
246
247
248 admin --isns-server|-s hostname
249
250 Location of the iSNS server. "hostname" can be either a resolvable
251 host name or an IP address.
252
253
254 admin --fast-write-ack|-f enable | disable
255
256 Enables or disables fast-write acknowledgment. You should enable
257 this option only if a system is connected to the power grid through
258 a UPS. Otherwise, data corruption could occur if power is lost and
259 some writes that were acknowledged have not been completely flushed
260 to the backing store.
261
262
263 delete Options
264 The following are the options and objects for the delete subcommand:
265
266 target --lun|-u lun_number local_target
267
268 Removes information about the LUN identified by lun_number. This
269 includes the data that is stored in the LUNs.
270
271
272 target --acl|-l local_initiator local_target
273
274 Remove access to local_target by local_initiator. If the initiator
275 is currently logged into the target, this option sends an asynchro‐
276 nous event message to the initiator.
277
278
279 target --tpgt|-p local_tpgt local_target
280
281 Removes the local_tpgt from local_target. Does not affect existing
282 connections.
283
284
285 initiator --all|-A local_initiator
286
287 Removes information about local_initiator. Does not affect current
288 connections. This option search all targets, seeking those that
289 reference local_initiator. On these, it performs the action defined
290 by the command:
291
292 # iscsitadm delete target --acl local_initiator target
293
294
295
296
297 tpgt --all|-A tpgt_number
298
299 Removes from the system all knowledge of the target portal group
300 identified by tpgt_number. This includes removal of the references
301 by targets to this group.
302
303
304 tpgt --ip-address|-i address tpgt_number
305
306 Removes a NIC's address from the target portal group identified by
307 tpgt_number. Does not affect current connections.
308
309
310 list Options
311 The following are the options and objects for the list subcommand:
312
313 target [--verbose] [local_target]
314 target [-v|-s num] [local_target]
315
316 By default, displays a list of target local names followed by the
317 iSCSI TargetName, as it was created. By specifying local_target,
318 the same information is displayed for that target and can be used
319 to validate the name of local_target. With the --verbose option,
320 information about the target's LUNs and current connections is dis‐
321 played.
322
323 You can use the iostat(1M) command to obtain information on the
324 number of SCSI commands issued and sectors read and written.
325
326
327 initiator [--verbose|-v] local_initiator
328
329 Displays detailed information about local_initiator. Among this
330 data is CHAP information, what target portal groups this initiator
331 belongs to, and any available connections.
332
333
334 tpgt [--verbose|-v] tpgt_number
335
336 Displays detailed information about target group identified by
337 tpgt_number. Among this data is the list of NICs that are a part of
338 this target group.
339
340
341 show Options
342 The following are the options and objects for the show subcommand:
343
344 admin
345
346 Displays a list of administrative information, including the base
347 directory used by the target, CHAP, RADIUS, iSNS, and if fast
348 writes are enabled.
349
350
351 stats [--interval|-I seconds [--count|-N value]] [local_target]
352
353 Displays statistics for all available targets, unless you specify
354 local_target, in which case, displays statistics only for
355 local_target. If you use --interval, displays statistics for an
356 interval specified by seconds. If you do not specify --count, the
357 display continues until you enter a Control-C.
358
359
361 Example 1 Invoking Help
362
363
364 All of the commands shown below are valid ways of invoking help.
365
366
367 # iscsitadm -?
368 # iscsitadm modify -?
369 # iscsitadm modify target -?
370 # iscsitadm --help
371 # iscsitadm create --help
372 # iscsitadm create tpgt --help
373
374
375
376 Example 2 Establishing Backing Store
377
378
379 The following command establishes the default location for the backing
380 store. In addition to the backing store, certain configuration files
381 will be stored in the same location.
382
383
384 # iscsitadm modify admin --base-directory /zfs/data/targets
385
386
387
388
389 The short form of the --base-directory option is -d.
390
391
392 Example 3 Simplest-Case Target Creation
393
394
395 The following command creates a target that will emulate an LBA device
396 that has 10 GB of storage available. With the base directory set up and
397 as well as a single target, it is possible to use the system as an
398 iSCSI target. Note that because the LUN is not specified on the command
399 line, it reverts to the default, 0.
400
401
402 # iscsitadm create target --size 10g playarea
403
404
405
406
407 The short form of the --size option is -z.
408
409
410 Example 4 Creating with Both Size and Backing Store
411
412
413 The following iscsitadm create command specifies LUN size and a backing
414 store location. The result of this command is that the daemon will cre‐
415 ate a LUN file at the named location, of the specified size (20 GB).
416
417
418 # iscsitadm create target -z 20g -b /zfs/mirror/data/payroll payroll
419
420
421
422
423 A target such as the one created by the preceding command might be use‐
424 ful, for example, when most of the LUN can be created in a default
425 area, using whatever redundancy is provided by the underlying file sys‐
426 tem. Alternatively, you might want to create a special LUN on a higher
427 speed storage medium or one with better failover characteristics.
428
429
430
431 The long form of the -z option is --size. The long form of the -b
432 option is --backing-store
433
434
435 Example 5 Specifying a Local Name for a SCSI Initiator
436
437
438 Consider that you want to restrict access to the payroll target, cre‐
439 ated in the previous example, to a limited set of initiators. Because
440 the initiator names can be quite long (and therefore prone to be
441 entered incorrectly), you create a local name for each initiator, as in
442 the command below.
443
444
445 # iscsitadm create initiator --iqn \
446 iqn.1986-03.com.example[node name continues...] multistrada
447
448
449
450
451 The short form of the --iqn option is -q.
452
453
454 Example 6 Granting an Initiator Access to a Target
455
456
457 Upon completion of the command below, only the initiator multistrada is
458 allowed to log into the daemon and access the payroll target. This
459 presents a potential gap in security, which is addressed in the follow‐
460 ing example.
461
462
463 # iscsitadm modify target --acl multistrada payroll
464
465
466
467
468 The short form of the --acl option is -l.
469
470
471 Example 7 Adding CHAP Secret and Name for an Initiator
472
473
474 The initiator is allowed to identify itself. Because of this, it is
475 prudent to add a CHAP secret an name for an initiator. This is accom‐
476 plished with the following command.
477
478
479 # iscsitadm modify initiator -C multistrada
480
481
482
483
484 The preceding command prompts you for a secret to use. This must be the
485 same secret that was setup on the initiator with the local name of mul‐
486 tistrada. If it is not, the target daemon will issue a challenge to
487 multistrada when it attempts to login. A non-matching response will
488 cause the target to drop the connection. If you have many targets that
489 require authentication, it is probably best to setup a RADIUS server to
490 administer the secrets.
491
492
493
494 The long form of the -C option is --chap-secret.
495
496
497 Example 8 Displaying Target Information
498
499
500 The following commands displays information about iSCSI targets.
501
502
503 # iscsitadm list target
504 Target: vol0
505 iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c5250.vol0
506 Target: disk0
507 iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c6f05.disk0
508
509
510
511
512 The following command differs from the preceding in that it uses the
513 verbose (-v) option and it specifies a single target.
514
515
516 # iscsitadm list target -v vol0
517 Target: vol0
518 iSCSI Name: iqn.1986-03.com.sun:01:00093d12170c.434c5250.vol0
519 ACL list:
520 TPGT list:
521 LUN information:
522 LUN: 0
523 GUID: 010000093d12170c00002a00434c5251
524 VID: SUN
525 PID: SOLARIS
526 Type: raw
527 Size: 0x1400000 blocks
528
529
530
531 Example 9 Displaying Administrative Information
532
533
534 The following command uses the show subcommand to display administra‐
535 tive information.
536
537
538 # iscsitadm show admin
539 iscsitadm:
540 Base Directory: /zfs/stress/play/targets
541 CHAP Name: Not set
542 RADIUS Access: Not set
543 RADIUS Server: Not set
544 iSNS Access: Not set
545 Fast Write ACK: Not set
546
547
548
549 Example 10 Displaying Statistics
550
551
552 The following command uses the show subcommand to display statistics.
553
554
555 # iscsitadm show stats
556 operations bandwidth
557 device read write read write
558 -------------------- ----- ----- ----- -----
559 vol0 0 0 0K 0K
560 disk0 0 0 0K 0K
561
562
563
565 0 Command successful.
566
567
568 >0 An error occurred.
569
570
572 See attributes(5) for descriptions of the following attributes:
573
574
575
576
577 ┌─────────────────────────────┬─────────────────────────────┐
578 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
579 ├─────────────────────────────┼─────────────────────────────┤
580 │Availability │SUNWiscsitgtu │
581 ├─────────────────────────────┼─────────────────────────────┤
582 │Interface Stability │Volatile │
583 └─────────────────────────────┴─────────────────────────────┘
584
586 iostat(1M), iscsiadm(1M), getpassphrase(3C), attributes(5), rbac(5),
587 smf(5)
588
590 This command set is considered to be experimental. Future releases,
591 both minor and micro, might introduce incompatible changes to the com‐
592 mand set. A future release will stabilize the command set. Any future
593 changes in stability level will be reflected in the ATTRIBUTES section
594 of this man page.
595
596
597 The iSCSI Target daemon, iscsitgtd, is managed by the service manage‐
598 ment facility (smf(5)), under the fault management resource identifier
599 (FMRI):
600
601 svc:/system/iscsitgt:default
602
603
604
605
606 Use iscsitadm to perform administrative actions, such as are performed
607 by the create, modify, and delete subcommands, on iSCSI Target proper‐
608 ties. Such actions require that you become superuser or assume the Pri‐
609 mary Administrator role. See rbac(5).
610
611
612
613SunOS 5.11 5 Feb 2009 iscsitadm(1M)