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 --device-type <type>] [-l --lun <lun>]
13 [-b --backing-store <path>] [-E --bstype <type>]
14 [-I --initiator-address <address>]
15 [-Q --initiator-name <name>]
16 [-n --name <parameter>] [-v --value <value>]
17 [-P --params <param=value[,param=value...]>]
18 [-F --force] [-h --help]
19
21 tgtadm is used to monitor and modify everything about Linux SCSI target
22 software: targets, volumes, etc.
23
25 -C, --control-port <port>
26 It is possible to run multiple concurrent instances of tgtd on a
27 host. This argument is used to control which instance the tgtadm
28 command will operate on.
29 -Y, --device-type <type>
31 When creating a LUN, this parameter specifies the type of device to
32 create. Default is disk.
33 Possible device-types are:
35 disk : emulate a disk device
36 tape : emulate a tape reader
37 ssc : same as tape
38 cd : emulate a DVD drive
39 changer : emulate a media changer device
40 pt : passthrough type to export a /dev/sg device
41 -E, --bstype <type>
44 When creating a LUN, this parameter specifies the type of backend
45 storage to to use.
46 Possible backend types are:
48 rdwr : Use normal file I/O. This is the default for disk devices
49 aio : Use Asynchronous I/O
50 sg : Special backend type for passthrough devices
52 ssc : Special backend type for tape emulation
53 --lld <driver> --op new --mode target --tid <id> --targetname <name>
56 Add a new target with <id> and <name>.
57 --lld <driver> --op delete --mode target --tid <id>
59 Delete specific target with <id>. The target must have no active
60 I_T nexus.
61 --lld <driver> --op delete --force --mode target --tid <id>
63 Delete specific target forcibly with <id>.
64 --lld <driver> --op show --mode target
66 Show all the targets.
67 --lld <driver> --op show --mode target --tid <id>
69 Show target parameters of a target with <id>.
70 --lld <driver> --op new --mode logicalunit --tid <id> --lun <lun>
72 --backing-store <path>
73 Add a new logical unit with <lun> to specific target with <id>. The
74 logical unit is offered to the initiators. <path> must be block
75 device files (including LVM and RAID devices) or regular files.
76 lun0 is reserved for a special device automatically created.
77 --lld <driver> --op delete --mode logicalunit --tid <id> --lun <lun>
79 Delete specific logical unit with <lun> that the target with <id>
80 has.
81 --lld <driver> --op bind --mode target --tid <id> --initiator-address
83 <address>
84 Add the address to the access lists of the target with <id>.
85 Initiators with the address can access to the target. ´ALL´ is a
86 special address to allow all initiators to access to a target.
87 --lld <driver> --op bind --mode target --tid <id> --initiator-name
89 <name>
90 Add the initiator´s name to the access lists of the target with
91 <id>. Initiators with the names can access to the target.
92 --lld <driver> --op unbind --mode target --tid <id> --initiator-address
94 <address>
95 Delete the address from the access lists of the target with <id>.
96 --lld <driver> --op unbind --mode target --tid <id> --initiator-name
98 <name>
99 Delete the initiator´s name from the access lists of the target
100 with <id>.
101 --lld <driver> --op update --mode target --tid <id> --name=<parameter>
103 --value=<value>
104 Change the value of <parameter> of the target with <id> to <value>.
105 --lld <driver> --op update --mode target --tid <id> --params
107 parameter=value<,...>
108 Sets/changes the value of one or more parameters.
109 --help
111 Display a list of available options and exits.
112
114 These parameters are only applicable for "--mode logicalunit".
115 vendor_id=<string>
117 This parameter sets the Vendor Identification string that a LUN
118 will report in INQURY data.
119 product_id=<string>
121 This parameter sets the Product Identification string that a LUN
122 will report in INQURY data.
123 product_rev=<string>
125 This parameter sets the Product Revision string that a LUN will
126 report in INQURY data.
127 Example:
129 tgtadm --lld iscsi --mode logicalunit --op update \
131 --tid <TID> --lun <LUN> \
132 --params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103
133 removable=<0|1>
136 This can be used to override/change the default setting for the
137 removable flag. Disk devices default to non-removable while DVD and
138 TAPE devices default to removable.
139 sense_format=<0|1>
141 This flag controls the format of sense data that the device will
142 return. 0 = Clasic sense format, 1 = Support descriptor format.
143 online=<0|1>
145 This controls whether a device is online or not.
146 Devices default to be online when created but can be brought
148 offline using this parameter. Behaviour of offline devices depend
149 on device type. An MMC/DVD device that is offline will report that
150 there is no disk in the unit but the actual MMC/DVD unit itself can
151 still be communicated with. All other device types will fail all
152 I/O with a sense code of Not Ready.
153 Example:
155 tgtadm --lld iscsi --mode logicalunit --op update \
157 --tid 1 --lun 1 \
158 --params removable=1,sense_format=1,online=1
159 mode_page=<byte-string>
162 This parameter is used to set specific mode pages for the device
163 and the mode page contents. Most devices default to reasonable
164 default mode pages automatically when the LUN is created, but this
165 allows special settings.
166 Examples:
168 Create mode page ´2´, subpage 0 and 14 bytes of data.
170 This is Disconnect-Reconnect mode page.
171 tgtadm --mode logicalunit --op update --tid 1 --lun 2 \
173 --params mode_page=2:0:14:0x80:0x80:0:0xa:0:0:0:0:0:0:0:0:0:0
174 Create mode page ´10´, subpage 0 and 10 bytes of data.
177 This is Control Extension mode page.
178 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
180 --params mode_page=10:0:10:2:0:0:0:0:0:0:0:2:0
181 Create mode page ´0x1c´, subpage 0 and 10 bytes of data.
184 This is Informational Exceptions Control mode page.
185 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
187 --params mode_page=0x1c:0:10:8:0:0:0:0:0:0:0:0:0
188 readonly=<0|1>
191 This sets the read-only flag of a LUN. A read-only LUN will refuse
192 any attempts to write data to it.
193 This parameter only applies to DISK devices.
195 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
197 --params readonly=1
198
201 These parameters are only applicable for luns that are of type
202 "changer" i.e. the media changer device for a DVD Jukebox or a Virtual
203 Tape Library.
204 element_type=<1|2|3|4>
206 This controls which type of element a certain slot in the
207 jukebox/vtl is.
208 Slot types:
210 1 -> Medium Transport (picker arm)
211 2 -> Storage Element
212 3 -> Import/Export Element
213 4 -> Data Transfer device (CD drive, tape drive, MO drive etc)
214 address=<1-65535>
217 This is used to create/operate on a single slot. Address specifies
218 the slot on which to perform the operation.
219 start_address=<1-65535>,quantity=<1--65535>
221 This is used to create/operate on an entire range of slots at once.
222 Start_address specifies the first address to operate on and
223 quantity specifies the number of consequtive slots.
224 sides=<1|2>
226 When creating storage elements, i.e. "element_type=2", this
227 parameter specifies if the media has 1 or two sides to hold data.
228 clear_slot=<1>
230 This option is used to clear a storage element and remove any media
231 that may be present. Once this command completes the storage
232 element will show up as "Empty".
233 barcode=<string>
235 This is used to assign a barcode to an element.
236 media_home=<string>
238 This parameter specifies a directory where all virtual media for
239 the dvd/tape device elements are stored.
240 To assign a media image file to a storage element slot, you assign
242 "barcode" to be the name of the image file in the "media_home"
243 directory.
244 Example: How to create a DVD jukebox with eight disk trays and
246 two empty DVD-R disks.
247 # Create a target
250 tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn.2007-03:virtual-dvd:`hostname`
251 # Create a DVD drive and give it a nice name
253 # The dvd starts out without a backing store file, i.e. no disk loaded
254 tgtadm --op new --mode logicalunit --tid 1 --lun 1 --device-type cd
255 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
256 # We need a backend store file for the media changer
258 if [ ! -f $HOME/smc ]; then
259 dd if=/dev/zero of=$HOME/smc bs=1k count=1
260 fi
261 # Create the SMC device and give it a nice name
263 tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 --backing-store $HOME/smc --device-type changer
264 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
265 # Add a Data Transfer devices (1 drive)
267 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,start_address=1,quantity=1
268 # Specify that the DVD above (LUN 1) is the data transfer device we created
270 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,address=1,tid=1,lun=1
271 # Medium Transport Elements (robot arm / picker)
273 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=1,start_address=16,quantity=1
274 # define path to virtual media
276 VTL=${HOME}/vtl
277 mkdir -p ${VTL}
278 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params media_home=${VTL}
279 # Storage Elements - 8 starting at addr 1024
281 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,start_address=1024,quantity=8
282 # Add ´media´ to slots 1 and 2 and leave the other 6 slots empty
284 # slot 1
285 # Create empty writeable virtual DVD-R media
286 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_001
287 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1024,barcode=DISK_001,sides=1
288 # slot 2
290 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_002
291 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1025,barcode=DISK_002,sides=1
292 # Allow ALL initiators to connect to this target
294 tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL
295 # Show all our good work.
297 tgtadm --lld iscsi --mode target --op show
298
301 In addition to device emulation TGTD also supports utilizing existing
302 SG devices on the host and exporting these through a special
303 passthrough device type.
304 --bstype=sg
306 This specifies that an SG devices is used.
307 --device-type=pt
309 This specifies that passthrough device type is used.
310 --backing-store=</dev/sg4>
312 This specifies which device to export through TGTD.
313 Example:
315 Make /dev/sg4 available to initiators connecting to TGTD.
316 tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4
318
321 Header and data digests can be set on a per target parameter. TGTD
322 supports two modes, None and CRC32C. When the digest is set to None,
323 TDTD will negotiate that digests will not be used, and when CRC32C is
324 set, TGTD will force the connection to use digest.
325 Viewing the current settings
327 This command is used to view the current settings for header/data
328 digest.
329 tgtadm --op show --mode target --tid 1
331 ...
332 HeaderDigest=None
333 DataDigest=None
334 ...
335 Setting digest
338 Set header digest to CRC32C:
339 tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C
340 Set data digest to None:
342 tgtadm --op update --mode target --tid 1 -n DataDigest -v None
343
346 CHAP authentication is supported to require authentication before an
347 initiator is allowed to log in and access devices.
348 CHAP main-phase authentication is set on the target level. To set up
350 CHAP authentication we first need to create an account and its
351 associated password, then we bind the account to one or more targets.
352 Setting CHAP on a target
354 These two commands create a user account and binds it to target 1.
355 tgtadm --lld iscsi --op new --mode account --user ronnie --password password
357 tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie
358 List all accounts
361 This command is used to list all accounts that have been created.
362 tgtadm --lld iscsi --op show --mode account
364 Account list:
365 ronnie
366 Show if a target requires authentication
369 When listing the targets, each target that has authantication enabled
370 will contain a listing of all accoutns bound to that target.
371 tgtadm --lld iscsi --op show --mode target
373 Target 1: iqn.ronnie.test
374 ...
375 Account information:
376 ronnie
377 ...
378
381 iSCSI portals can be viewed, added and removed at runtime.
382 List portals
384 This command is used to list the current iSCSI portals defined on the
385 target:
386 tgtadm --lld iscsi --op show --mode portal
388 Portal: 10.1.1.101:3260,1
389 Portal: 127.0.0.1:3260,1
390 Add portal
393 This command is used to add a portal to the target :
394 tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260
396 Remove portal
399 This command is used to remove a portal from the target :
400 tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260
402
405 iSCSI connections can be viewed and forced closed at runtime.
406 List all active connections for a target
408 This command is used to list the all the active iSCSI connections to
409 the target with connection id, initiator name and ip address for the
410 initiator :
411 tgtadm --lld iscsi --op show --mode conn --tid 1
413 Session: 2
414 Connection: 0
415 Initiator: iqn.2008-11.org.linux-kvm:
416 IP Address: 127.0.0.1
417 Close an existing connection
420 This command is used to close an iSCSI connection. Note that forcibly
421 closing iSCSI connections can lead to data-loss.
422 tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0
424
427 Tgtd LUNs can be in online or offline status. LUNs that are Offline
428 behave slightly different depending on the device type. Offline devices
429 behave as if there is no media available and any operations that access
430 media will fail with an check-condition error.
431 Devices can not be set to Offline mode while there are "PREVENT ALLOW
433 MEDIUM REMOVAL" locks on the device. Similarly media in Online devices
434 can not be software ejected while there are such locks on the device
435 (the ´eject´ command will fail).
436 Show Online/Offline status
438 Finding the Online/Offline status of a LUN is done through the tgtd
439 command. If "Prevent removal" is "Yes" this indicates that an
440 application holds a "prevent media removal" lock on the device.
441 tgtadm --lld iscsi --mode target --op show
443 ...
444 LUN: 2
445 Type: cd/dvd
446 SCSI ID: IET 00010002
447 SCSI SN: beaf12
448 Size: 3432 MB, Block size: 1
449 Online: Yes
450 Removable media: Yes
451 Prevent removal: Yes
452 ...
453 Changing a LUN to Offline
456 A LUN is changed to Offline status using the tgtadm command. When
457 devices are set Offline these devices will behave as if there is no
458 media loaded into the drive.
459 Change a LUN to become offline. (no disk in the drive)
461 tgtadm --tid 1 --lun 2 --op update --mode logicalunit -P Online=No
463
466 iSNS configuration for a target is by using the tgtadm command.
467 iSNSServerIP
469 This specifies the IP address of the iSNS server. TGTD only
470 supprots one iSNS server.
471 Example:
473 tgtadm --op update --mode sys --name iSNSServerIP --value 192.168.11.133
475 iSNS
478 This setting enables(on)/disables(off) iSNS.
479 Example:
481 tgtadm --op update --mode sys --name iSNS --value On
483 iSNSServerPort
486 This setting specifies the port to use for iSNS.
487 Example:
489 tgtadm --op update --mode sys --name iSNSServerPort --value 3205
491 iSNSAccessControl
494 Enable/disable access control for iSNS.
495 Example:
497 tgtadm --op update --mode sys --name iSNSAccessControl --value Off
499
502 tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8).
503 http://stgt.sourceforge.net/
504
506 Report bugs to <stgt@vger.kernel.org>
507[FIXME: source] 05/11/2016 TGTADM(8)