1TGTADM(8)                       [FIXME: manual]                      TGTADM(8)
2
3
4

NAME

6       tgtadm - Linux SCSI Target Administration Utility
7

SYNOPSIS

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

DESCRIPTION

24       tgtadm is used to monitor and modify everything about Linux SCSI target
25       software: targets, volumes, etc.
26

OPTIONS

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
33       -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
38           Example:
39
40           tgtadm --lld iscsi --mode logicalunit --op new \
41                  --tid <TID> --lun <LUN> \
42                  -b <backing-file> --blocksize=4096
43
44
45       -Y, --device-type <type>
46           When creating a LUN, this parameter specifies the type of device to
47           create. Default is disk.
48
49           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
57
58       -E, --bstype <type>
59           When creating a LUN, this parameter specifies the type of backend
60           storage to to use.
61
62           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
67               sg      : Special backend type for passthrough devices
68               ssc     : Special backend type for tape emulation
69
70
71       --lld <driver> --op new --mode target --tid <id> --targetname <name>
72           Add a new target with <id> and <name>.
73
74       --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
78       --lld <driver> --op delete --force --mode target --tid <id>
79           Delete specific target forcibly with <id>.
80
81       --lld <driver> --op show --mode target
82           Show all the targets.
83
84       --lld <driver> --op show --mode target --tid <id>
85           Show target parameters of a target with <id>.
86
87       --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
95               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
101               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
105
106
107       --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
111       --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
117       --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
122       --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
126       --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
131       --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
135       --lld <driver> --op update --mode target --tid <id> --params
136       parameter=value<,...>
137           Sets/changes the value of one or more target parameters.
138
139       --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
143       --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
148       --help
149           Display a list of available options and exits.
150

LUN PARAMETERS

152       These parameters are only applicable for "--mode logicalunit".
153
154       vendor_id=<string>
155           This parameter sets the Vendor Identification string that a LUN
156           will report in INQURY data.
157
158       product_id=<string>
159           This parameter sets the Product Identification string that a LUN
160           will report in INQURY data.
161
162       product_rev=<string>
163           This parameter sets the Product Revision string that a LUN will
164           report in INQURY data.
165
166           Example:
167
168           tgtadm --lld iscsi --mode logicalunit --op update \
169                  --tid <TID> --lun <LUN> \
170                  --params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103
171
172
173       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
178       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
182       online=<0|1>
183           This controls whether a device is online or not.
184
185           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
192           Example:
193
194           tgtadm --lld iscsi --mode logicalunit --op update \
195                  --tid 1 --lun 1 \
196                  --params removable=1,sense_format=1,online=1
197
198
199       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
205           Examples:
206
207           Create mode page '2', subpage 0 and 14 bytes of data.
208           This is Disconnect-Reconnect mode page.
209
210           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
213
214           Create mode page '10', subpage 0 and 10 bytes of data.
215           This is Control Extension mode page.
216
217           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
220
221           Create mode page '0x1c', subpage 0 and 10 bytes of data.
222           This is Informational Exceptions Control mode page.
223
224           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
227
228       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
232           This parameter only applies to DISK devices.
233
234           tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
235                    --params readonly=1
236
237
238       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
245           This parameter only applies to DISK devices.
246
247           Thin-provisioning only works for LUNs stored on filesystems that
248           support FALLOC_FL_PUNCH_HOLE.
249
250           tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
251                    --params thin_provisioning=1
252
253

SMC SPECIFIC LUN PARAMETERS

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
259       element_type=<1|2|3|4>
260           This controls which type of element a certain slot in the
261           jukebox/vtl is.
262
263               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
269
270       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
274       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
279       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
283       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
288       barcode=<string>
289           This is used to assign a barcode to an element. Barcodes are
290           limited to 10 characters in tgtd.
291
292       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
297       media_home=<string>
298           This parameter specifies a directory where all virtual media for
299           the dvd/tape device elements are stored.
300
301           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
305           Example: How to create a DVD jukebox with eight disk trays and
306           two empty DVD-R disks.
307
308
309           # Create a target
310           tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn.2007-03:virtual-dvd:`hostname`
311
312           # 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
317           # 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
322           # 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
326           # 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
329           # 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
332           # 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
335           # 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
340           # 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
343           # 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
349           # 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
353           # Allow ALL initiators to connect to this target
354           tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL
355
356           # Show all our good work.
357           tgtadm --lld iscsi --mode target --op show
358
359

PASSTHROUGH DEVICES

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
365       --bstype=sg
366           This specifies that an SG devices is used.
367
368       --device-type=pt
369           This specifies that passthrough device type is used.
370
371       --backing-store=</dev/sg4>
372           This specifies which device to export through TGTD.
373
374       --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
379           Example:
380           Make /dev/sg4 available to initiators connecting to TGTD.
381
382           tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4
383
384           Example:
385           Open the backing file with O_SYNC.
386
387           tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bsoflags="sync" --backing-store=/data/100m_image.raw
388
389
390

HEADER DIGEST AND DATA DIGEST

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
397   Viewing the current settings
398       This command is used to view the current settings for header/data
399       digest.
400
401           tgtadm --op show --mode target --tid 1
402             ...
403             HeaderDigest=None
404             DataDigest=None
405             ...
406
407
408   Setting digest
409           Set header digest to CRC32C:
410           tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C
411
412           Set data digest to None:
413           tgtadm --op update --mode target --tid 1 -n DataDigest -v None
414
415

CHAP AUTHENTICATION

417       CHAP authentication is supported to require authentication before an
418       initiator is allowed to log in and access devices.
419
420       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
424   Setting CHAP on a target
425       These two commands create a user account and binds it to target 1.
426
427           tgtadm --lld iscsi --op new --mode account --user ronnie --password password
428           tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie
429
430
431   List all accounts
432       This command is used to list all accounts that have been created.
433
434           tgtadm --lld iscsi --op show --mode account
435           Account list:
436               ronnie
437
438
439   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
443           tgtadm --lld iscsi --op show --mode target
444           Target 1: iqn.ronnie.test
445           ...
446           Account information:
447               ronnie
448           ...
449
450

NOP-OUT PROBES

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
458   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
462       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
466           tgtadm --lld iscsi --op show --mode target
467
468           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
476
477   Setting NOP-OUT for a target
478       The tgtadm command is used to change the NOP-OUT settings.
479
480           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
483

ISCSI PORTALS

485       iSCSI portals can be viewed, added and removed at runtime.
486
487   List portals
488       This command is used to list the current iSCSI portals defined on the
489       target:
490
491           tgtadm --lld iscsi --op show --mode portal
492           Portal: 10.1.1.101:3260,1
493           Portal: 127.0.0.1:3260,1
494
495
496   Add portal
497       This command is used to add a portal to the target :
498
499           tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260
500
501
502   Remove portal
503       This command is used to remove a portal from the target :
504
505           tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260
506
507

ISCSI CONNECTIONS

509       iSCSI connections can be viewed and forced closed at runtime.
510
511   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
516           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
522
523   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
527           tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0
528
529

ONLINE/OFFLINE STATUS

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
536       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
541   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
546           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
558
559   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
564       Change a LUN to become offline. (no disk in the drive)
565
566           tgtadm --tid 1 --lun 2 --op update --mode logicalunit -P Online=No
567
568

ISNS PARAMETERS

570       iSNS configuration for a target is by using the tgtadm command.
571
572       iSNSServerIP
573           This specifies the IP address of the iSNS server. TGTD only
574           supprots one iSNS server.
575
576           Example:
577
578           tgtadm --op update --mode sys --name iSNSServerIP --value 192.168.11.133
579
580
581       iSNS
582           This setting enables(on)/disables(off) iSNS.
583
584           Example:
585
586           tgtadm --op update --mode sys --name iSNS --value On
587
588
589       iSNSServerPort
590           This setting specifies the port to use for iSNS.
591
592           Example:
593
594           tgtadm --op update --mode sys --name iSNSServerPort --value 3205
595
596
597       iSNSAccessControl
598           Enable/disable access control for iSNS.
599
600           Example:
601
602           tgtadm --op update --mode sys --name iSNSAccessControl --value Off
603
604

SEE ALSO

606       tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8).
607       http://stgt.sourceforge.net/
608

REPORTING BUGS

610       Report bugs to <stgt@vger.kernel.org>
611
612
613
614[FIXME: source]                   07/29/2020                         TGTADM(8)
Impressum