Provided by: tgt_1.0.69-1ubuntu1_amd64 bug

NAME

       tgtadm - Linux SCSI Target Administration Utility

SYNOPSIS

       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]

DESCRIPTION

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

OPTIONS

       -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.

LUN PARAMETERS

       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 only works for LUNs stored on filesystems that
           support FALLOC_FL_PUNCH_HOLE.

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

SMC SPECIFIC LUN PARAMETERS

       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

PASSTHROUGH DEVICES

       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 DIGEST AND DATA DIGEST

       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.

   Viewing the current settings
       This command is used to view the current settings for header/data
       digest.

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

   Setting digest
           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

       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.

   Setting CHAP on a target
       These two commands create a user account and binds it to target 1.

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

   List all accounts
       This command is used to list all accounts that have been created.

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

   Show if a target requires authentication
       When listing the targets, each target that has authantication enabled
       will contain a listing of all accoutns bound to that target.

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

NOP-OUT PROBES

       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.

   Check the current NOP-OUT setting
       The tgtadm command is used to view the current setting for if/when to
       send NOP-OUT probes to connected initiators.

       If the target is configured to send NOP-OUT probes this will show up as
       two parameter lines in the target printout. If the target is not
       configured to send NOP-OUT these lines will not be printed at all.

           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:

   Setting NOP-OUT for a target
       The tgtadm command is used to change the NOP-OUT settings.

           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

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

   List portals
       This command is used to list the current iSCSI portals defined on the
       target:

           tgtadm --lld iscsi --op show --mode portal
           Portal: 10.1.1.101:3260,1
           Portal: 127.0.0.1:3260,1

   Add portal
       This command is used to add a portal to the target :

           tgtadm --lld iscsi --op new --mode portal --param portal=10.1.1.101:3260

   Remove portal
       This command is used to remove a portal from the target :

           tgtadm --lld iscsi --op delete --mode portal --param portal=10.1.1.101:3260

ISCSI CONNECTIONS

       iSCSI connections can be viewed and forced closed at runtime.

   List all active connections for a target
       This command is used to list the all the active iSCSI connections to
       the target with connection id, initiator name and ip address for the
       initiator :

           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

   Close an existing connection
       This command is used to close an iSCSI connection. Note that forcibly
       closing iSCSI connections can lead to data-loss.

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

ONLINE/OFFLINE STATUS

       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).

   Show Online/Offline status
       Finding the Online/Offline status of a LUN is done through the tgtd
       command. If "Prevent removal" is "Yes" this indicates that an
       application holds a "prevent media removal" lock on the device.

           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
           ...

   Changing a LUN to Offline
       A LUN is changed to Offline status using the tgtadm command. When
       devices are set Offline these devices will behave as if there is no
       media loaded into the drive.

       Change a LUN to become offline. (no disk in the drive)

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

ISNS PARAMETERS

       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

SEE ALSO

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

REPORTING BUGS

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

[FIXME: source]                   01/25/2017                         TGTADM(8)