1iscsitadm(1M) System Administration Commands iscsitadm(1M)
2
6 iscsitadm - administer iSCSI targets
7
9 iscsitadm create [-? | --help] object [-? | --help]
10 [options] operand
11 iscsitadm modify [-? | --help] object [-? | --help]
14 [options] operand
15 iscsitadm delete [-? | --help] object [-? | --help]
18 [options] operand
19 iscsitadm list [-? | --help] object [-? | --help] [options]
22 operand
23 iscsitadm show [-? | --help] admin
26 iscsitadm show [-? | --help] object [-? | --help] [options]
29 [operand]
30 iscsitadm -? --help
33
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 The iscsitadm command has the following subcommands:
42 create Creates a target using a local target as a reference.
44 modify Modifies a target or a list of targets.
47 delete Deletes a target or a list of targets.
50 list Lists names and information about targets.
53 show Displays target-related statistics.
56 The preceding subcommands work on the following objects:
60 target An iSCSI target node, or list of target nodes.
62 initiator An iSCSI initiator node, or list of initiator nodes.
65 admin Stores administrative information, such as server loca‐
68 tions and passwords.
69 tpgt Stands for TargetPortGroupTag. A number that represents a
72 list of connections that an initiator can use for a given
73 target.
74 stats Displays statistics; can accept interval and count values.
77 Used only with the show subcommand.
78 These objects are discussed in greater detail under the options
82 descriptions for each subcommand.
83 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 create Options
96 The following are the options and objects for the create subcommand:
97 target --size|-z lun_size [--lun number]
99 [--type disk|tape|raw] [--backing-store|-b pathname] local_name
100 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 k kilobyte
107 m megabyte
110 g gigabyte
113 t terabyte
116 --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 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 initiator --iqn|-n iSCSI_node_name local_initiator
136 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 tpgt tpgt_number
145 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 modify Options
156 The following are the options and objects for the modify subcommand:
157 target --tpgt|-p local_tpgt local_target
159 Specifies one or more target portal groups to use when initiators
161 reference local_target during discovery.
162 target --acl|-l local_initiator local_target
165 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 target --alias|-a TargetAlias local_target
172 Sets the alias if it was not done during the creation of the target
174 or change an existing target's alias.
175 target --maxrecv|-m value local_target
178 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 initiator --chap-secret|-C local_initiator
185 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 initiator --chap-name|-H value local_initiator
192 Specifies the CHAP username used during authentication.
194 tpgt --ip-address|-i address tpgt_number
197 Adds the NIC's address to tpgt_number.
199 admin --base-directory|-d directory
202 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 admin --chap-secret|-C
210 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 admin --chap-name|-H value
217 Specifies the user name portion of the CHAP protocol.
219 admin --radius-access|-R enable | disable
222 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 admin --radius-server|-r hostname:port
231 Location of RADIUS server. hostname can be either a resolvable name
233 or an IP address.
234 admin --radius-secret|-P
237 Used to initiate contact with the RADIUS server. Interaction with
239 server uses getpassphrase(3C).
240 admin --isns-access|-S enable | disable
243 Enables or disables access to an iSNS server. iSNS servers broad‐
245 cast their locations.
246 admin --isns-server|-s hostname
249 Location of the iSNS server. "hostname" can be either a resolvable
251 host name or an IP address.
252 admin --fast-write-ack|-f enable | disable
255 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 delete Options
264 The following are the options and objects for the delete subcommand:
265 target --lun|-u lun_number local_target
267 Removes information about the LUN identified by lun_number. This
269 includes the data that is stored in the LUNs.
270 target --acl|-l local_initiator local_target
273 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 target --tpgt|-p local_tpgt local_target
280 Removes the local_tpgt from local_target. Does not affect existing
282 connections.
283 initiator --all|-A local_initiator
286 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 # iscsitadm delete target --acl local_initiator target
293 tpgt --all|-A tpgt_number
298 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 tpgt --ip-address|-i address tpgt_number
305 Removes a NIC's address from the target portal group identified by
307 tpgt_number. Does not affect current connections.
308 list Options
311 The following are the options and objects for the list subcommand:
312 target [--verbose] [local_target]
314 target [-v|-s num] [local_target]
315 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 You can use the iostat(1M) command to obtain information on the
324 number of SCSI commands issued and sectors read and written.
325 initiator [--verbose|-v] local_initiator
328 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 tpgt [--verbose|-v] tpgt_number
335 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 show Options
342 The following are the options and objects for the show subcommand:
343 admin
345 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 stats [--interval|-I seconds [--count|-N value]] [local_target]
352 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
361 Example 1 Invoking Help
362 All of the commands shown below are valid ways of invoking help.
365 # iscsitadm -?
368 # iscsitadm modify -?
369 # iscsitadm modify target -?
370 # iscsitadm --help
371 # iscsitadm create --help
372 # iscsitadm create tpgt --help
373 Example 2 Establishing Backing Store
377 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 # iscsitadm modify admin --base-directory /zfs/data/targets
385 The short form of the --base-directory option is -d.
390 Example 3 Simplest-Case Target Creation
393 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 # iscsitadm create target --size 10g playarea
403 The short form of the --size option is -z.
408 Example 4 Creating with Both Size and Backing Store
411 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 # iscsitadm create target -z 20g -b /zfs/mirror/data/payroll payroll
419 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 The long form of the -z option is --size. The long form of the -b
432 option is --backing-store
433 Example 5 Specifying a Local Name for a SCSI Initiator
436 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 # iscsitadm create initiator --iqn \
446 iqn.1986-03.com.example[node name continues...] multistrada
447 The short form of the --iqn option is -q.
452 Example 6 Granting an Initiator Access to a Target
455 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 # iscsitadm modify target --acl multistrada payroll
464 The short form of the --acl option is -l.
469 Example 7 Adding CHAP Secret and Name for an Initiator
472 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 # iscsitadm modify initiator -C multistrada
480 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 The long form of the -C option is --chap-secret.
495 Example 8 Displaying Target Information
498 The following commands displays information about iSCSI targets.
501 # 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 The following command differs from the preceding in that it uses the
513 verbose (-v) option and it specifies a single target.
514 # 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 Example 9 Displaying Administrative Information
532 The following command uses the show subcommand to display administra‐
535 tive information.
536 # 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 Example 10 Displaying Statistics
550 The following command uses the show subcommand to display statistics.
553 # 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
565 0 Command successful.
566 >0 An error occurred.
569
572 See attributes(5) for descriptions of the following attributes:
573 ┌─────────────────────────────┬─────────────────────────────┐
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 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 svc:/system/iscsitgt:default
602 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).
610SunOS 5.11 5 Feb 2009 iscsitadm(1M)