From 17fc7159b6f73480f105132fa8fcf0a8562dc27f Mon Sep 17 00:00:00 2001 From: zhenwei pi Date: Wed, 25 Oct 2023 11:31:55 +0800 Subject: [PATCH] doc: Add iscsi-md5sum Add document for utils/iscsi-md5sum. Signed-off-by: zhenwei pi --- doc/Makefile.am | 3 +- doc/iscsi-md5sum.1 | 101 ++++++++++++++++++++++++++++ doc/iscsi-md5sum.xml | 152 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 255 insertions(+), 1 deletion(-) create mode 100644 doc/iscsi-md5sum.1 create mode 100644 doc/iscsi-md5sum.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 293c644c..20e8b66d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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: diff --git a/doc/iscsi-md5sum.1 b/doc/iscsi-md5sum.1 new file mode 100644 index 00000000..1fa71cc6 --- /dev/null +++ b/doc/iscsi-md5sum.1 @@ -0,0 +1,101 @@ +'\" t +.\" Title: iscsi-md5sum +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" 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\ ]\ \fR\ 'u +\fBiscsi\-md5sum [ OPTIONS ] \fR +.HP \w'\fBiscsi\-md5sum\fR\ 'u +\fBiscsi\-md5sum\fR [\-i\ \-\-initiator\-name=] [\-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://[[%]@][:]\*(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= +.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 +.SH "SEE ALSO" +.PP +iscsi\-inq(1) +\m[blue]\fB\%http://github.com/sahlberg/libiscsi\fR\m[] diff --git a/doc/iscsi-md5sum.xml b/doc/iscsi-md5sum.xml new file mode 100644 index 00000000..6f690227 --- /dev/null +++ b/doc/iscsi-md5sum.xml @@ -0,0 +1,152 @@ + + + + + iscsi-md5sum + 1 + iscsi-md5sum + iscsi-md5sum: calculate MD5 + + + + + iscsi-md5sum + Utility to calculate MD5 value of an iSCSI LUN at range [LBAm, LBAn) + + + + + iscsi-md5sum [ OPTIONS ] <ISCSI-PORTAL> + + + + iscsi-md5sum + -i --initiator-name=<IQN> + -o --offset + -l --length + -d --debug + -? --help + --usage + + + + + DESCRIPTION + + iscsi-md5sum is a utility to calculate MD5 value of an iSCSI LUN at range [LBAm, LBAn). + + + + ISCSI PORTAL URL FORMAT + + iSCSI portal format is 'iscsi://[<username>[%<password>]@]<host>[:<port>]' + + + + 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. + + + + Host can be specified either as a hostname, an IPv4 address or an + IPv6 address. + + Examples: + + iscsi://192.0.2.1 + iscsi://[2001:DB8::1]:3261 + iscsi://ronnie%password@iscsi.example.com + + + + + Port is the TCP port on the target to connect to. Default is 3260. + + + + + OPTIONS + + + + -i --initiator-name=<IQN> + + + This specifies the initiator-name that iscsi-md5sum will use when + logging in to the target. + + + 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. + + + + + -o --offset + + + 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. + + + + + -l --length + + + 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. + + + + + -d --debug + + + Print debug information. + + + + + -? --help + + + Display basic help text. + + + + + --usage + + + Display basic usage text. + + + + + + + + AUTHOR + + zhenwei pi <pizhenwei@bytedance.com> + + + + SEE ALSO + + iscsi-inq(1) + + + + +