tgtadm - Man Page

tgtadm [Options]​.​.​. [-C --control-port <port>] [-L --lld <driver>] [-o --op <operation>] [-m --mode <mode>] [-t --tid <id>] [-T --targetname <targetname>] [-y --blocksize <size>] [-Y --device-type <type>] [-l --lun <lun>] [-b --backing-store <path>] [-f --bsoflags {direct|sync}] [-S --bsopts {backing-store opt string}] [-E --bstype <type>] [-I --initiator-address <address>] [-Q --initiator-name <name>] [-n --name <parameter>] [-v --value <value>] [-P --params <param=value[,param=value​.​.​.]>] [-F --force] [-h --help]

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

-C,  --control-port <port>

It is possible to run multiple concurrent instances of tgtd on a host​. This argument is used to control which instance the tgtadm command will operate on​.

-y,  --blocksize <size>

Block devices are created with a default block size of 512 bytes​. This argument can be used to create block devices with different block sizes​.

Example:

tgtadm --lld iscsi --mode logicalunit --op new \
       --tid <TID> --lun <LUN> \
       -b <backing-file> --blocksize=4096

-Y,  --device-type <type>

When creating a LUN, this parameter specifies the type of device to create​. Default is disk​.

Possible device-types are:
    disk    : emulate a disk device
    tape    : emulate a tape reader
    ssc     : same as tape
    cd      : emulate a DVD drive
    changer : emulate a media changer device
    pt      : passthrough type to export a /dev/sg device

-E,  --bstype <type>

When creating a LUN, this parameter specifies the type of backend storage to to use​.

Possible backend types are:
    rdwr    : Use normal file I/O​. This is the default for disk devices
    aio     : Use Asynchronous I/O
    rbd     : Use Ceph's distributed-storage RADOS Block Device

    sg      : Special backend type for passthrough devices
    ssc     : Special backend type for tape emulation

--lld <driver> --op new --mode target --tid <id> --targetname <name>

Add a new target with <id> and <name>​.

--lld <driver> --op delete --mode target --tid <id>

Delete specific target with <id>​. The target must have no active I_T nexus​.

--lld <driver> --op delete --force --mode target --tid <id>

Delete specific target forcibly with <id>​.

--lld <driver> --op show --mode target

Show all the targets​.

--lld <driver> --op show --mode target --tid <id>

Show target parameters of a target with <id>​.

--lld <driver> --op new --mode logicalunit --tid <id> --lun <lun> --backing-store <path> --bsopts=<backing store options>

Add a new logical unit with <lun> to specific target with <id>​. The logical unit is offered to the initiators​. <path> must be block device files (including LVM and RAID devices) or regular files, or an RBD image or snapshot name for --bstype rbd​. lun0 is reserved for a special device automatically created​.

Example:
If tgt is compiled with the bs_rbd backing store for
Ceph RBD images (see tgtadm --mode system --op show to
verify), set up a target mapping the rbd image named
"rbdimage", and pass options to bs_rbd:

tgtadm --lld iscsi --op new --mode logicalunit --tid 1 \
--lun 1 --bstype=rbd --backing-store=rbdimage \
--bsopts="conf=/etc/ceph/ceph​.conf;id=tgt"

--lld <driver> --op delete --mode logicalunit --tid <id> --lun <lun>

Delete specific logical unit with <lun> that the target with <id> has​.

--lld <driver> --op bind --mode target --tid <id> --initiator-address <address>

Add the address to the access lists of the target with <id>​. Initiators with the address can access to the target​. 'ALL' is a special address to allow all initiators to access to a target​.

--lld <driver> --op bind --mode target --tid <id> --initiator-name <name>

Add the initiator's name to the access lists of the target with <id>​. Initiators with the names can access to the target​.

--lld <driver> --op unbind --mode target --tid <id> --initiator-address <address>

Delete the address from the access lists of the target with <id>​.

--lld <driver> --op unbind --mode target --tid <id> --initiator-name <name>

Delete the initiator's name from the access lists of the target with <id>​.

--lld <driver> --op update --mode target --tid <id> --name=<parameter> --value=<value>

Change the value of <parameter> of the target with <id> to <value>​.

--lld <driver> --op update --mode target --tid <id> --params parameter=value<,​.​.​.>

Sets/changes the value of one or more target parameters​.

--lld <driver> --op update --mode logicalunit --tid <id> --lun <id> --params parameter=value<,​.​.​.>

Sets/changes the value of one or more logical unit parameters​.

--lld <driver> --op start --mode lld

Start the specified lld without restarting the tgtd process​. Can be used to initialize lld driver in case required modules were loaded after tgtd was already executed​.

--help

Display a list of available options and exits​.

These parameters are only applicable for "--mode logicalunit"​.

vendor_id=<string>

This parameter sets the Vendor Identification string that a LUN will report in INQURY data​.

product_id=<string>

This parameter sets the Product Identification string that a LUN will report in INQURY data​.

product_rev=<string>

This parameter sets the Product Revision string that a LUN will report in INQURY data​.

Example:

tgtadm --lld iscsi --mode logicalunit --op update \
       --tid <TID> --lun <LUN> \
       --params vendor_id=TGTD,product_id=VirtualHD,product_rev=0103

removable=<0|1>

This can be used to override/change the default setting for the removable flag​. Disk devices default to non-removable while DVD and TAPE devices default to removable​.

sense_format=<0|1>

This flag controls the format of sense data that the device will return​. 0 = Clasic sense format, 1 = Support descriptor format​.

online=<0|1>

This controls whether a device is online or not​.

Devices default to be online when created but can be brought offline using this parameter​. Behaviour of offline devices depend on device type​. An MMC/DVD device that is offline will report that there is no disk in the unit but the actual MMC/DVD unit itself can still be communicated with​. All other device types will fail all I/O with a sense code of Not Ready​.

Example:

tgtadm --lld iscsi --mode logicalunit --op update \
       --tid 1 --lun 1 \
       --params removable=1,sense_format=1,online=1

mode_page=<byte-string>

This parameter is used to set specific mode pages for the device and the mode page contents​. Most devices default to reasonable default mode pages automatically when the LUN is created, but this allows special settings​.

Examples:

Create mode page '2', subpage 0 and 14 bytes of data​.
This is Disconnect-Reconnect mode page​.

tgtadm --mode logicalunit --op update --tid 1 --lun 2 \
         --params mode_page=2:0:14:0x80:0x80:0:0xa:0:0:0:0:0:0:0:0:0:0


Create mode page '10', subpage 0 and 10 bytes of data​.
This is Control Extension mode page​.

tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
         --params mode_page=10:0:10:2:0:0:0:0:0:0:0:2:0


Create mode page '0x1c', subpage 0 and 10 bytes of data​.
This is Informational Exceptions Control mode page​.

tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
         --params mode_page=0x1c:0:10:8:0:0:0:0:0:0:0:0:0

readonly=<0|1>

This sets the read-only flag of a LUN​. A read-only LUN will refuse any attempts to write data to it​.

This parameter only applies to DISK devices​.

tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
         --params readonly=1

thin_provisioning=<0|1>

This controls the provisioning for the LUN​. A thin-provisioned LUN is represented as a sparse file​. TGTD supports provisioning type 2 for sparse files​. When initiators use the SCSI UNMAP command TGTD will release the affected areas back to the filesystem using FALLOC_FL_PUNCH_HOLE​.

This parameter only applies to DISK devices​.

Thin-provisioning works for LUNs stored on filesystems that support FALLOC_FL_PUNCH_HOLE​.

When using thin-provisioning option with a block device such a SSD or ZVOL, UNMAP SCSI command discards the region from the block device​.

tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
         --params thin_provisioning=1

rotation_rate=<uint32>

This sets the reported rotation rate in RPM of the LUN to the initiator​. Some operating systems assume a SSD type disk when this parameter is zero​.

This parameter only applies to DISK devices​.

tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
         --params rotation_rate=0

These parameters are only applicable for luns that are of type "changer" i​.e​. the media changer device for a DVD Jukebox or a Virtual Tape Library​.

element_type=<1|2|3|4>

This controls which type of element a certain slot in the jukebox/vtl is​.

Slot types:
 1 -> Medium Transport (picker arm)
 2 -> Storage Element
 3 -> Import/Export Element
 4 -> Data Transfer device (CD drive, tape drive, MO drive etc)

address=<1-65535>

This is used to create/operate on a single slot​. Address specifies the slot on which to perform the operation​.

start_address=<1-65535>,quantity=<1--65535>

This is used to create/operate on an entire range of slots at once​. Start_address specifies the first address to operate on and quantity specifies the number of consequtive slots​.

sides=<1|2>

When creating storage elements, i​.e​. "element_type=2", this parameter specifies if the media has 1 or two sides to hold data​.

clear_slot=<1>

This option is used to clear a storage element and remove any media that may be present​. Once this command completes the storage element will show up as "Empty"​.

barcode=<string>

This is used to assign a barcode to an element​. Barcodes are limited to 10 characters in tgtd​.

volume_tag=<string>

This is used to assign a volume tag to SMC storage elements​. If no volume tag is specified tgtd will use fall back to the barcode​. The volume tag can be up to 32 characters​.

media_home=<string>

This parameter specifies a directory where all virtual media for the dvd/tape device elements are stored​.

To assign a media image file to a storage element slot, you assign "barcode" to be the name of the image file in the "media_home" directory​.

Example: How to create a DVD jukebox with eight disk trays and
two empty DVD-R disks​.


# Create a target
tgtadm --lld iscsi --mode target --op new --tid 1 --targetname iqn​.2007-03:virtual-dvd:`hostname`

# Create a DVD drive and give it a nice name
# The dvd starts out without a backing store file, i​.e​. no disk loaded
tgtadm --op new --mode logicalunit --tid 1 --lun 1 --device-type cd
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

# We need a backend store file for the media changer
if [ ! -f $HOME/smc ]; then
	dd if=/dev/zero of=$HOME/smc bs=1k count=1
fi

# Create the SMC device and give it a nice name
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 --backing-store $HOME/smc --device-type changer
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

# Add a Data Transfer devices (1 drive)
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,start_address=1,quantity=1

# Specify that the DVD above (LUN 1) is the data transfer device we created
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=4,address=1,tid=1,lun=1

# Medium Transport Elements (robot arm / picker)
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=1,start_address=16,quantity=1

# define path to virtual media
VTL=${HOME}/vtl
mkdir -p ${VTL}
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params media_home=${VTL}

# Storage Elements - 8 starting at addr 1024
tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 --params element_type=2,start_address=1024,quantity=8

# Add 'media' to slots 1 and 2 and leave the other 6 slots empty
# slot 1
# Create empty writeable virtual DVD-R media
tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_001
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

# slot 2
tgtimg --op new --device-type cd --type dvd+r --file ${VTL}/DISK_002
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

# Allow ALL initiators to connect to this target
tgtadm --lld iscsi --mode target --op bind --tid 1 --initiator-address ALL

# Show all our good work​.
tgtadm --lld iscsi --mode target --op show

In addition to device emulation TGTD also supports utilizing existing SG devices on the host and exporting these through a special passthrough device type​.

--bstype=sg

This specifies that an SG devices is used​.

--device-type=pt

This specifies that passthrough device type is used​.

--backing-store=</dev/sg4>

This specifies which device to export through TGTD​.

--bsoflags={direct|sync}

This argument is used when creating a LUN to specify extra flags to use when opening the backing file​. O_DIRECT is specified by "direct" and O_SYNC by "sync"​.

Example:
Make /dev/sg4 available to initiators connecting to TGTD​.

tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bstype=sg --device-type=pt --backing-store=/dev/sg4

Example:
Open the backing file with O_SYNC​.

tgtadm --lld iscsi --op new --mode logicalunit --tid 1 --lun 1 --bsoflags="sync" --backing-store=/data/100m_image​.raw

Header and data digests can be set on a per target parameter​. TGTD supports two modes, None and CRC32C​. When the digest is set to None, TDTD will negotiate that digests will not be used, and when CRC32C is set, TGTD will force the connection to use digest​.

tgtadm --op show --mode target --tid 1
  ​.​.​.
  HeaderDigest=None
  DataDigest=None
  ​.​.​.

Set header digest to CRC32C:
tgtadm --op update --mode target --tid 1 -n HeaderDigest -v CRC32C

Set data digest to None:
tgtadm --op update --mode target --tid 1 -n DataDigest -v None

CHAP authentication is supported to require authentication before an initiator is allowed to log in and access devices​.

CHAP main-phase authentication is set on the target level​. To set up CHAP authentication we first need to create an account and its associated password, then we bind the account to one or more targets​.

tgtadm --lld iscsi --op new --mode account --user ronnie --password password
tgtadm --lld iscsi --op bind --mode account --tid 1 --user ronnie

tgtadm --lld iscsi --op show --mode account
Account list:
    ronnie

tgtadm --lld iscsi --op show --mode target
Target 1: iqn​.ronnie​.test
​.​.​.
Account information:
    ronnie
​.​.​.

TGTD can send NOP-OUT probes to connected initiators to determine when an initiator is dead and then automatically clear and tear down the TCP connection​. This can either be set as a global default from the tgtd command-line or it can be set for individual targets using the tgtadm command​.

tgtadm --lld iscsi --op show --mode target

Target 1: iqn​.ronnie​.test
    System information:
        Driver: iscsi
        State: ready
        Nop interval: 5
        Nop count: 5
    I_T nexus information:

tgtadm --op update --mode target --tid 1 -n nop_count -v 5
tgtadm --op update --mode target --tid 1 -n nop_interval -v 5

iSCSI portals can be viewed, added and removed at runtime​.

tgtadm --lld iscsi --op show --mode portal
Portal: 10​.1​.1​.101:3260,1
Portal: 127​.0​.0​.1:3260,1

tgtadm --lld iscsi --op new --mode portal --param portal=10​.1​.1​.101:3260

tgtadm --lld iscsi --op delete --mode portal --param portal=10​.1​.1​.101:3260

iSCSI connections can be viewed and forced closed at runtime​.

tgtadm --lld iscsi --op show --mode conn --tid 1
Session: 2
    Connection: 0
        Initiator: iqn​.2008-11​.org​.linux-kvm:
        IP Address: 127​.0​.0​.1

tgtadm --lld iscsi --op delete --mode conn --tid 1 --sid 2 --cid 0

Tgtd LUNs can be in online or offline status​. LUNs that are Offline behave slightly different depending on the device type​. Offline devices behave as if there is no media available and any operations that access media will fail with an check-condition error​.

Devices can not be set to Offline mode while there are "PREVENT ALLOW MEDIUM REMOVAL" locks on the device​. Similarly media in Online devices can not be software ejected while there are such locks on the device (the 'eject' command will fail)​.

tgtadm --lld iscsi --mode target --op show
​.​.​.
        LUN: 2
            Type: cd/dvd
            SCSI ID: IET     00010002
            SCSI SN: beaf12
            Size: 3432 MB, Block size: 1
            Online: Yes
            Removable media: Yes
            Prevent removal: Yes
​.​.​.

tgtadm --tid 1 --lun 2 --op update --mode logicalunit -P Online=No

iSNS configuration for a target is by using the tgtadm command​.

iSNSServerIP

This specifies the IP address of the iSNS server​. TGTD only supprots one iSNS server​.

Example:

tgtadm --op update --mode sys --name iSNSServerIP --value 192​.168​.11​.133

iSNS

This setting enables(on)/disables(off) iSNS​.

Example:

tgtadm --op update --mode sys --name iSNS --value On

iSNSServerPort

This setting specifies the port to use for iSNS​.

Example:

tgtadm --op update --mode sys --name iSNSServerPort --value 3205

iSNSAccessControl

Enable/disable access control for iSNS​.

Example:

tgtadm --op update --mode sys --name iSNSAccessControl --value Off

tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8)​. https://github.com/fujita/tgt

Report bugs to <stgt@vger​.kernel​.org>

ocf_heartbeat_iSCSILogicalUnit(7), targets.conf(5), tgt-admin(8), tgt-setup-lun(8).