1TGTADM(8) [FIXME: manual] TGTADM(8)
2
6 tgtadm - Linux SCSI Target Administration Utility
7
9 tgtadm [OPTIONS]... [-C --control-port <port>] [-L --lld <driver>]
10 [-o --op <operation>] [-m --mode <mode>]
11 [-t --tid <id>] [-T --targetname <targetname>]
12 [-y --blocksize <size>] [-Y --device-type <type>]
13 [-l --lun <lun>] [-b --backing-store <path>]
14 [-f --bsoflags {direct|sync}]
15 [-S --bsopts {backing-store opt string}]
16 [-E --bstype <type>]
17 [-I --initiator-address <address>]
18 [-Q --initiator-name <name>]
19 [-n --name <parameter>] [-v --value <value>]
20 [-P --params <param=value[,param=value...]>]
21 [-F --force] [-h --help]
22
24 tgtadm is used to monitor and modify everything about Linux SCSI target
25 software: targets, volumes, etc.
26
28 -C, --control-port <port>
29 It is possible to run multiple concurrent instances of tgtd on a
30 host. This argument is used to control which instance the tgtadm
31 command will operate on.
32 -y, --blocksize <size>
34 Block devices are created with a default block size of 512 bytes.
35 This argument can be used to create block devices with different
36 block sizes.
37 Example:
39 tgtadm --lld iscsi --mode logicalunit --op new \
41 --tid <TID> --lun <LUN> \
42 -b <backing-file> --blocksize=4096
43 -Y, --device-type <type>
46 When creating a LUN, this parameter specifies the type of device to
47 create. Default is disk.
48 Possible device-types are:
50 disk : emulate a disk device
51 tape : emulate a tape reader
52 ssc : same as tape
53 cd : emulate a DVD drive
54 changer : emulate a media changer device
55 pt : passthrough type to export a /dev/sg device
56 -E, --bstype <type>
59 When creating a LUN, this parameter specifies the type of backend
60 storage to to use.
61 Possible backend types are:
63 rdwr : Use normal file I/O. This is the default for disk devices
64 aio : Use Asynchronous I/O
65 rbd : Use Ceph's distributed-storage RADOS Block Device
66 sg : Special backend type for passthrough devices
68 ssc : Special backend type for tape emulation
69 --lld <driver> --op new --mode target --tid <id> --targetname <name>
72 Add a new target with <id> and <name>.
73 --lld <driver> --op delete --mode target --tid <id>
75 Delete specific target with <id>. The target must have no active
76 I_T nexus.
77 --lld <driver> --op delete --force --mode target --tid <id>
79 Delete specific target forcibly with <id>.
80 --lld <driver> --op show --mode target
82 Show all the targets.
83 --lld <driver> --op show --mode target --tid <id>
85 Show target parameters of a target with <id>.
86 --lld <driver> --op new --mode logicalunit --tid <id> --lun <lun>
88 --backing-store <path> --bsopts=<backing store options>
89 Add a new logical unit with <lun> to specific target with <id>. The
90 logical unit is offered to the initiators. <path> must be block
91 device files (including LVM and RAID devices) or regular files, or
92 an RBD image or snapshot name for --bstype rbd. lun0 is reserved
93 for a special device automatically created.
94 Example:
96 If tgt is compiled with the bs_rbd backing store for
97 Ceph RBD images (see tgtadm --mode system --op show to
98 verify), set up a target mapping the rbd image named
99 "rbdimage", and pass options to bs_rbd:
100 tgtadm --lld iscsi --op new --mode logicalunit --tid 1 \
102 --lun 1 --bstype=rbd --backing-store=rbdimage \
103 --bsopts="conf=/etc/ceph/ceph.conf;id=tgt"
104 --lld <driver> --op delete --mode logicalunit --tid <id> --lun <lun>
108 Delete specific logical unit with <lun> that the target with <id>
109 has.
110 --lld <driver> --op bind --mode target --tid <id> --initiator-address
112 <address>
113 Add the address to the access lists of the target with <id>.
114 Initiators with the address can access to the target. 'ALL' is a
115 special address to allow all initiators to access to a target.
116 --lld <driver> --op bind --mode target --tid <id> --initiator-name
118 <name>
119 Add the initiator's name to the access lists of the target with
120 <id>. Initiators with the names can access to the target.
121 --lld <driver> --op unbind --mode target --tid <id> --initiator-address
123 <address>
124 Delete the address from the access lists of the target with <id>.
125 --lld <driver> --op unbind --mode target --tid <id> --initiator-name
127 <name>
128 Delete the initiator's name from the access lists of the target
129 with <id>.
130 --lld <driver> --op update --mode target --tid <id> --name=<parameter>
132 --value=<value>
133 Change the value of <parameter> of the target with <id> to <value>.
134 --lld <driver> --op update --mode target --tid <id> --params
136 parameter=value<,...>
137 Sets/changes the value of one or more target parameters.
138 --lld <driver> --op update --mode logicalunit --tid <id> --lun <id>
140 --params parameter=value<,...>
141 Sets/changes the value of one or more logical unit parameters.
142 --lld <driver> --op start --mode lld
144 Start the specified lld without restarting the tgtd process. Can be
145 used to initialize lld driver in case required modules were loaded
146 after tgtd was already executed.
147 --help
149 Display a list of available options and exits.
150
152 These parameters are only applicable for "--mode logicalunit".
153 vendor_id=<string>
155 This parameter sets the Vendor Identification string that a LUN
156 will report in INQURY data.
157 product_id=<string>
159 This parameter sets the Product Identification string that a LUN
160 will report in INQURY data.
161 product_rev=<string>
163 This parameter sets the Product Revision string that a LUN will
164 report in INQURY data.
165 Example:
167 tgtadm --lld iscsi --mode logicalunit --op update \
169 --tid <TID> --lun <LUN> \
170 --params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103
171 removable=<0|1>
174 This can be used to override/change the default setting for the
175 removable flag. Disk devices default to non-removable while DVD and
176 TAPE devices default to removable.
177 sense_format=<0|1>
179 This flag controls the format of sense data that the device will
180 return. 0 = Clasic sense format, 1 = Support descriptor format.
181 online=<0|1>
183 This controls whether a device is online or not.
184 Devices default to be online when created but can be brought
186 offline using this parameter. Behaviour of offline devices depend
187 on device type. An MMC/DVD device that is offline will report that
188 there is no disk in the unit but the actual MMC/DVD unit itself can
189 still be communicated with. All other device types will fail all
190 I/O with a sense code of Not Ready.
191 Example:
193 tgtadm --lld iscsi --mode logicalunit --op update \
195 --tid 1 --lun 1 \
196 --params removable=1,sense_format=1,online=1
197 mode_page=<byte-string>
200 This parameter is used to set specific mode pages for the device
201 and the mode page contents. Most devices default to reasonable
202 default mode pages automatically when the LUN is created, but this
203 allows special settings.
204 Examples:
206 Create mode page '2', subpage 0 and 14 bytes of data.
208 This is Disconnect-Reconnect mode page.
209 tgtadm --mode logicalunit --op update --tid 1 --lun 2 \
211 --params mode_page=2:0:14:0x80:0x80:0:0xa:0:0:0:0:0:0:0:0:0:0
212 Create mode page '10', subpage 0 and 10 bytes of data.
215 This is Control Extension mode page.
216 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
218 --params mode_page=10:0:10:2:0:0:0:0:0:0:0:2:0
219 Create mode page '0x1c', subpage 0 and 10 bytes of data.
222 This is Informational Exceptions Control mode page.
223 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
225 --params mode_page=0x1c:0:10:8:0:0:0:0:0:0:0:0:0
226 readonly=<0|1>
229 This sets the read-only flag of a LUN. A read-only LUN will refuse
230 any attempts to write data to it.
231 This parameter only applies to DISK devices.
233 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
235 --params readonly=1
236 thin_provisioning=<0|1>
239 This controls the provisioning for the LUN. A thin-provisioned LUN
240 is represented as a sparse file. TGTD supports provisioning type 2
241 for sparse files. When initiators use the SCSI UNMAP command TGTD
242 will release the affected areas back to the filesystem using
243 FALLOC_FL_PUNCH_HOLE.
244 This parameter only applies to DISK devices.
246 Thin-provisioning only works for LUNs stored on filesystems that
248 support FALLOC_FL_PUNCH_HOLE.
249 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
251 --params thin_provisioning=1
252
255 These parameters are only applicable for luns that are of type
256 "changer" i.e. the media changer device for a DVD Jukebox or a Virtual
257 Tape Library.
258 element_type=<1|2|3|4>
260 This controls which type of element a certain slot in the
261 jukebox/vtl is.
262 Slot types:
264 1 -> Medium Transport (picker arm)
265 2 -> Storage Element
266 3 -> Import/Export Element
267 4 -> Data Transfer device (CD drive, tape drive, MO drive etc)
268 address=<1-65535>
271 This is used to create/operate on a single slot. Address specifies
272 the slot on which to perform the operation.
273 start_address=<1-65535>,quantity=<1--65535>
275 This is used to create/operate on an entire range of slots at once.
276 Start_address specifies the first address to operate on and
277 quantity specifies the number of consequtive slots.
278 sides=<1|2>
280 When creating storage elements, i.e. "element_type=2", this
281 parameter specifies if the media has 1 or two sides to hold data.
282 clear_slot=<1>
284 This option is used to clear a storage element and remove any media
285 that may be present. Once this command completes the storage
286 element will show up as "Empty".
287 barcode=<string>
289 This is used to assign a barcode to an element. Barcodes are
290 limited to 10 characters in tgtd.
291 volume_tag=<string>
293 This is used to assign a volume tag to SMC storage elements. If no
294 volume tag is specified tgtd will use fall back to the barcode. The
295 volume tag can be up to 32 characters.
296 media_home=<string>
298 This parameter specifies a directory where all virtual media for
299 the dvd/tape device elements are stored.
300 To assign a media image file to a storage element slot, you assign
302 "barcode" to be the name of the image file in the "media_home"
303 directory.
304 Example: How to create a DVD jukebox with eight disk trays and
306 two empty DVD-R disks.
307 # Create a target
310 tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn.2007-03:virtual-dvd:`hostname`
311 # Create a DVD drive and give it a nice name
313 # The dvd starts out without a backing store file, i.e. no disk loaded
314 tgtadm --op new --mode logicalunit --tid 1 --lun 1 --device-type cd
315 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 --params vendor_id=STGT_DVD,product_id=DVD101,product_rev=0010,scsi_sn=STGTDVD01,removable=1
316 # We need a backend store file for the media changer
318 if [ ! -f $HOME/smc ]; then
319 dd if=/dev/zero of=$HOME/smc bs=1k count=1
320 fi
321 # Create the SMC device and give it a nice name
323 tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 --backing-store $HOME/smc --device-type changer
324 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params vendor_id=STK,product_id=L700,product_rev=0010,scsi_sn=XYZZY_0,removable=1
325 # Add a Data Transfer devices (1 drive)
327 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,start_address=1,quantity=1
328 # Specify that the DVD above (LUN 1) is the data transfer device we created
330 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,address=1,tid=1,lun=1
331 # Medium Transport Elements (robot arm / picker)
333 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=1,start_address=16,quantity=1
334 # define path to virtual media
336 VTL=${HOME}/vtl
337 mkdir -p ${VTL}
338 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params media_home=${VTL}
339 # Storage Elements - 8 starting at addr 1024
341 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,start_address=1024,quantity=8
342 # Add 'media' to slots 1 and 2 and leave the other 6 slots empty
344 # slot 1
345 # Create empty writeable virtual DVD-R media
346 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_001
347 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1024,barcode=DISK_001,volume_tag="A blank disk",sides=1
348 # slot 2
350 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_002
351 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1025,barcode=DISK_002,volume_tag="My second blank disk",sides=1
352 # Allow ALL initiators to connect to this target
354 tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL
355 # Show all our good work.
357 tgtadm --lld iscsi --mode target --op show
358
361 In addition to device emulation TGTD also supports utilizing existing
362 SG devices on the host and exporting these through a special
363 passthrough device type.
364 --bstype=sg
366 This specifies that an SG devices is used.
367 --device-type=pt
369 This specifies that passthrough device type is used.
370 --backing-store=</dev/sg4>
372 This specifies which device to export through TGTD.
373 --bsoflags={direct|sync}
375 This argument is used when creating a LUN to specify extra flags to
376 use when opening the backing file. O_DIRECT is specified by
377 "direct" and O_SYNC by "sync".
378 Example:
380 Make /dev/sg4 available to initiators connecting to TGTD.
381 tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4
383 Example:
385 Open the backing file with O_SYNC.
386 tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bsoflags="sync" --backing-store=/data/100m_image.raw
388
392 Header and data digests can be set on a per target parameter. TGTD
393 supports two modes, None and CRC32C. When the digest is set to None,
394 TDTD will negotiate that digests will not be used, and when CRC32C is
395 set, TGTD will force the connection to use digest.
396 Viewing the current settings
398 This command is used to view the current settings for header/data
399 digest.
400 tgtadm --op show --mode target --tid 1
402 ...
403 HeaderDigest=None
404 DataDigest=None
405 ...
406 Setting digest
409 Set header digest to CRC32C:
410 tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C
411 Set data digest to None:
413 tgtadm --op update --mode target --tid 1 -n DataDigest -v None
414
417 CHAP authentication is supported to require authentication before an
418 initiator is allowed to log in and access devices.
419 CHAP main-phase authentication is set on the target level. To set up
421 CHAP authentication we first need to create an account and its
422 associated password, then we bind the account to one or more targets.
423 Setting CHAP on a target
425 These two commands create a user account and binds it to target 1.
426 tgtadm --lld iscsi --op new --mode account --user ronnie --password password
428 tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie
429 List all accounts
432 This command is used to list all accounts that have been created.
433 tgtadm --lld iscsi --op show --mode account
435 Account list:
436 ronnie
437 Show if a target requires authentication
440 When listing the targets, each target that has authantication enabled
441 will contain a listing of all accoutns bound to that target.
442 tgtadm --lld iscsi --op show --mode target
444 Target 1: iqn.ronnie.test
445 ...
446 Account information:
447 ronnie
448 ...
449
452 TGTD can send NOP-OUT probes to connected initiators to determine when
453 an initiator is dead and then automatically clear and tear down the TCP
454 connection. This can either be set as a global default from the tgtd
455 command-line or it can be set for individual targets using the tgtadm
456 command.
457 Check the current NOP-OUT setting
459 The tgtadm command is used to view the current setting for if/when to
460 send NOP-OUT probes to connected initiators.
461 If the target is configured to send NOP-OUT probes this will show up as
463 two parameter lines in the target printout. If the target is not
464 configured to send NOP-OUT these lines will not be printed at all.
465 tgtadm --lld iscsi --op show --mode target
467 Target 1: iqn.ronnie.test
469 System information:
470 Driver: iscsi
471 State: ready
472 Nop interval: 5
473 Nop count: 5
474 I_T nexus information:
475 Setting NOP-OUT for a target
478 The tgtadm command is used to change the NOP-OUT settings.
479 tgtadm --op update --mode target --tid 1 -n nop_count -v 5
481 tgtadm --op update --mode target --tid 1 -n nop_interval -v 5
482
485 iSCSI portals can be viewed, added and removed at runtime.
486 List portals
488 This command is used to list the current iSCSI portals defined on the
489 target:
490 tgtadm --lld iscsi --op show --mode portal
492 Portal: 10.1.1.101:3260,1
493 Portal: 127.0.0.1:3260,1
494 Add portal
497 This command is used to add a portal to the target :
498 tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260
500 Remove portal
503 This command is used to remove a portal from the target :
504 tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260
506
509 iSCSI connections can be viewed and forced closed at runtime.
510 List all active connections for a target
512 This command is used to list the all the active iSCSI connections to
513 the target with connection id, initiator name and ip address for the
514 initiator :
515 tgtadm --lld iscsi --op show --mode conn --tid 1
517 Session: 2
518 Connection: 0
519 Initiator: iqn.2008-11.org.linux-kvm:
520 IP Address: 127.0.0.1
521 Close an existing connection
524 This command is used to close an iSCSI connection. Note that forcibly
525 closing iSCSI connections can lead to data-loss.
526 tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0
528
531 Tgtd LUNs can be in online or offline status. LUNs that are Offline
532 behave slightly different depending on the device type. Offline devices
533 behave as if there is no media available and any operations that access
534 media will fail with an check-condition error.
535 Devices can not be set to Offline mode while there are "PREVENT ALLOW
537 MEDIUM REMOVAL" locks on the device. Similarly media in Online devices
538 can not be software ejected while there are such locks on the device
539 (the 'eject' command will fail).
540 Show Online/Offline status
542 Finding the Online/Offline status of a LUN is done through the tgtd
543 command. If "Prevent removal" is "Yes" this indicates that an
544 application holds a "prevent media removal" lock on the device.
545 tgtadm --lld iscsi --mode target --op show
547 ...
548 LUN: 2
549 Type: cd/dvd
550 SCSI ID: IET 00010002
551 SCSI SN: beaf12
552 Size: 3432 MB, Block size: 1
553 Online: Yes
554 Removable media: Yes
555 Prevent removal: Yes
556 ...
557 Changing a LUN to Offline
560 A LUN is changed to Offline status using the tgtadm command. When
561 devices are set Offline these devices will behave as if there is no
562 media loaded into the drive.
563 Change a LUN to become offline. (no disk in the drive)
565 tgtadm --tid 1 --lun 2 --op update --mode logicalunit -P Online=No
567
570 iSNS configuration for a target is by using the tgtadm command.
571 iSNSServerIP
573 This specifies the IP address of the iSNS server. TGTD only
574 supprots one iSNS server.
575 Example:
577 tgtadm --op update --mode sys --name iSNSServerIP --value 192.168.11.133
579 iSNS
582 This setting enables(on)/disables(off) iSNS.
583 Example:
585 tgtadm --op update --mode sys --name iSNS --value On
587 iSNSServerPort
590 This setting specifies the port to use for iSNS.
591 Example:
593 tgtadm --op update --mode sys --name iSNSServerPort --value 3205
595 iSNSAccessControl
598 Enable/disable access control for iSNS.
599 Example:
601 tgtadm --op update --mode sys --name iSNSAccessControl --value Off
603
606 tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8).
607 http://stgt.sourceforge.net/
608
610 Report bugs to <stgt@vger.kernel.org>
611[FIXME: source] 01/21/2023 TGTADM(8)