List, Tomo Please find attached a patch to add an initial manpage for tgtimg. It also updates the other manpages to link to this from their SEE ALSO section, to make visibility of this manpages existence higher. This manpage is better than no manpage but can definitely be improved. Perhaps someone using VTL can enhance it and add some better examples ? Maybe it could be enhanced to show a small example on how to create a set of tape images and then how to set up a VTL with the tgtadm commands ? regards ronnie sahlberg
Attachment:
0001-Add-an-initial-manpage-for-the-tgtimg-utility-that-i.patch.gz
Description: GNU Zip compressed data
From f77d8fed63013ebd2142129e49661c2a34ce0534 Mon Sep 17 00:00:00 2001 From: Ronnie Sahlberg <ronniesahlberg@xxxxxxxxx> Date: Thu, 4 Mar 2010 17:53:22 +1100 Subject: [PATCH] Add an initial manpage for the tgtimg utility that is used to initialize ior view tape image files. Signed-off-by: Ronnie Sahlberg <ronniesahlberg@xxxxxxxxx> --- doc/Makefile | 13 +++- doc/htmlpages/tgtadm.8.html | 6 +- doc/htmlpages/tgtd.8.html | 4 +- doc/htmlpages/tgtimg.8.html | 49 ++++++++++++++ doc/manpages/tgtadm.8 | 6 +- doc/manpages/tgtd.8 | 6 +- doc/manpages/tgtimg.8 | 93 +++++++++++++++++++++++++++ doc/tgtadm.8.xml | 2 +- doc/tgtd.8.xml | 2 +- doc/tgtimg.8.xml | 149 +++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 314 insertions(+), 16 deletions(-) create mode 100644 doc/htmlpages/tgtimg.8.html create mode 100644 doc/manpages/tgtimg.8 create mode 100644 doc/tgtimg.8.xml diff --git a/doc/Makefile b/doc/Makefile index 4650040..518caaf 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,15 +1,16 @@ mandir ?= $(PREFIX)/share/man docdir ?= $(PREFIX)/share/doc/tgt -MANPAGES = manpages/tgtadm.8 manpages/tgt-admin.8 \ +MANPAGES = manpages/tgtadm.8 manpages/tgt-admin.8 manpages/tgtimg.8 \ manpages/tgt-setup-lun.8 manpages/tgtd.8 DOCS = README.fcoe README.ibmvstgt README.iscsi README.iser \ README.lu_configuration README.mmc tmf.txt XSLTPROC = /usr/bin/xsltproc -XMLMAN = manpages/tgtd.8 manpages/tgtadm.8 -XMLHTML = htmlpages/tgtd.8.html htmlpages/tgtadm.8.html +XMLMAN = manpages/tgtd.8 manpages/tgtadm.8 manpages/tgtimg.8 +XMLHTML = htmlpages/tgtd.8.html htmlpages/tgtadm.8.html \ + htmlpages/tgtimg.8.html .PHONY:all all: @@ -36,6 +37,12 @@ manpages/tgtadm.8: tgtadm.8.xml htmlpages/tgtadm.8.html: tgtadm.8.xml -test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< +manpages/tgtimg.8: tgtimg.8.xml + -test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +htmlpages/tgtimg.8.html: tgtimg.8.xml + -test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< + xmlman: $(XMLMAN) xmlhtml: $(XMLHTML) diff --git a/doc/htmlpages/tgtadm.8.html b/doc/htmlpages/tgtadm.8.html index cc4f712..9b9c73c 100644 --- a/doc/htmlpages/tgtadm.8.html +++ b/doc/htmlpages/tgtadm.8.html @@ -1,7 +1,7 @@ <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.73.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><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"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">tgtadm [--control-port NNNN] --lld [driver] --op [operation] --mode [mode] [OPTION]...</code> </p></div></div><div class="refsect1" lang="en"><a name="id2475961"></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" lang="en"><a name="id2475971"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term"><code class="option">--control-port NNNN</code></span></dt><dd><p> + </p></div><div class="refsect1" lang="en"><a name="id2475972"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term"><code class="option">--control-port NNNN</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 the tgtadm command will operate on. @@ -33,8 +33,8 @@ </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" lang="en"><a name="id2476171"></a><h2>SEE ALSO</h2><p> - tgtd(8), tgt-admin(8), tgt-setup-lun(8). + 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" lang="en"><a name="id2476185"></a><h2>REPORTING BUGS</h2><p> + </p></div><div class="refsect1" lang="en"><a name="id2476186"></a><h2>REPORTING BUGS</h2><p> Report bugs to <stgt@xxxxxxxxxxxxxxx> </p></div></div></body></html> diff --git a/doc/htmlpages/tgtd.8.html b/doc/htmlpages/tgtd.8.html index 175e1b2..16b6c55 100644 --- a/doc/htmlpages/tgtd.8.html +++ b/doc/htmlpages/tgtd.8.html @@ -29,9 +29,9 @@ tgtd --iscsi portal=192.0.2.1:3260 </pre><p> </p></div></div><div class="refsect1" lang="en"><a name="id2476091"></a><h2>SEE ALSO</h2><p> - tgtadm(8), tgt-admin(8), tgt-setup-lun(8). + tgtadm(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" lang="en"><a name="id2476105"></a><h2>COPYRIGHT/LICENSE</h2><div class="literallayout"><p><br> + </p></div><div class="refsect1" lang="en"><a name="id2476106"></a><h2>COPYRIGHT/LICENSE</h2><div class="literallayout"><p><br> This program is free software; you can redistribute it and/or modify<br> it under the terms of the GNU General Public License as published by<br> the Free Software Foundation; either version 2 of the License, or (at<br> diff --git a/doc/htmlpages/tgtimg.8.html b/doc/htmlpages/tgtimg.8.html new file mode 100644 index 0000000..3777994 --- /dev/null +++ b/doc/htmlpages/tgtimg.8.html @@ -0,0 +1,49 @@ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>tgtimg</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="tgtimg.8"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>tgtimg — Linux SCSI Target Framework Image File Utility</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">tgtimg --op new --device-type tape </code> <br><code class="command">--barcode <code> --size <size> --type <type> --file <path></code> </p></div><div class="cmdsynopsis"><p><code class="command">tgtimg --op show --device-type tape --file=<path></code> </p></div><div class="cmdsynopsis"><p><code class="command">tgtimg --help</code> </p></div></div><div class="refsect1" lang="en"><a name="id2475961"></a><h2>DESCRIPTION</h2><p> + tgtimg is a utility to create and manage the image files used by the + stgt tape emulation. + </p><p> + This command is used to initialize tape image files with the additional + metadata, such as barcode, list of blocks, total size, etc that + the tape emulation of TGTD needs. + </p><p> + You must use this command to initialize a file so that TGTD will\ + recognize it as a tape image. + </p></div><div class="refsect1" lang="en"><a name="id2475984"></a><h2>OPTIONS</h2><div class="variablelist"><dl><dt><span class="term"><code class="option">-h, --help</code></span></dt><dd><p> + Show a help screen and exit. + </p></dd><dt><span class="term"><code class="option">-o, --op {new|show}</code></span></dt><dd><p> + Operation. Is either new to create a new image file or show to + show the content of an existing image file. + </p></dd><dt><span class="term"><code class="option">-Y, --device-type <type></code></span></dt><dd><p> + This specifies the type of image file. The only valid type is tape. + </p></dd><dt><span class="term"><code class="option">-b, --barcode <barcode></code></span></dt><dd><p> + When creating a new image, this argument specifies the barcode + to use with this image file. Backup application software often + uses barcodes to identify specific tapes. When emulating a VTL, + make sure that all tape images use unique barcodes. + </p></dd><dt><span class="term"><code class="option">-s, --size <size></code></span></dt><dd><p> + When creating a new image, this specifies the size in megabytes + for the virtual tape image. + </p></dd><dt><span class="term"><code class="option">-t, --type {data|clean|worm}</code></span></dt><dd><p> + When creating a new image, this specifies the type of media to + emulate, normal data, cleaning image, or worm. + </p><p> + Data is a normal tape to read/write to and probably what you + want to use. + </p></dd><dt><span class="term"><code class="option">-f, --file <path></code></span></dt><dd><p> + The filename of the image file. + </p></dd></dl></div></div><div class="refsect1" lang="en"><a name="id2476108"></a><h2>EXAMPLES</h2><p> + To create a new image + </p><pre class="screen"> + tgtimg --op new --device-type tape --barcode 12345 --size 100 --type data --file /data/tape001.img + </pre><p> + </p><p> + To view the content of an existing image + </p><pre class="screen"> + tgtimg --op show --device-type tape --file /data/tape001.img + </pre><p> + </p></div><div class="refsect1" lang="en"><a name="id2476136"></a><h2>SEE ALSO</h2><p> + tgtd(8), tgtadm(8), tgt-admin(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" lang="en"><a name="id2476151"></a><h2>REPORTING BUGS</h2><p> + Report bugs to <stgt@xxxxxxxxxxxxxxx> + </p></div></div></body></html> diff --git a/doc/manpages/tgtadm.8 b/doc/manpages/tgtadm.8 index 37f64c7..92fef89 100644 --- a/doc/manpages/tgtadm.8 +++ b/doc/manpages/tgtadm.8 @@ -1,11 +1,11 @@ .\" Title: tgtadm .\" Author: .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/> -.\" Date: 02/26/2010 +.\" Date: 03/04/2010 .\" Manual: .\" Source: .\" -.TH "TGTADM" "8" "02/26/2010" "" "" +.TH "TGTADM" "8" "03/04/2010" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -81,7 +81,7 @@ display a list of available options and exits\. .RE .SH "SEE ALSO" .PP -tgtd(8), tgt\-admin(8), tgt\-setup\-lun(8)\. +tgtd(8), tgt\-admin(8), tgtimg(8), tgt\-setup\-lun(8)\. \fI\%http://stgt.sourceforge.net/\fR .SH "REPORTING BUGS" .PP diff --git a/doc/manpages/tgtd.8 b/doc/manpages/tgtd.8 index 1bded50..6db034f 100644 --- a/doc/manpages/tgtd.8 +++ b/doc/manpages/tgtd.8 @@ -1,11 +1,11 @@ .\" Title: tgtd .\" Author: .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/> -.\" Date: 02/26/2010 +.\" Date: 03/04/2010 .\" Manual: .\" Source: .\" -.TH "TGTD" "8" "02/26/2010" "" "" +.TH "TGTD" "8" "03/04/2010" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -66,7 +66,7 @@ Example: to bind tgtd to a specific address and port .sp .SH "SEE ALSO" .PP -tgtadm(8), tgt\-admin(8), tgt\-setup\-lun(8)\. +tgtadm(8), tgt\-admin(8), tgtimg(8), tgt\-setup\-lun(8)\. \fI\%http://stgt.sourceforge.net/\fR .SH "COPYRIGHT/LICENSE" .sp diff --git a/doc/manpages/tgtimg.8 b/doc/manpages/tgtimg.8 new file mode 100644 index 0000000..ce1d026 --- /dev/null +++ b/doc/manpages/tgtimg.8 @@ -0,0 +1,93 @@ +.\" Title: tgtimg +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/> +.\" Date: 03/04/2010 +.\" Manual: +.\" Source: +.\" +.TH "TGTIMG" "8" "03/04/2010" "" "" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +tgtimg - Linux SCSI Target Framework Image File Utility +.SH "SYNOPSIS" +.HP 35 +\fBtgtimg \-\-op new \-\-device\-type tape \fR\fB\-\-barcode <code> \-\-size <size> \-\-type <type> \-\-file <path>\fR +.HP 50 +\fBtgtimg \-\-op show \-\-device\-type tape \-\-file=<path>\fR +.HP 14 +\fBtgtimg \-\-help\fR +.SH "DESCRIPTION" +.PP +tgtimg is a utility to create and manage the image files used by the stgt tape emulation\. +.PP +This command is used to initialize tape image files with the additional metadata, such as barcode, list of blocks, total size, etc that the tape emulation of TGTD needs\. +.PP +You must use this command to initialize a file so that TGTD will\e recognize it as a tape image\. +.SH "OPTIONS" +.PP +\fB\-h, \-\-help\fR +.RS 4 +Show a help screen and exit\. +.RE +.PP +\fB\-o, \-\-op {new|show}\fR +.RS 4 +Operation\. Is either new to create a new image file or show to show the content of an existing image file\. +.RE +.PP +\fB\-Y, \-\-device\-type <type>\fR +.RS 4 +This specifies the type of image file\. The only valid type is tape\. +.RE +.PP +\fB\-b, \-\-barcode <barcode>\fR +.RS 4 +When creating a new image, this argument specifies the barcode to use with this image file\. Backup application software often uses barcodes to identify specific tapes\. When emulating a VTL, make sure that all tape images use unique barcodes\. +.RE +.PP +\fB\-s, \-\-size <size>\fR +.RS 4 +When creating a new image, this specifies the size in megabytes for the virtual tape image\. +.RE +.PP +\fB\-t, \-\-type {data|clean|worm}\fR +.RS 4 +When creating a new image, this specifies the type of media to emulate, normal data, cleaning image, or worm\. +.sp +Data is a normal tape to read/write to and probably what you want to use\. +.RE +.PP +\fB\-f, \-\-file <path>\fR +.RS 4 +The filename of the image file\. +.RE +.SH "EXAMPLES" +.PP +To create a new image +.sp +.RS 4 +.nf + tgtimg \-\-op new \-\-device\-type tape \-\-barcode 12345 \-\-size 100 \-\-type data \-\-file /data/tape001\.img + +.fi +.RE +.PP +To view the content of an existing image +.sp +.RS 4 +.nf + tgtimg \-\-op show \-\-device\-type tape \-\-file /data/tape001\.img + +.fi +.RE +.sp +.SH "SEE ALSO" +.PP +tgtd(8), tgtadm(8), tgt\-admin(8), tgt\-setup\-lun(8)\. +\fI\%http://stgt.sourceforge.net/\fR +.SH "REPORTING BUGS" +.PP +Report bugs to <stgt@vger\.kernel\.org> diff --git a/doc/tgtadm.8.xml b/doc/tgtadm.8.xml index 381555f..22d96f1 100644 --- a/doc/tgtadm.8.xml +++ b/doc/tgtadm.8.xml @@ -139,7 +139,7 @@ <refsect1><title>SEE ALSO</title> <para> - tgtd(8), tgt-admin(8), tgt-setup-lun(8). + tgtd(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8). <ulink url="http://stgt.sourceforge.net/"/> </para> </refsect1> diff --git a/doc/tgtd.8.xml b/doc/tgtd.8.xml index ace5f1f..33ef7f9 100644 --- a/doc/tgtd.8.xml +++ b/doc/tgtd.8.xml @@ -113,7 +113,7 @@ <refsect1><title>SEE ALSO</title> <para> - tgtadm(8), tgt-admin(8), tgt-setup-lun(8). + tgtadm(8), tgt-admin(8), tgtimg(8), tgt-setup-lun(8). <ulink url="http://stgt.sourceforge.net/"/> </para> </refsect1> diff --git a/doc/tgtimg.8.xml b/doc/tgtimg.8.xml new file mode 100644 index 0000000..f12b145 --- /dev/null +++ b/doc/tgtimg.8.xml @@ -0,0 +1,149 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<refentry id="tgtimg.8"> + +<refmeta> + <refentrytitle>tgtimg</refentrytitle> + <manvolnum>8</manvolnum> +</refmeta> + + +<refnamediv> + <refname>tgtimg</refname> + <refpurpose>Linux SCSI Target Framework Image File Utility</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>tgtimg --op new --device-type tape </command> + <command>--barcode <code> --size <size> --type <type> --file <path></command> + </cmdsynopsis> + <cmdsynopsis> + <command>tgtimg --op show --device-type tape --file=<path></command> + </cmdsynopsis> + <cmdsynopsis> + <command>tgtimg --help</command> + </cmdsynopsis> + +</refsynopsisdiv> + + <refsect1><title>DESCRIPTION</title> + <para> + tgtimg is a utility to create and manage the image files used by the + stgt tape emulation. + </para> + <para> + This command is used to initialize tape image files with the additional + metadata, such as barcode, list of blocks, total size, etc that + the tape emulation of TGTD needs. + </para> + <para> + You must use this command to initialize a file so that TGTD will\ + recognize it as a tape image. + </para> + </refsect1> + + + <refsect1> + <title>OPTIONS</title> + + <variablelist> + <varlistentry><term><option>-h, --help</option></term> + <listitem> + <para> + Show a help screen and exit. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><option>-o, --op {new|show}</option></term> + <listitem> + <para> + Operation. Is either new to create a new image file or show to + show the content of an existing image file. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><option>-Y, --device-type <type></option></term> + <listitem> + <para> + This specifies the type of image file. The only valid type is tape. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><option>-b, --barcode <barcode></option></term> + <listitem> + <para> + When creating a new image, this argument specifies the barcode + to use with this image file. Backup application software often + uses barcodes to identify specific tapes. When emulating a VTL, + make sure that all tape images use unique barcodes. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><option>-s, --size <size></option></term> + <listitem> + <para> + When creating a new image, this specifies the size in megabytes + for the virtual tape image. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><option>-t, --type {data|clean|worm}</option></term> + <listitem> + <para> + When creating a new image, this specifies the type of media to + emulate, normal data, cleaning image, or worm. + </para> + <para> + Data is a normal tape to read/write to and probably what you + want to use. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><option>-f, --file <path></option></term> + <listitem> + <para> + The filename of the image file. + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1><title>EXAMPLES</title> + <para> + To create a new image + <screen format="linespecific"> + tgtimg --op new --device-type tape --barcode 12345 --size 100 --type data --file /data/tape001.img + </screen> + </para> + + <para> + To view the content of an existing image + <screen format="linespecific"> + tgtimg --op show --device-type tape --file /data/tape001.img + </screen> + </para> + </refsect1> + + + <refsect1><title>SEE ALSO</title> + <para> + tgtd(8), tgtadm(8), tgt-admin(8), tgt-setup-lun(8). + <ulink url="http://stgt.sourceforge.net/"/> + </para> + </refsect1> + + <refsect1><title>REPORTING BUGS</title> + <para> + Report bugs to <stgt@xxxxxxxxxxxxxxx> + </para> + </refsect1> + +</refentry> -- 1.5.4.3
