warren/libiscsi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Add iscsi-md5sum

Browse Source 
Add document for utils/iscsi-md5sum.

Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
This commit is contained in:
zhenwei pi
2023-10-25 11:31:55 +08:00
parent d0cc81347f
commit 17fc7159b6
3 changed files with 255 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/Makefile.am
View File

@@ -1,11 +1,12 @@
XSLTPROC = /usr/bin/xsltproc
# Manpages
man1_MANS = iscsi-inq.1 iscsi-ls.1 iscsi-swp.1 iscsi-test-cu.1
man1_MANS = iscsi-inq.1 iscsi-ls.1 iscsi-swp.1 iscsi-md5sum.1 iscsi-test-cu.1
EXTRA_DIST = iscsi-inq.1 iscsi-inq.xml \
iscsi-ls.1 iscsi-ls.xml \
iscsi-swp.1 iscsi-swp.xml \
iscsi-md5sum.1 iscsi-md5sum.xml \
iscsi-test-cu.1 iscsi-test-cu.xml
.xml.1:

101
doc/iscsi-md5sum.1 Normal file
View File

@@ -0,0 +1,101 @@
'\" t
.\" Title: iscsi-md5sum
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 10/25/2023
.\" Manual: iscsi-md5sum: calculate MD5
.\" Source: iscsi-md5sum
.\" Language: English
.\"
.TH "ISCSI\-MD5SUM" "1" "10/25/2023" "iscsi\-md5sum" "iscsi\-md5sum: calculate MD5"
.\" -----------------------------------------------------------------
.\" * 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
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
iscsi-md5sum \- Utility to calculate MD5 value of an iSCSI LUN at range [LBAm, LBAn)
.SH "SYNOPSIS"
.HP \w'\fBiscsi\-md5sum\ [\ OPTIONS\ ]\ <ISCSI\-PORTAL>\fR\ 'u
\fBiscsi\-md5sum [ OPTIONS ] <ISCSI\-PORTAL>\fR
.HP \w'\fBiscsi\-md5sum\fR\ 'u
\fBiscsi\-md5sum\fR [\-i\ \-\-initiator\-name=<IQN>] [\-o\ \-\-offset] [\-l\ \-\-length] [\-d\ \-\-debug] [\-?\ \-\-help] [\-\-usage]
.SH "DESCRIPTION"
.PP
iscsi\-md5sum is a utility to calculate MD5 value of an iSCSI LUN at range [LBAm, LBAn)\&.
.SH "ISCSI PORTAL URL FORMAT"
.PP
iSCSI portal format is \*(Aqiscsi://[<username>[%<password>]@]<host>[:<port>]\*(Aq
.PP
Username and password are only required if the target requires CHAP authentication\&. Optionally you can specify the username and password via the environment variables LIBISCSI_CHAP_USERNAME and LIBISCSI_CHAP_PASSWORD\&.
.PP
Host can be specified either as a hostname, an IPv4 address or an IPv6 address\&. Examples:
.sp
.if n \{\
.RS 4
.\}
.nf
iscsi://192\&.0\&.2\&.1
iscsi://[2001:DB8::1]:3261
iscsi://ronnie%password@iscsi\&.example\&.com
.fi
.if n \{\
.RE
.\}
.PP
Port is the TCP port on the target to connect to\&. Default is 3260\&.
.SH "OPTIONS"
.PP
\-i \-\-initiator\-name=<IQN>
.RS 4
This specifies the initiator\-name that iscsi\-md5sum will use when logging in to the target\&.
.sp
The default name is \*(Aqiqn\&.2007\-10\&.com\&.github:sahlberg:libiscsi:iscsi\-md5sum\*(Aq but you can use this argument to override this\&. This is mainly needed for cases where the target is configured with access\-control to only allow discovery logins from known initiator\-names\&.
.RE
.PP
\-o \-\-offset
.RS 4
Byte offset into the target from which to start calculating\&. The provided value must be aligned to the target sector size\&. The default value is zero\&.
.RE
.PP
\-l \-\-length
.RS 4
The number of bytes to calculate (counting from the starting point)\&. The provided value must be aligned to the target sector size\&. If the specified value extends past the end of the device, iscsi\-md5sum will stop at the device size boundary\&. The default value extends to the end of the device\&.
.RE
.PP
\-d \-\-debug
.RS 4
Print debug information\&.
.RE
.PP
\-? \-\-help
.RS 4
Display basic help text\&.
.RE
.PP
\-\-usage
.RS 4
Display basic usage text\&.
.RE
.SH "AUTHOR"
.PP
zhenwei pi <pizhenwei@bytedance\&.com>
.SH "SEE ALSO"
.PP
iscsi\-inq(1)
\m[blue]\fB\%http://github.com/sahlberg/libiscsi\fR\m[]

152
doc/iscsi-md5sum.xml Normal file
View File

@@ -0,0 +1,152 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<refentry id="iscsi-md5sum.1">
<refmeta>
<refentrytitle>iscsi-md5sum</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">iscsi-md5sum</refmiscinfo>
<refmiscinfo class="manual">iscsi-md5sum: calculate MD5</refmiscinfo>
</refmeta>
<refnamediv>
<refname>iscsi-md5sum</refname>
<refpurpose>Utility to calculate MD5 value of an iSCSI LUN at range [LBAm, LBAn)</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>iscsi-md5sum [ OPTIONS ] &lt;ISCSI-PORTAL&gt;</command>
</cmdsynopsis>
<cmdsynopsis>
<command>iscsi-md5sum</command>
<arg choice="opt">-i --initiator-name=&lt;IQN&gt;</arg>
<arg choice="opt">-o --offset</arg>
<arg choice="opt">-l --length</arg>
<arg choice="opt">-d --debug</arg>
<arg choice="opt">-? --help</arg>
<arg choice="opt">--usage</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
<para>
iscsi-md5sum is a utility to calculate MD5 value of an iSCSI LUN at range [LBAm, LBAn).
</para>
</refsect1>
<refsect1><title>ISCSI PORTAL URL FORMAT</title>
<para>
iSCSI portal format is 'iscsi://[&lt;username&gt;[%&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;]'
</para>
<para>
Username and password are only required if the target requires CHAP
authentication. Optionally you can specify the username and password via
the environment variables LIBISCSI_CHAP_USERNAME and
LIBISCSI_CHAP_PASSWORD.
</para>
<para>
Host can be specified either as a hostname, an IPv4 address or an
IPv6 address.
Examples:
<screen format="linespecific">
iscsi://192.0.2.1
iscsi://[2001:DB8::1]:3261
iscsi://ronnie%password@iscsi.example.com
</screen>
</para>
<para>
Port is the TCP port on the target to connect to. Default is 3260.
</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry><term>-i --initiator-name=&lt;IQN&gt;</term>
<listitem>
<para>
This specifies the initiator-name that iscsi-md5sum will use when
logging in to the target.
</para>
<para>
The default name is
'iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-md5sum' but you can use
this argument to override this. This is mainly needed for cases
where the target is configured with access-control to only
allow discovery logins from known initiator-names.
</para>
</listitem>
</varlistentry>
<varlistentry><term>-o --offset</term>
<listitem>
<para>
Byte offset into the target from which to start calculating.
The provided value must be aligned to the target sector size.
The default value is zero.
</para>
</listitem>
</varlistentry>
<varlistentry><term>-l --length</term>
<listitem>
<para>
The number of bytes to calculate (counting from the starting point).
The provided value must be aligned to the target sector size.
If the specified value extends past the end of the device,
iscsi-md5sum will stop at the device size boundary.
The default value extends to the end of the device.
</para>
</listitem>
</varlistentry>
<varlistentry><term>-d --debug</term>
<listitem>
<para>
Print debug information.
</para>
</listitem>
</varlistentry>
<varlistentry><term>-? --help</term>
<listitem>
<para>
Display basic help text.
</para>
</listitem>
</varlistentry>
<varlistentry><term>--usage</term>
<listitem>
<para>
Display basic usage text.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>AUTHOR</title>
<para>
zhenwei pi &lt;pizhenwei@bytedance.com&gt;
</para>
</refsect1>
<refsect1><title>SEE ALSO</title>
<para>
iscsi-inq(1)
<ulink url="http://github.com/sahlberg/libiscsi"/>
</para>
</refsect1>
</refentry>