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 [-n --name <parameter>] [-v --value <value>]
16 [-P --params <param=value[,param=value...]>]
17 [-h --help]
18
20 tgtadm is used to monitor and modify everything about Linux SCSI target
21 software: targets, volumes, etc.
22
24 -C, --control-port <port>
25 It is possible to run multiple concurrent instances of tgtd on a
26 host. This argument is used to control which instance the tgtadm
27 command will operate on.
28 -Y, --device-type <type>
30 When creating a LUN, this parameter specifies the type of device to
31 create. Default is disk.
32 Possible device-types are:
34 disk : emulate a disk device
35 tape : emulate a tape reader
36 ssc : same as tape
37 cd : emulate a DVD drive
38 changer : emulate a media changer device
39 pt : passthrough type to export a /dev/sg device
40 -E, --bstype <type>
43 When creating a LUN, this parameter specifies the type of backend
44 storage to to use.
45 Possible backend types are:
47 rdwr : Use normal file I/O. This is the default for disk devices
48 aio : Use Asynchronous I/O
49 mmap : Use memory mapping for the backend file
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 show --mode target
63 Show all the targets.
64 --lld <driver> --op show --mode target --tid <id>
66 Show target parameters of a target with <id>.
67 --lld <driver> --op new --mode logicalunit --tid <id> --lun <lun>
69 --backing-store <path>
70 Add a new logical unit with <lun> to specific target with <id>. The
71 logical unit is offered to the initiators. <path> must be block
72 device files (including LVM and RAID devices) or regular files.
73 lun0 is reserved for a special device automatically created.
74 --lld <driver> --op delete --mode logicalunit --tid <id> --lun <lun>
76 Delete specific logical unit with <lun> that the target with <id>
77 has.
78 --lld <driver> --op bind --mode target --tid <id> --initiator-address
80 <address>
81 Add the address to the access lists of the target with <id>.
82 Initiators with the address can access to the target. 'ALL' is a
83 special address to allow all initiators to access to a target.
84 --lld <driver> --op unbind --mode target --tid <id> --initiator-address
86 <address>
87 Delete the address from the access lists of the target with <id>.
88 --lld <driver> --op update --mode target --tid <id> --name=<parameter>
90 --value=<value>
91 Change the value of <parameter> of the target with <id> to <value>.
92 --lld <driver> --op update --mode target --tid <id> --params
94 parameter=value<,...>
95 Sets/changes the value of one or more parameters.
96 --help
98 Display a list of available options and exits.
99
101 These parameters are only applicable for "--mode logicalunit".
102 vendor_id=<string>
104 This parameter sets the Vendor Identification string that a LUN
105 will report in INQURY data.
106 product_id=<string>
108 This parameter sets the Product Identification string that a LUN
109 will report in INQURY data.
110 product_rev=<string>
112 This parameter sets the Product Revision string that a LUN will
113 report in INQURY data.
114 Example:
116 tgtadm --lld iscsi --mode logicalunit --op update \
118 --tid <TID> --lun <LUN> \
119 --params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103
120 removable=<0|1>
123 This can be used to override/change the default setting for the
124 removable flag. Disk devices default to non-removable while DVD and
125 TAPE devices default to removable.
126 sense_format=<0|1>
128 This flag controls the format of sense data that the device will
129 return. 0 = Clasic sense format, 1 = Support descriptor format.
130 online=<0|1>
132 This controls whether a device is online or not.
133 Devices default to be online when created but can be brought
135 offline using this parameter. Behaviour of offline devices depend
136 on device type. An MMC/DVD device that is offline will report that
137 there is no disk in the unit but the actual MMC/DVD unit itself can
138 still be communicated with. All other device types will fail all
139 I/O with a sense code of Not Ready.
140 Example:
142 tgtadm --lld iscsi --mode logicalunit --op update \
144 --tid 1 --lun 1 \
145 --params removable=1,sense_format=1,online=1
146 mode_page=<byte-string>
149 This parameter is used to set specific mode pages for the device
150 and the mode page contents. Most devices default to reasonable
151 default mode pages automatically when the LUN is created, but this
152 allows special settings.
153 Examples:
155 Create mode page '2', subpage 0 and 14 bytes of data.
157 This is Disconnect-Reconnect mode page.
158 tgtadm --mode logicalunit --op update --tid 1 --lun 2 \
160 --params mode_page=2:0:14:0x80:0x80:0:0xa:0:0:0:0:0:0:0:0:0:0
161 Create mode page '10', subpage 0 and 10 bytes of data.
164 This is Control Extension mode page.
165 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
167 --params mode_page=10:0:10:2:0:0:0:0:0:0:0:2:0
168 Create mode page '0x1c', subpage 0 and 10 bytes of data.
171 This is Informational Exceptions Control mode page.
172 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
174 --params mode_page=0x1c:0:10:8:0:0:0:0:0:0:0:0:0
175 readonly=<0|1>
178 This sets the read-only flag of a LUN. A read-only LUN will refuse
179 any attempts to write data to it.
180 This parameter only applies to DISK devices.
182 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
184 --params readonly=1
185
188 These parameters are only applicable for luns that are of type
189 "changer" i.e. the media changer device for a DVD Jukebox or a Virtual
190 Tape Library.
191 element_type=<1|2|3|4>
193 This controls which type of element a certain slot in the
194 jukebox/vtl is.
195 Slot types:
197 1 -> Medium Transport (picker arm)
198 2 -> Storage Element
199 3 -> Import/Export Element
200 4 -> Data Transfer device (CD drive, tape drive, MO drive etc)
201 address=<1-65535>
204 This is used to create/operate on a single slot. Address specifies
205 the slot on which to perform the operation.
206 start_address=<1-65535>,quantity=<1--65535>
208 This is used to create/operate on an entire range of slots at once.
209 Start_address specifies the first address to operate on and
210 quantity specifies the number of consequtive slots.
211 sides=<1|2>
213 When creating storage elements, i.e. "element_type=2", this
214 parameter specifies if the media has 1 or two sides to hold data.
215 barcode=<string>
217 This is used to assign a barcode to an element.
218 media_home=<string>
220 This parameter specifies a directory where all virtual media for
221 the dvd/tape device elements are stored.
222 To assign a media image file to a storage element slot, you assign
224 "barcode" to be the name of the image file in the "media_home"
225 directory.
226 Example: How to create a DVD jukebox with eight disk trays and
228 two empty DVD-R disks.
229 # Create a target
232 tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn.2007-03:virtual-dvd:`hostname`
233 # Create a DVD drive and give it a nice name
235 # The dvd starts out without a backing store file, i.e. no disk loaded
236 tgtadm --op new --mode logicalunit --tid 1 --lun 1 --device-type cd
237 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
238 # We need a backend store file for the media changer
240 if [ ! -f $HOME/smc ]; then
241 dd if=/dev/zero of=$HOME/smc bs=1k count=1
242 fi
243 # Create the SMC device and give it a nice name
245 tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 --backing-store $HOME/smc --device-type changer
246 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
247 # Add a Data Transfer devices (1 drive)
249 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,start_address=1,quantity=1
250 # Specify that the DVD above (LUN 1) is the data transfer device we created
252 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,address=1,tid=1,lun=1
253 # Medium Transport Elements (robot arm / picker)
255 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=1,start_address=16,quantity=1
256 # define path to virtual media
258 VTL=${HOME}/vtl
259 mkdir -p ${VTL}
260 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params media_home=${VTL}
261 # Storage Elements - 8 starting at addr 1024
263 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,start_address=1024,quantity=8
264 # Add 'media' to slots 1 and 2 and leave the other 6 slots empty
266 # slot 1
267 # Create empty writeable virtual DVD-R media
268 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_001
269 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1024,barcode=DISK_001,sides=1
270 # slot 2
272 tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_002
273 tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,address=1025,barcode=DISK_002,sides=1
274 # Allow ALL initiators to connect to this target
276 tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL
277 # Show all our good work.
279 tgtadm --lld iscsi --mode target --op show
280
283 In addition to device emulation TGTD also supports utilizing existing
284 SG devices on the host and exporting these through a special
285 passthrough device type.
286 --bstype=sg
288 This specifies that an SG devices is used.
289 --device-type=pt
291 This specifies that passthrough device type is used.
292 --backing-store=</dev/sg4>
294 This specifies which device to export through TGTD.
295 Example:
297 Make /dev/sg4 available to initiators connecting to TGTD.
298 tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4
300
303 Header and data digests can be set on a per target parameter. TGTD
304 supports two modes, None and CRC32C. When the digest is set to None,
305 TDTD will negotiate that digests will not be used, and when CRC32C is
306 set, TGTD will force the connection to use digest.
307 Viewing the current settings
309 This command is used to view the current settings for header/data
310 digest.
311 tgtadm --op show --mode target --tid 1
313 ...
314 HeaderDigest=None
315 DataDigest=None
316 ...
317 Setting digest
320 Set header digest to CRC32C:
321 tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C
322 Set data digest to None:
324 tgtadm --op update --mode target --tid 1 -n DataDigest -v None
325
328 CHAP authentication is supported to require authentication before an
329 initiator is allowed to log in and access devices. TGTD supports
330 setting CHAP for normal log in sessions only, not for discovery
331 sessions. Discovery sessions are always possible without
332 authentication.
333 CHAP authentication is set on the target level. To set up CHAP
335 authentication we first need to create an account and its associated
336 password, then we bind the account to one or more targets.
337 Setting CHAP on a target
339 These two commands create a user account and binds it to target 1.
340 tgtadm --lld iscsi --op new --mode account --user ronnie --password password
342 tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie
343 List all accounts
346 This command is used to list all accounts that have been created.
347 tgtadm --lld iscsi --op show --mode account
349 Account list:
350 ronnie
351 Show if a target requires authentication
354 When listing the targets, each target that has authantication enabled
355 will contain a listing of all accoutns bound to that target.
356 tgtadm --lld iscsi --op show --mode target
358 Target 1: iqn.ronnie.test
359 ...
360 Account information:
361 ronnie
362 ...
363
366 iSCSI portals can be viewed, added and removed at runtime.
367 List portals
369 This command is used to list the current iSCSI portals defined on the
370 target:
371 tgtadm --lld iscsi --op show --mode portal
373 Portal: 10.1.1.101:3260,1
374 Portal: 127.0.0.1:3260,1
375 Add portal
378 This command is used to add a portal to the target :
379 tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260
381 Remove portal
384 This command is used to remove a portal from the target :
385 tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260
387
390 iSCSI connections can be viewed and forced closed at runtime.
391 List all active connections for a target
393 This command is used to list the all the active iSCSI connections to
394 the target with connection id, initiator name and ip address for the
395 initiator :
396 tgtadm --lld iscsi --op show --mode conn --tid 1
398 Session: 2
399 Connection: 0
400 Initiator: iqn.2008-11.org.linux-kvm:
401 IP Address: 127.0.0.1
402 Close an existing connection
405 This command is used to close an iSCSI connection. Note that forcibly
406 closing iSCSI connections can lead to data-loss.
407 tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0
409
412 iSNS configuration for a target is by using the tgtadm command.
413 iSNSServerIP
415 This specifies the IP address of the iSNS server. TGTD only
416 supprots one iSNS server.
417 Example:
419 tgtadm --op update --mode sys --name iSNSServerIP --value 192.168.11.133
421 iSNS
424 This setting enables(on)/disables(off) iSNS.
425 Example:
427 tgtadm --op update --mode sys --name iSNS --value On
429 iSNSServerPort
432 This setting specifies the port to use for iSNS.
433 Example:
435 tgtadm --op update --mode sys --name iSNSServerPort --value 3205
437 iSNSAccessControl
440 Enable/disable access control for iSNS.
441 Example:
443 tgtadm --op update --mode sys --name iSNSAccessControl --value Off
445
448 tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8).
449 http://stgt.sourceforge.net/
450
452 Report bugs to <stgt@vger.kernel.org>
453[FIXME: source] 05/08/2011 TGTADM(8)