[stgt] [PATCH 1/2] Add a section for passthrough devices to the tgtadm manpage with an example
FUJITA Tomonori
fujita.tomonori at lab.ntt.co.jp
Sat Oct 2 13:02:27 CEST 2010
From: Ronnie Sahlberg <ronniesahlberg at gmail.com>
Add a section to list the available --bstype s to the manpage
Signed-off-by: Ronnie Sahlberg <ronniesahlberg at gmail.com>
Signed-off-by: FUJITA Tomonori <fujita.tomonori at lab.ntt.co.jp>
---
doc/htmlpages/tgtadm.8.html | 47 ++++++++++++++++---
doc/manpages/tgtadm.8 | 107 ++++++++++++++++++++++++++++++++++++++-----
doc/tgtadm.8.xml | 55 ++++++++++++++++++++++
3 files changed, 190 insertions(+), 19 deletions(-)
diff --git a/doc/htmlpages/tgtadm.8.html b/doc/htmlpages/tgtadm.8.html
index 18f62f2..f945079 100644
--- a/doc/htmlpages/tgtadm.8.html
+++ b/doc/htmlpages/tgtadm.8.html
@@ -1,13 +1,22 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>tgtadm</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="tgtadm"><a name="tgtadm.8"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>tgtadm — Linux SCSI Target Administration Utility</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">tgtadm [OPTIONS]...</code> [-C --control-port <port>] [-L --lld <driver>] [-o --op <operation>] [-m --mode <mode>] [-t --tid <id>] [-T --targetname <targetname>] [-Y --device-type <type>] [-l --lun <lun>] [-b --backing-store <path>] [-I --initiator-address <address>] [-n --name <parameter>] [-v --value <value>] [-P --params <param=value[,param=v!
alue...]>] [-h --help]</p></div></div><div class="refsect1" title="DESCRIPTION"><a name="id247594"></a><h2>DESCRIPTION</h2><p>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>tgtadm</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="tgtadm"><a name="tgtadm.8"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>tgtadm — Linux SCSI Target Administration Utility</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">tgtadm [OPTIONS]...</code> [-C --control-port <port>] [-L --lld <driver>] [-o --op <operation>] [-m --mode <mode>] [-t --tid <id>] [-T --targetname <targetname>] [-Y --device-type <type>] [-l --lun <lun>] [-b --backing-store <path>] [-E --bstype <type>] [-I --initiator-address <address>] [-n --name <parameter>] [-v --value <value>] [-P --para!
ms <param=value[,param=value...]>] [-h --help]</p></div></div><div class="refsect1" title="DESCRIPTION"><a name="id415940"></a><h2>DESCRIPTION</h2><p>
tgtadm is used to monitor and modify everything about Linux SCSI target
software: targets, volumes, etc.
- </p></div><div class="refsect1" title="OPTIONS"><a name="id247605"></a><h2>OPTIONS</h2><div class="variablelist"><pre class="screen">
+ </p></div><div class="refsect1" title="OPTIONS"><a name="id415951"></a><h2>OPTIONS</h2><div class="variablelist"><pre class="screen">
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
+ </pre><pre class="screen">
+Possible backend types are:
+ rdwr : Use normal file I/O. This is the default for disk devices
+ aio : Use Asynchronous I/O
+ mmap : Use memory mapping for the backend file
+
+ sg : Special backend type for passthrough devices
+ ssc : Special backend type for tape emulation
</pre><dl><dt><span class="term"><code class="option">-C, --control-port <port></code></span></dt><dd><p>
It is possible to run multiple concurrent instances of tgtd
on a host. This argument is used to control which instance
@@ -15,6 +24,9 @@ Possible device-types are:
</p></dd><dt><span class="term"><code class="option">-Y, --device-type <type></code></span></dt><dd><p>
When creating a LUN, this parameter specifies the type of device
to create. Default is disk.
+ </p></dd><dt><span class="term"><code class="option">-E, --bstype <type></code></span></dt><dd><p>
+ When creating a LUN, this parameter specifies the type of backend storage
+ to to use.
</p></dd><dt><span class="term"><code class="option">--lld <driver> --op new --mode target --tid <id> --targetname <name></code></span></dt><dd><p>
Add a new target with <id> and <name>.
</p></dd><dt><span class="term"><code class="option">--lld <driver> --op delete --mode target --tid <id></code></span></dt><dd><p>
@@ -42,7 +54,7 @@ Possible device-types are:
Sets/changes the value of one or more parameters.
</p></dd><dt><span class="term"><code class="option">--help</code></span></dt><dd><p>
Display a list of available options and exits.
- </p></dd></dl></div></div><div class="refsect1" title="LUN PARAMETERS"><a name="id247860"></a><h2>LUN PARAMETERS</h2><p>
+ </p></dd></dl></div></div><div class="refsect1" title="LUN PARAMETERS"><a name="id416196"></a><h2>LUN PARAMETERS</h2><p>
These parameters are only applicable for "--mode logicalunit".
</p><div class="variablelist"><pre class="screen">
Example:
@@ -78,6 +90,9 @@ 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
+ </pre><pre class="screen">
+tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 1 \
+ --params readonly=1
</pre><dl><dt><span class="term"><code class="option">vendor_id=<string></code></span></dt><dd><p>
This parameter sets the Vendor Identification string that a LUN
will report in INQURY data.
@@ -108,7 +123,12 @@ tgtadm --lld iscsi --mode logicalunit --op update --tid 1 --lun 2 \
and the mode page contents. Most devices default to reasonable
default mode pages automatically when the LUN is created, but this
allows special settings.
- </p></dd></dl></div></div><div class="refsect1" title="SMC SPECIFIC LUN PARAMETERS"><a name="id248034"></a><h2>SMC SPECIFIC LUN PARAMETERS</h2><p>
+ </p></dd><dt><span class="term"><code class="option">readonly=<0|1></code></span></dt><dd><p>
+ This sets the read-only flag of a LUN. A read-only LUN will
+ refuse any attempts to write data to it.
+ </p><p>
+ This parameter only applies to DISK devices.
+ </p></dd></dl></div></div><div class="refsect1" title="SMC SPECIFIC LUN PARAMETERS"><a name="id416369"></a><h2>SMC SPECIFIC LUN PARAMETERS</h2><p>
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.
</p><div class="variablelist"><pre class="screen">
@@ -193,7 +213,20 @@ Slot types:
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.
- </p></dd></dl></div></div><div class="refsect1" title="iSNS PARAMETERS"><a name="id248206"></a><h2>iSNS PARAMETERS</h2><p>
+ </p></dd></dl></div></div><div class="refsect1" title="Passthrough devices"><a name="id416529"></a><h2>Passthrough devices</h2><p>
+ In addition to device emulation TGTD also supports utilizing existing SG devices on the host and exporting these through a special passthrough device type.
+ </p><dt><span class="term"><code class="option">--bstype=sg</code></span></dt><dd><p>
+ This specifies that an SG devices is used.
+ </p></dd><dt><span class="term"><code class="option">--device-type=pt</code></span></dt><dd><p>
+ This specifies that passthrough device type is used.
+ </p></dd><dt><span class="term"><code class="option">--backing-store=</dev/sg4></code></span></dt><dd><p>
+ This specifies which device to export through TGTD.
+ </p></dd><pre class="screen">
+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
+ </pre></div><div class="refsect1" title="iSNS PARAMETERS"><a name="id416588"></a><h2>iSNS PARAMETERS</h2><p>
iSNS configuration for a target is by using the tgtadm command.
</p><div class="variablelist"><pre class="screen">
Example:
@@ -220,9 +253,9 @@ tgtadm --op update --mode sys --name iSNSAccessControl --value Off
This setting specifies the port to use for iSNS.
</p></dd><dt><span class="term"><code class="option">iSNSAccessControl</code></span></dt><dd><p>
Enable/disable access control for iSNS.
- </p></dd></dl></div></div><div class="refsect1" title="SEE ALSO"><a name="id248305"></a><h2>SEE ALSO</h2><p>
+ </p></dd></dl></div></div><div class="refsect1" title="SEE ALSO"><a name="id416681"></a><h2>SEE ALSO</h2><p>
tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8).
<a class="ulink" href="http://stgt.sourceforge.net/" target="_top">http://stgt.sourceforge.net/</a>
- </p></div><div class="refsect1" title="REPORTING BUGS"><a name="id248320"></a><h2>REPORTING BUGS</h2><p>
+ </p></div><div class="refsect1" title="REPORTING BUGS"><a name="id416695"></a><h2>REPORTING BUGS</h2><p>
Report bugs to <stgt at vger.kernel.org>
</p></div></div></body></html>
diff --git a/doc/manpages/tgtadm.8 b/doc/manpages/tgtadm.8
index 05485ed..e61b558 100644
--- a/doc/manpages/tgtadm.8
+++ b/doc/manpages/tgtadm.8
@@ -1,13 +1,22 @@
'\" t
.\" Title: tgtadm
-.\" Author:
-.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
-.\" Date: 08/14/2010
-.\" Manual:
-.\" Source:
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\" Date: 10/02/2010
+.\" Manual: [FIXME: manual]
+.\" Source: [FIXME: source]
.\" Language: English
.\"
-.TH "TGTADM" "8" "08/14/2010" "" ""
+.TH "TGTADM" "8" "10/02/2010" "[FIXME: source]" "[FIXME: manual]"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
@@ -22,7 +31,7 @@
tgtadm \- Linux SCSI Target Administration Utility
.SH "SYNOPSIS"
.HP \w'\fBtgtadm\ [OPTIONS]\&.\&.\&.\fR\ 'u
-\fBtgtadm [OPTIONS]\&.\&.\&.\fR [\-C\ \-\-control\-port\ <port>] [\-L\ \-\-lld\ <driver>] [\-o\ \-\-op\ <operation>] [\-m\ \-\-mode\ <mode>] [\-t\ \-\-tid\ <id>] [\-T\ \-\-targetname\ <targetname>] [\-Y\ \-\-device\-type\ <type>] [\-l\ \-\-lun\ <lun>] [\-b\ \-\-backing\-store\ <path>] [\-I\ \-\-initiator\-address\ <address>] [\-n\ \-\-name\ <parameter>] [\-v\ \-\-value\ <value>] [\-P\ \-\-params\ <param=value[,param=value\&.\&.\&.]>] [\-h\ \-\-help]
+\fBtgtadm [OPTIONS]\&.\&.\&.\fR [\-C\ \-\-control\-port\ <port>] [\-L\ \-\-lld\ <driver>] [\-o\ \-\-op\ <operation>] [\-m\ \-\-mode\ <mode>] [\-t\ \-\-tid\ <id>] [\-T\ \-\-targetname\ <targetname>] [\-Y\ \-\-device\-type\ <type>] [\-l\ \-\-lun\ <lun>] [\-b\ \-\-backing\-store\ <path>] [\-E\ \-\-bstype\ <type>] [\-I\ \-\-initiator\-address\ <address>] [\-n\ \-\-name\ <parameter>] [\-v\ \-\-value\ <value>] [\-P\ \-\-params\ <param=value[,param=value\&.\&.\&.]>] [\-h\ \-\-help]
.SH "DESCRIPTION"
.PP
tgtadm is used to monitor and modify everything about Linux SCSI target software: targets, volumes, etc\&.
@@ -48,6 +57,29 @@ Possible device\-types are:
ssc : same as tape
cd : emulate a DVD drive
changer : emulate a media changer device
+ pt : passthrough type to export a /dev/sg device
+
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fB\-E, \-\-bstype <type>\fR
+.RS 4
+When creating a LUN, this parameter specifies the type of backend storage to to use\&.
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Possible backend types are:
+ rdwr : Use normal file I/O\&. This is the default for disk devices
+ aio : Use Asynchronous I/O
+ mmap : Use memory mapping for the backend file
+
+ sg : Special backend type for passthrough devices
+ ssc : Special backend type for tape emulation
.fi
.if n \{\
@@ -86,7 +118,7 @@ Delete specific logical unit with <lun> that the target with <id> has\&.
.PP
\fB\-\-lld <driver> \-\-op bind \-\-mode target \-\-tid <id> \-\-initiator\-address <address>\fR
.RS 4
-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\&.
+Add the address to the access lists of the target with <id>\&. Initiators with the address can access to the target\&. \*(AqALL\*(Aq is a special address to allow all initiators to access to a target\&.
.RE
.PP
\fB\-\-lld <driver> \-\-op unbind \-\-mode target \-\-tid <id> \-\-initiator\-address <address>\fR
@@ -185,21 +217,21 @@ This parameter is used to set specific mode pages for the device and the mode pa
.nf
Examples:
-Create mode page \'2\', subpage 0 and 14 bytes of data\&.
+Create mode page \*(Aq2\*(Aq, subpage 0 and 14 bytes of data\&.
This is Disconnect\-Reconnect mode page\&.
tgtadm \-\-mode logicalunit \-\-op update \-\-tid 1 \-\-lun 2 \e
\-\-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\&.
+Create mode page \*(Aq10\*(Aq, subpage 0 and 10 bytes of data\&.
This is Control Extension mode page\&.
tgtadm \-\-lld iscsi \-\-mode logicalunit \-\-op update \-\-tid 1 \-\-lun 2 \e
\-\-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\&.
+Create mode page \*(Aq0x1c\*(Aq, 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 \e
@@ -209,6 +241,25 @@ tgtadm \-\-lld iscsi \-\-mode logicalunit \-\-op update \-\-tid 1 \-\-lun 2 \e
.if n \{\
.RE
.\}
+.PP
+\fBreadonly=<0|1>\fR
+.RS 4
+This sets the read\-only flag of a LUN\&. A read\-only LUN will refuse any attempts to write data to it\&.
+.sp
+This parameter only applies to DISK devices\&.
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+tgtadm \-\-lld iscsi \-\-mode logicalunit \-\-op update \-\-tid 1 \-\-lun 1 \e
+ \-\-params readonly=1
+
+.fi
+.if n \{\
+.RE
+.\}
.SH "SMC SPECIFIC LUN PARAMETERS"
.PP
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\&.
@@ -302,7 +353,7 @@ tgtadm \-\-lld iscsi \-\-mode logicalunit \-\-op update \-\-tid 1 \-\-lun 2 \-\-
# 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
+# Add \*(Aqmedia\*(Aq 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
@@ -322,6 +373,38 @@ tgtadm \-\-lld iscsi \-\-mode target \-\-op show
.if n \{\
.RE
.\}
+.SH "PASSTHROUGH DEVICES"
+.PP
+In addition to device emulation TGTD also supports utilizing existing SG devices on the host and exporting these through a special passthrough device type\&.
+.PP
+\fB\-\-bstype=sg\fR
+.RS 4
+This specifies that an SG devices is used\&.
+.RE
+.PP
+\fB\-\-device\-type=pt\fR
+.RS 4
+This specifies that passthrough device type is used\&.
+.RE
+.PP
+\fB\-\-backing\-store=</dev/sg4>\fR
+.RS 4
+This specifies which device to export through TGTD\&.
+.RE
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+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
+
+.fi
+.if n \{\
+.RE
+.\}
.SH "ISNS PARAMETERS"
.PP
iSNS configuration for a target is by using the tgtadm command\&.
diff --git a/doc/tgtadm.8.xml b/doc/tgtadm.8.xml
index 92218b7..2209fc7 100644
--- a/doc/tgtadm.8.xml
+++ b/doc/tgtadm.8.xml
@@ -24,6 +24,7 @@
<arg choice="opt">-Y --device-type <type></arg>
<arg choice="opt">-l --lun <lun></arg>
<arg choice="opt">-b --backing-store <path></arg>
+ <arg choice="opt">-E --bstype <type></arg>
<arg choice="opt">-I --initiator-address <address></arg>
<arg choice="opt">-n --name <parameter></arg>
<arg choice="opt">-v --value <value></arg>
@@ -70,6 +71,25 @@ Possible device-types are:
ssc : same as tape
cd : emulate a DVD drive
changer : emulate a media changer device
+ pt : passthrough type to export a /dev/sg device
+ </screen>
+
+ <varlistentry><term><option>-E, --bstype <type></option></term>
+ <listitem>
+ <para>
+ When creating a LUN, this parameter specifies the type of backend storage
+ to to use.
+ </para>
+ </listitem>
+ </varlistentry>
+ <screen format="linespecific">
+Possible backend types are:
+ rdwr : Use normal file I/O. This is the default for disk devices
+ aio : Use Asynchronous I/O
+ mmap : Use memory mapping for the backend file
+
+ sg : Special backend type for passthrough devices
+ ssc : Special backend type for tape emulation
</screen>
<varlistentry><term><option>--lld <driver> --op new --mode target --tid <id> --targetname <name></option></term>
@@ -442,6 +462,41 @@ tgtadm --lld iscsi --mode target --op show
</refsect1>
+ <refsect1><title>Passthrough devices</title>
+ <para>
+ In addition to device emulation TGTD also supports utilizing existing SG devices on the host and exporting these through a special passthrough device type.
+ </para>
+ <varlistentry><term><option>--bstype=sg</option></term>
+ <listitem>
+ <para>
+ This specifies that an SG devices is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><option>--device-type=pt</option></term>
+ <listitem>
+ <para>
+ This specifies that passthrough device type is used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term><option>--backing-store=</dev/sg4></option></term>
+ <listitem>
+ <para>
+ This specifies which device to export through TGTD.
+ </para>
+ </listitem>
+ </varlistentry>
+ <screen format="linespecific">
+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
+ </screen>
+
+ </refsect1>
+
+
<refsect1><title>iSNS PARAMETERS</title>
<para>
iSNS configuration for a target is by using the tgtadm command.
--
1.7.1
--
To unsubscribe from this list: send the line "unsubscribe stgt" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
More information about the stgt
mailing list