From 9a2d2f2cf391c707a98204d488c3cb3e58cdab00 Mon Sep 17 00:00:00 2001 From: Lee Duncan Date: Fri, 25 Mar 2022 07:54:18 -0700 Subject: Make DB and ISCSIHOME directories configurable. This commit adds two new top-level build options: one for the "home" directory for open-iscsi called "HOMEDIR", and one for the "database" directory, called "DBROOT". One can now override the defaults of "/etc/iscsi" for either or both of these directories on the make command line. The README and man pages are updated with details about these new options. Some Makefile cleanup/repair was done as well. Installation of the initiatorname.iscsi file, was moved out of the top-level Makefile into the etc subdirectory, and installation of man ages moved from the top-level Makefile to the doc subdirectory. Also, this fixes some issues from commit fd14dd8316b1 ("Clean p Makefile build system."), which incorrectly changed the DESTDIR ariable in the Makefiles. This current commit also fixes the top-level variable names for moving DBROOT and HOMEDIR. --- doc/.gitignore | 3 + doc/Makefile | 55 +++ doc/iscsi-gen-initiatorname.8 | 36 -- doc/iscsi-gen-initiatorname.8.template | 36 ++ doc/iscsiadm.8 | 702 -------------------------------- doc/iscsiadm.8.template | 718 +++++++++++++++++++++++++++++++++ doc/iscsid.8 | 84 ---- doc/iscsid.8.template | 84 ++++ 8 files changed, 896 insertions(+), 822 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/Makefile delete mode 100644 doc/iscsi-gen-initiatorname.8 create mode 100644 doc/iscsi-gen-initiatorname.8.template delete mode 100644 doc/iscsiadm.8 create mode 100644 doc/iscsiadm.8.template delete mode 100644 doc/iscsid.8 create mode 100644 doc/iscsid.8.template (limited to 'doc') diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..2f32a57 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,3 @@ +iscsi-gen-initiatorname.8 +iscsiadm.8 +iscsid.8 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..7d39dad --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,55 @@ +# This Makefile will work only with GNU make. +# +# Make file for the doc sub-directory +# + +ifeq ($(TOPDIR),) + TOPDIR = .. +endif + +SED = /usr/bin/sed +INSTALL = install + +DESTDIR ?= +etcdir = /etc +DBROOT ?= $(etcdir)/iscsi +HOMEDIR ?= $(etcdir)/iscsi + +prefix ?= /usr +mandir ?= $(prefix)/share/man + +MAN8DIR = $(DESTDIR)$(mandir)/man8 + +MANPAGES_SOURCES = iscsi_discovery.8 \ + iscsi_fw_login.8 \ + iscsi-iname.8 \ + iscsistart.8 +MANPAGES_SOURCES_ISCSIUIO = $(TOPDIR)/iscsiuio/docs/iscsiuio.8 +MANPAGES_TEMPLATES = iscsid.8.template \ + iscsiadm.8.template \ + iscsi-gen-initiatorname.8 +MANPAGES_GENERATED = $(MANPAGES_TEMPLATES:.template=) +MANPAGES_DEST = $(addprefix $(MAN8DIR)/,$(MANPAGES_GENERATED)) \ + $(addprefix $(MAN8DIR)/,$(MANPAGES_SOURCES)) +MANPAGES_DEST_ISCSIUIO = $(addprefix $(MAN8DIR)/,$(notdir $(MANPAGES_SOURCES_ISCSIUIO))) + +all: $(MANPAGES_GENERATED) + +install: install_doc + +install_doc: $(MAN8DIR) $(MANPAGES_DEST) $(MANPAGES_DEST_ISCSIUIO) + +$(MANPAGES_GENERATED): %.8: %.8.template + $(SED) -e 's:@HOMEDIR@:$(HOMEDIR):' -e 's:@DBROOT@:$(DBROOT):' $? > $@ + +$(MANPAGES_DEST): $(MAN8DIR)/%: % + $(INSTALL) -m 644 $? $@ + +$(MANPAGES_DEST_ISCSIUIO): $(MAN8DIR)/%: $(TOPDIR)/iscsiuio/docs/% + $(INSTALL) -m 644 $? $@ + +$(MAN8DIR): + [ -d $@ ] || $(INSTALL) -d $@ + +clean: + $(RM) $(MANPAGES_GENERATED) diff --git a/doc/iscsi-gen-initiatorname.8 b/doc/iscsi-gen-initiatorname.8 deleted file mode 100644 index 5ad0a1e..0000000 --- a/doc/iscsi-gen-initiatorname.8 +++ /dev/null @@ -1,36 +0,0 @@ -.TH ISCSI_GEN_INITIATORNAME 8 "Dec 2021" "" "Linux Administrator's Manual" -.SH NAME -iscsi-gen-initiatorname \- smart iSCSI initiator name generation tool -.SH SYNOPSIS -.BI iscsi-gen-initiatorname -[OPTIONS] -.SH "DESCRIPTION" -.B iscsi-gen-initiatorname -generates a unique iSCSI node name on every invocation. If -iBFT is in use, the iBFT-registered initiator name will be used. -.P -If there is an existing initiator name, it will not be overwritten -unless the \fB-f\fP option is supplied. -.SH OPTIONS -.TP -.BI [-h] -Display a help message and exit. -.TP -.BI [-f] -Force overwrite of existing initiator name, if present. -.TP -.BI [-p] \fIIQN-PREFIX\fP -Use \fIIQN-PREFIX\fP as the prefix to the IQN generated, -instead of the default of \fBiqn.1996-04.de.suse:01\fP. -.SH FILES -.TP -/etc/iscsi/initiatorname.iscsi -The file containing the initiator name. Do not edit manually. -.SH "SEE ALSO" -.BR iscsi-iname (8) -.SH AUTHORS -Open-iSCSI project -.br -Hannes Reinecke -.br -Lee Duncan diff --git a/doc/iscsi-gen-initiatorname.8.template b/doc/iscsi-gen-initiatorname.8.template new file mode 100644 index 0000000..e10a4ac --- /dev/null +++ b/doc/iscsi-gen-initiatorname.8.template @@ -0,0 +1,36 @@ +.TH ISCSI_GEN_INITIATORNAME 8 "Dec 2021" "" "Linux Administrator's Manual" +.SH NAME +iscsi-gen-initiatorname \- smart iSCSI initiator name generation tool +.SH SYNOPSIS +.BI iscsi-gen-initiatorname +[OPTIONS] +.SH "DESCRIPTION" +.B iscsi-gen-initiatorname +generates a unique iSCSI node name on every invocation. If +iBFT is in use, the iBFT-registered initiator name will be used. +.P +If there is an existing initiator name, it will not be overwritten +unless the \fB-f\fP option is supplied. +.SH OPTIONS +.TP +.BI [-h] +Display a help message and exit. +.TP +.BI [-f] +Force overwrite of existing initiator name, if present. +.TP +.BI [-p] \fIIQN-PREFIX\fP +Use \fIIQN-PREFIX\fP as the prefix to the IQN generated, +instead of the default of \fBiqn.1996-04.de.suse:01\fP. +.SH FILES +.TP +@HOMEDIR@/initiatorname.iscsi +The file containing the initiator name. Do not edit manually. +.SH "SEE ALSO" +.BR iscsi-iname (8) +.SH AUTHORS +Open-iSCSI project +.br +Hannes Reinecke +.br +Lee Duncan diff --git a/doc/iscsiadm.8 b/doc/iscsiadm.8 deleted file mode 100644 index 599a8fd..0000000 --- a/doc/iscsiadm.8 +++ /dev/null @@ -1,702 +0,0 @@ -.TH ISCSIADM 8 "Mar 2021" "" "Linux Administrator's Manual" -.SH NAME -iscsiadm \- open-iscsi administration utility -.SH SYNOPSIS -.B iscsiadm -.B \-m discoverydb -.RB [ \-hV ] -.RB [ \-d -.IR debug_level ] -.RB [ \-P -.IR printlevel ] -.RB [ \-I -.I iface -.BI \-t\ type\ \-p\ ip:port -.RB [ \-lD ] -] | [ -.RB [ \-p -.I ip:port -.B \-t -.IR type ] -.RB [ \-o -.IR operation ] -.RB [ \-n -.IR name ] -.RB [ \-v -.IR value ] -.RB [ \-lD ] -] -.PP -.B iscsiadm -.B \-m discovery -.RB [ \-hV ] -.RB [ \-d -.IR debug_level ] -.RB [ \-P -.IR printlevel ] -.RB [ \-I -.IR iface ] -.RB [ \-t -.IR type ] -.RB [ \-p -.IR ip:port ] -.RB [ \-l ] -.PP -.B iscsiadm -.B \-m node -.RB [ \-hV ] -.RB [ \-d -.IR debug_level ] -.RB [ \-P -.IR printlevel ] -.RB [ \-L -.IR all,manual,automatic,onboot ] -.RB [ \-W ] -.RB [ \-U -.IR all,manual,automatic,onboot ] -.RB [ \-S ] -[ -.RB [ \-T -.IB targetname\ \-p\ ip:port\ \-I -.IR iface ] -.RB [ \-l | \-u | \-R | \-s ] -] -[ -.RB [ \-o -.IR operation ] -.RB [ \-n -.IR name ] -.RB [ \-v -.IR value ] -.RB [ \-p -.IR ip:port ] -] -.PP -.B iscsiadm -.B \-m session -.RB [ \-hV ] -.RB [ \-d -.IR debug_level ] -.RB [ \-P -.IR printlevel ] -.RB [ \-r -.IR sessionid | sysfsdir -.RB [ \-R ] -.RB [ \-u | \-s | \-o -.IR new ] -] -.PP -.B iscsiadm -.B \-m iface -.RB [ \-hV ] -.RB [ \-d -.IR debug_level ] -.RB [ \-P -.IR printlevel ] -.RB [ \-I -.IR ifacename\ | -.B \-H -.IR hostno|MAC ] -[ -.RB [ \-o -.IR operation ] -.RB [ \-n -.IR name ] -.RB [ \-v -.IR value ] -] -[ -.BI \-C\ ping -.RB [ \-a -.IR ip ] -.RB [ \-b -.IR packetsize ] -.RB [ \-c -.IR count ] -.RB [ \-i -.IR interval ] -] -.PP -.B iscsiadm -.B \-m fw -.RB [ \-d -.IR debug_level ] -.RB [ \-l ] -.RB [ \-W ] -.RB [ \-n -.IR name ] -.RB [ \-v -.IR value ] -.PP -.B iscsiadm -.B \-m host -.RB [ \-P -.IR printlevel ] -.RB [ \-H -.IR hostno|MAC ] -[ -.RB [ \-C -.I chap -.RB [ \-x -.IR chap_tbl_idx ] -] | -.RB [ \-C -.I flashnode -.RB [ \-A -.IR portal_type ] -.RB [ \-x -.IR flashnode_idx ] -] | -.RB [ \-C -.IR stats ] -] -[ -.RB [ \-o -.IR operation ] -.RB [ \-n -.IR name ] -.RB [ \-v -.IR value ] -] -.PP -.B iscsiadm -.B \-k priority -.SH DESCRIPTION -The iscsiadm utility is a command-line tool allowing discovery and login -to iSCSI targets, as well as access and management of the open-iscsi -database. -.PP -Open-iscsi does not use the term \fInode\fR as defined by the iSCSI RFC, -where a node is a single iSCSI initiator or target. Open-iscsi uses the -term \fInode\fR to refer to a portal on a target. -.PP -For \fIsession\fR mode, a session id (\fIsid\fR) is used. The \fIsid\fR of a session can be -found by running \fIiscsiadm \-m session \-P 1\fR. The session id and sysfs -path are not currently persistent and is partially determined by when the -session is setup. -.PP -Note that many of the \fInode\fR and \fIdiscovery\fR operations require that the iSCSI -daemon (iscsid) be running. -.SH OPTIONS -.TP -\fB\-a\fR, \fB\-\-ip=\fIipaddr\fP -\fIipaddr\fR can be IPv4 or IPv6. -.IP -This option is only valid for \fIping\fR submode. -.TP -\fB\-A\fR, \fB\-\-portal_type=\fI[ipv4|ipv6]\fR -Specify the portal type for the new flash node entry to be created. -.IP -This option is only valid for \fIflashnode\fR submode of \fIhost\fR mode and only with \fInew\fR operation. -.TP -\fB\-b\fR, \fB\-\-packetsize=\fIpacketsize\fP -Specify the ping \fIpacketsize\fR. -.IP -This option is only valid for \fIping\fR submode. -.TP -\fB\-c\fR, \fB\-\-count=\fIcount\fP -\fIcount\fR specifies the number of ping iterations. -.IP -This option is only valid for \fIping\fR submode. -.TP -\fB\-C\fR, \fB\-\-submode=\fIop\fP -Specify the submode for mode. \fIop\fR must be name of submode. -.IP -Currently iscsiadm supports \fIping\fR as a submode for \fIiface\fR. For example: -.IP -iscsiadm \-m iface \-I ifacename \-C ping \-a ipaddr \-b packetsize \-c count \-i interval -.IP -For \fIhost\fR, it supports \fIchap\fR, \fIflashnode\fR and \fIstats\fR as submodes. For example: -.IP -iscsiadm \-m host \-H hostno \-C chap \-x chap_tbl_idx \-o operation -.IP -iscsiadm \-m host \-H hostno \-C flashnode \-x flashnode_idx \-o operation -.IP -iscsiadm \-m host \-H hostno \-C stats -.TP -\fB\-d\fR, \fB\-\-debug=\fIdebug_level\fP -print debugging information. Valid values for \fIdebug_level\fR are 0 to 8. -.TP -\fB\-h\fR, \fB\-\-help\fR -display help text and exit -.TP -\fB\-H\fR, \fB\-\-host=\fI[hostno|MAC]\fR -The \fIhost\fR argument specifies the SCSI host to use for the operation. It can be -the scsi host number assigned to the host by the kernel's scsi layer, or the -MAC address of a scsi host. -.TP -\fB\-i\fR, \fB\-\-interval=\fIinterval\fP -\fIinterval\fP specifies the delay between two ping iterations. -.IP -This option is only valid for \fIping\fR submode. -.TP -\fB\-I\fR, \fB\-\-interface=\fI[iface]\fR -The \fIinterface\fR argument specifies the iSCSI interface to use for the operation. -iSCSI interfaces (\fIiface\fR) are defined in /etc/iscsi/ifaces. For hardware -iSCSI (e.g. qla4xxx) the \fIiface\fR configuration must have the hardware address -(\fIiface.hwaddress\fR = port's MAC address) -and the driver/transport_name (\fIiface.transport_name\fR). The \fIiface\fR's name is -then the filename of the iface configuration. For software iSCSI, the iface configuration -must have either the hardware address (\fIiface.hwaddress\fR), or the network -layer's interface name (\fIiface.net_ifacename\fR), and it must have the -driver/transport_name. -.IP -The available drivers/iscsi_transports are \fItcp\fR (software iSCSI over TCP/IP), -\fIiser\fR (software iSCSI over InfiniBand), -\fIqla4xxx\fR (Qlogic 4XXXX and 82XXX HBAs), -\fIcxgb3i\fR and \fIcxgb4i\fR (Chelsio T3 and T4 adapters), -\fIbnx2i\fR (QLogic Netextreme II adapters), -\fIbe2iscsi\fR (Emulex 10G adapter), -\fIqedi\fR (QLogic QEDI 25/40/100Gb adapter), and -\fIocs\fR (Emulex One Connect storage). -Some of these are considered experimental, as they are not fully tested. -.IP -The \fIhwaddress\fR is the MAC address or for software iSCSI it may be the special -value \fIdefault\fR which directs the initiator to not bind the session to a -specific hardware resource and instead allow the network or InfiniBand layer -to decide what to do. There is no need to create an iface configuration with the default -behavior. If you do not specify an \fIiface\fR, then the default behavior is used. -.IP -As mentioned above there is a special iface name \fIdefault\fR. There are -others which do not bind the session to a specific card, but instead bind -the session to the transport: -\fIiser\fR, -\fIcxgb3i\fR, -\fIcxgb4i\fR, and -\fIbnx2i\fR. -.IP -In \fIdiscovery\fR mode multiple interfaces can be specified by passing in -multiple \fI\-I/\-\-interface\fR instances. For example: -.IP -\fBsh#\fR iscsiadm \-m discoverydb \-t st \-p ip:port \-I iface0 \-I iface2 \-\-discover -.IP -Will direct iscsiadm to setup the node db to create records which will create -sessions through the two interfaces passed in. -.IP -In \fInode\fR mode, only a single interface is supported in each call to iscsiadm. -.IP -This option is valid for \fIdiscovery\fR, \fInode\fR and \fIiface\fR modes. -.TP -\fB\-k\fR, \fB\-\-killiscsid=\fI[priority]\fR -Currently \fIpriority\fR must be zero. This will immediately stop all iscsid -operations and shutdown iscsid. It does not logout any sessions. Running -this command is the same as doing \fIkillall iscsid\fR. Neither should -normally be used, because if iscsid is doing error recovery or if there -is an error while iscsid is not running, the system may not be able to recover. -This command and iscsid's SIGTERM handling are experimental. -.TP -\fB\-D\fR, \fB\-\-discover\fR -Discover targets using the discovery record with the \fIrecid\fR matching -the the discovery type and portal passed in. If there is no matching record, -it will be created using the iscsid.conf discovery settings. -This must be passed in to \fIdiscoverydb\fR mode to instruct iscsiadm to perform -discovery. -.IP -This option is only valid for \fISendTargets\fR discovery mode. -.TP -\fB\-l\fR, \fB\-\-login\fR -For \fInode\fR and \fIfw\fR modes, login to a specified record. For \fIdiscovery\fR mode, -login to all discovered targets. -.IP -This option is only valid for \fIdiscovery\fR, \fInode\fR, and \fIfw\fR modes. -For \fIfw\fR mode only, \fIname\fR and \fIvalue\fR pairs can optionally be passed in, -so that those values get used for the sessions created. In this case, no \fIop\fR -is needed, since \fIupdate\fR is assumed. -.TP -\fB\-L\fR, \fB\-\-loginall=\fI[all|manual|automatic|onboot]\fR -For \fInode\fR mode, login to all sessions with the node or conn startup values passed -in or all running session, except ones marked \fIonboot\fR, if \fIall\fR is passed in. -.IP -This option is only valid for \fInode\fR mode (it is valid but not functional -for \fIsession\fR mode). -.TP -\fB\-W\fR, \fB\-\-\-no_wait\fR -In \fInode\fR, \fIdiscovery\fR, or \fIfw\fR (firmware) mode, -do not wait for a response from the target(s). -This means that success will be returned if the command is able to -send the login requests, whether or not they succeed. In this case, it will -be up to the caller to poll for success (i.e. session creation). -.TP -\fB\-m\fR, \fB\-\-mode \fIop\fR -specify the mode. \fIop\fR -must be one of \fIdiscovery\fR, \fIdiscoverydb\fR, \fInode\fR, \fIfw\fR, -\fIhost\fR, \fIiface\fR or \fIsession\fR. -.IP -If no other options are specified: for \fIdiscovery\fR, \fIdiscoverydb\fR and -\fInode\fR mode, all of their respective records are displayed; for \fIsession\fR mode, -all active sessions and connections are displayed; for \fIfw\fR mode, all boot -firmware values are displayed; for \fIhost\fR mode, all iSCSI hosts are displayed; -and for \fIiface\fR mode, all interfaces setup in /etc/iscsi/ifaces are displayed. -.TP -\fB\-n\fR, \fB\-\-name=\fIname\fR -In \fInode\fR mode, specify a field \fIname\fR in a record. In \fIflashnode\fR submode -of \fIhost\fR mode, specify name of the flash node parameter. -.IP -For use with the \fIupdate\fR operator. -.TP -\fB\-o\fR, \fB\-\-op=\fIop\fR -Specifies a database operator \fIop\fR. \fIop\fR must be one of -\fInew\fR, \fIdelete\fR, \fIupdate\fR, \fIshow\fR or \fInonpersistent\fR. -.IP -For \fIiface\fR mode, \fIapply\fR and \fIapplyall\fR are also applicable. -.IP -For \fIflashnode\fR submode of \fIhost\fR mode, \fIlogin\fR and \fIlogout\fR are also applicable. -.IP -This option is valid for all modes except \fIfw\fR. Delete should not be used -on a running session. If it is iscsiadm will stop the session and then delete the -record. -.IP -An \fIop\fR of \fInew\fR creates a new database record for a given object. In \fInode\fR mode, the -\fIrecid\fR is the target name and portal (IP:port). In \fIiface\fR mode, the \fIrecid\fR -is the iface name. In \fIdiscovery\fR mode, the \fIrecid\fR is the portal and -discovery type. -.IP -In \fIsession\fR mode, the \fInew\fR operation logs in a new session using -the same node database and iface information as the specified session. -.IP -In \fIdiscovery\fR mode, if the \fIrecid\fR and \fInew\fR operation is passed in, -but the \fI\-\-discover\fR argument is not passed in, then iscsiadm will only create a -discovery record (it will not perform discovery). If the \fI\-\-discover\fR -argument is passed in with the portal and discovery type, then iscsiadm -will create the discovery record if needed, and it will create records -for portals returned by the target that do not yet have a node DB record. -.IP -Setting \fIop\fR to \fIdelete\fR deletes the specified \fIrecid\fR. In \fIdiscovery\fR mode, if -iscsiadm is performing discovery, it will delete records for portals that -are no longer returned. -.IP -Setting \fIop\fR to \fIupdate\fR will update the \fIrecid\fR with \fIname\fR to the specified -\fIvalue\fR. In discovery mode, if iscsiadm is performing discovery the -\fIrecid\fR, \fIname\fR and \fIvalue\fR arguments are not needed. The -update operation will operate on the portals returned by the target, -and will update the node records with information from the configuration file and -command line. -.IP -The \fIop\fR value of \fIshow\fR is the default behaviour for \fInode\fR, -\fIdiscovery\fR and \fIiface\fR mode. It is -also used when there are no commands passed into \fIsession\fR mode and a -running \fIsid\fR is passed in. -If \fIname\fR and \fIvalue\fR are passed in, they are currently ignored in \fIshow\fR mode. -.IP -An \fIop\fR value of \fInonpersistent\fR instructs iscsiadm to not manipulate the node DB. -.IP -An \fIop\fR value of \fIapply\fR will cause the network settings to take effect on the specified iface. -.IP -An \fIop\fR value of \fIapplyall\fR will cause the network settings to take effect on all the -ifaces whose MAC address or host number matches that of the specific host. -.IP -An \fIop\fR value of \fIlogin\fR will log into the specified flash node entry. -.IP -An \fIop\fR value of \fIlogout\fR does the logout from the given flash node entry. -.TP -\fB\-p\fR, \fB\-\-portal=\fIip[:port]\fR -Use target portal with IP address \fIip\fR and port \fIport\fR. If \fIport\fI is not passed -in the default value of 3260 is used. -.IP -IPv6 addresses can be specified as \fI[ddd.ddd.ddd.ddd]:port\fI or \fIddd.ddd.ddd.ddd\fR. -.IP -Hostnames can also be used for the \fIip\fI argument. -.IP -This option is only valid for \fIdiscovery\fR, or for \fInode\fR operations with -the \fInew\fR operator. -.IP -This should be used along with \fI\-\-target\fR in \fInode\fR mode, to specify what -the open-iscsi documents refer to as a node or node record. Note: open-iscsi's -use of the word node, does not match the iSCSI RFC's iSCSI Node term. -.TP -\fB\-P\fR, \fB\-\-print=\fIprintlevel\fR -If in \fInode\fR mode print nodes in tree format. If in \fIsession\fR mode print -sessions in tree format. If in \fIdiscovery\fR mode print the nodes in -tree format. -.TP -\fB\-T\fR, \fB\-\-targetname=\fItargetname\fR -Use target \fItargetname\fR. -.IP -This should be used along with \fI\-\-portal\fR in \fInode\fR mode, to specify what -the open-iscsi documents refer to as a node or node record. Note: open-iscsi's -use of the word node, does not match the iSCSI RFC's iSCSI Node term. -.TP -\fB\-r\fR, \fB\-\-sid=\fIsid | sysfsdir\fR -Use session ID \fIsid\fR. The session ID of a session can be found from running -iscsiadm in session mode with the \fI\-\-info\fR argument. -.IP -Instead of a session ID, a sysfs path containing the session can be used. -For example using one of the following: -/sys/devices/platform/hostH/sessionS/targetH:B:I/H:B:I:L, -/sys/devices/platform/hostH/sessionS/targetH:B:I, or -/sys/devices/platform/hostH/sessionS, for the \fIsysfsdir\fR argument would -result in the session with session ID \fIS\fR to be used. -.IP -\fIsid | sysfsdir\fR is only required for \fIsession\fR mode. -.TP -\fB\-R\fR, \fB\-\-rescan\fR -In \fIsession\fR mode, if \fIsid\fR is also passed in, rescan the session. -If no \fIsid\fR has been passed in rescan all running sessions. -.IP -In \fInode\fR mode, rescan a session running through the target, portal, iface -tuple passed in. -.TP -\fB\-s\fR, \fB\-\-stats\fR -Display session statistics. -This option when used with \fIhost\fR mode, displays host statistics. -.TP -\fB\-S\fR, \fB\-\-show\fR -When displaying records, do not hide masked values, such as the CHAP -secret (password). -.IP -This option is only valid for \fInode\fR and \fIsession\fR mode. -.TP -\fB\-t\fR, \fB\-\-type=\fItype\fR -\fItype\fR must be \fIsendtargets\fR (or abbreviated as \fIst\fR), -\fIslp\fR, \fIisns\fR or \fIfw\fR. Currently only \fIsendtargets\fR, \fIfw\fR, and -\fIiSNS\fR are supported, see the \fBDISCOVERY TYPES\fR section. -.IP -This option is only valid for \fIdiscovery\fR mode. -.TP -\fB\-u\fR, \fB\-\-logout\fR -Logout for the specified record. -.IP -This option is only valid for \fInode\fR and \fIsession\fR mode. -.TP -\fB\-U\fR, \fB\-\-logoutall=\fI[all,manual,automatic|onboot]\fR -Logout of all sessions with the node or conn startup values passed in or all -running sessions, except ones marked \fIonboot\fR, if \fIall\fR is passed in. -.IP -This option is only valid for \fInode\fR mode (it is valid but not functional -for \fIsession\fR mode). -.TP -\fB\-v\fR, \fB\-\-value=\fIvalue\fR -Specify a \fIvalue\fR for use with the \fIupdate\fR operator, or for firmware login mode. -.IP -This option is only valid for \fInode\fR mode and \fIflashnode\fR submode of \fIhost\fR mode. -.TP -\fB\-V\fR, \fB\-\-version\fR -Display version and exit. -.TP -\fB\-x\fR, \fB\-\-index=\fIindex\fR -Specify the \fIindex\fR of the entity to operate on. -.IP -This option is only valid for \fIchap\fR and \fIflashnode\fR submodes of \fIhost\fR mode. -.SH DISCOVERY TYPES -iSCSI defines 3 discovery types: \fISendTargets\fR, \fISLP\fR, and \fIiSNS\fR. -.PP -A special discovery type called -.I fw -(for firmware) is also supported, for discovering firmware interfaces, -and populating the interface database in the process. -.TP -.B -SendTargets -A native iSCSI protocol which allows each iSCSI -target to send a list of available targets to the initiator. -.TP -.B -SLP -Optionally an iSCSI target can use the Service Location Protocol (SLP) -to announce the available targets. The initiator can either implement -SLP queries directly or can use a separate tool to acquire the -information about available targets. -.TP -.B -iSNS -iSNS (Internet Storage Name Service) records information about storage -volumes within a larger network. To utilize iSNS, pass the address and -optionally the port of the iSNS server to do discovery to. -.TP -.B -fw -Firmware mode. -Several NICs and systems contain a mini iSCSI initiator which can be used -for boot. To get the values used for boot the \fIfw\fR option can be used. -Doing \fIfw\fR discovery does not store persistent records in the node or -discovery DB, because the values are stored in the system's or NIC's -resource. -.IP -Performing \fIfw\fR discovery will print the portals, like with other discovery -methods. To see other settings like CHAP values and initiator settings, -like you would in \fInode\fR mode, run \fIiscsiadm \-m fw\fR. -.P -Note that the \fISLP\fR implementation is under development and currently -is not supported. -.SH EXIT STATUS -On success 0 is returned. On error one of the return codes below will -be returned. -.PP -Commands that operate on multiple objects (sessions, records, etc), -iscsiadm/iscsistart will return the first error that is encountered. -iscsiadm/iscsistart will attempt to execute the operation on the objects it -can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is returned. -.TP -.B -0 -ISCSI_SUCCESS - command executed successfully. -.TP -.B -1 -ISCSI_ERR - generic error code. -.TP -.B -2 -ISCSI_ERR_SESS_NOT_FOUND - session could not be found. -.TP -.B -3 -ISCSI_ERR_NOMEM - could not allocate resource for operation. -.TP -.B -4 -ISCSI_ERR_TRANS - connect problem caused operation to fail. -.TP -.B -5 -ISCSI_ERR_LOGIN - generic iSCSI login failure. -.TP -.B -6 -ISCSI_ERR_IDBM - error accessing/managing iSCSI DB. -.TP -.B -7 -ISCSI_ERR_INVAL - invalid argument. -.TP -.B -8 -ISCSI_ERR_TRANS_TIMEOUT - connection timer expired while trying to connect. -.TP -.B -9 -ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure. -.TP -.B -10 -ISCSI_ERR_LOGOUT - iSCSI logout failed. -.TP -.B -11 -ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timed out. -.TP -.B -12 -ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in kernel or iscsid. -.TP -.B -13 -ISCSI_ERR_ACCESS - did not have proper OS permissions to access iscsid or execute iscsiadm command. -.TP -.B -14 -ISCSI_ERR_TRANS_CAPS - transport module did not support operation. -.TP -.B -15 -ISCSI_ERR_SESS_EXISTS - session is logged in. -.TP -.B -16 -ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request. -.TP -.B -17 -ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported. -.TP -.B -18 -ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed. -.TP -.B -19 -ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error. -.TP -.B -20 -ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid. -.TP -.B -21 -ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals found to execute operation on. -.TP -.B -22 -ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs. -.TP -.B -23 -ISCSI_ERR_HOST_NOT_FOUND - could not lookup host. -.TP -.B -24 -ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization failure. -.TP -.B -25 -ISCSI_ERR_ISNS_QUERY - iSNS query failure. -.TP -.B -26 -ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration failed. -.TP -.B -27 -ISCSI_ERR_OP_NOT_SUPP - operation not support -.TP -.B -28 -ISCSI_ERR_BUSY - device or resource in use -.TP -.B -29 -ISCSI_ERR_AGAIN - operation failed, but retrying later may succeed -.TP -.B -30 -ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE - unknown discovery type -.TP -.B -31 -ISCSI_ERR_CHILD_TERMINATED - child process terminated -.TP -.B -32 -ISCSI_ERR_SESSION_NOT_CONNECTED - session likely not connected -.SH EXAMPLES -Discover targets at a given IP address: -.IP -\fBsh#\fR iscsiadm \-\-mode discoverydb \-\-type sendtargets \-\-portal 192.168.1.10 \-\-discover -.PP -Login, must use a node record id found by the discovery: -.IP -\fBsh#\fR iscsiadm \-\-mode node \-\-targetname iqn.2001-05.com.doe:test \-\-portal 192.168.1.1:3260 \-\-login -.PP -Logout: -.IP -\fBsh#\fR iscsiadm \-\-mode node \-\-targetname iqn.2001-05.com.doe:test \-\-portal 192.168.1.1:3260 \-\-logout -.PP -List node records: -.IP -\fBsh#\fR iscsiadm \-\-mode node -.PP -Display all data for a given node record: -.IP -\fBsh#\fR iscsiadm \-\-mode node \-\-targetname iqn.2001-05.com.doe:test \-\-portal 192.168.1.1:3260 -.SH FILES -.TP -/etc/iscsi/iscsid.conf -The configuration file read by \fBiscsid\fR and \fBiscsiadm\fR on startup. -.TP -/etc/iscsi/initiatorname.iscsi -The file containing the iSCSI InitiatorName and InitiatorAlias read by -\fBiscsid\fR and \fBiscsiadm\fR on startup. -.TP -/etc/iscsi/nodes/ -This directory contains the nodes with their targets. -.TP -/etc/iscsi/send_targets -This directory contains the portals. -.SH "SEE ALSO" -.BR iscsid (8) -.SH AUTHORS -Open-iSCSI project -.br -Alex Aizman -.br -Dmitry Yusupov diff --git a/doc/iscsiadm.8.template b/doc/iscsiadm.8.template new file mode 100644 index 0000000..e65a4b0 --- /dev/null +++ b/doc/iscsiadm.8.template @@ -0,0 +1,718 @@ +.TH ISCSIADM 8 "Mar 2022" "" "Linux Administrator's Manual" +.SH NAME +iscsiadm \- open-iscsi administration utility +.SH SYNOPSIS +.B iscsiadm +.B \-m discoverydb +.RB [ \-hV ] +.RB [ \-d +.IR debug_level ] +.RB [ \-P +.IR printlevel ] +.RB [ \-I +.I iface +.BI \-t\ type\ \-p\ ip:port +.RB [ \-lD ] +] | [ +.RB [ \-p +.I ip:port +.B \-t +.IR type ] +.RB [ \-o +.IR operation ] +.RB [ \-n +.IR name ] +.RB [ \-v +.IR value ] +.RB [ \-lD ] +] +.PP +.B iscsiadm +.B \-m discovery +.RB [ \-hV ] +.RB [ \-d +.IR debug_level ] +.RB [ \-P +.IR printlevel ] +.RB [ \-I +.IR iface ] +.RB [ \-t +.IR type ] +.RB [ \-p +.IR ip:port ] +.RB [ \-l ] +.PP +.B iscsiadm +.B \-m node +.RB [ \-hV ] +.RB [ \-d +.IR debug_level ] +.RB [ \-P +.IR printlevel ] +.RB [ \-L +.IR all,manual,automatic,onboot ] +.RB [ \-W ] +.RB [ \-U +.IR all,manual,automatic,onboot ] +.RB [ \-S ] +[ +.RB [ \-T +.IB targetname\ \-p\ ip:port\ \-I +.IR iface ] +.RB [ \-l | \-u | \-R | \-s ] +] +[ +.RB [ \-o +.IR operation ] +.RB [ \-n +.IR name ] +.RB [ \-v +.IR value ] +.RB [ \-p +.IR ip:port ] +] +.PP +.B iscsiadm +.B \-m session +.RB [ \-hV ] +.RB [ \-d +.IR debug_level ] +.RB [ \-P +.IR printlevel ] +.RB [ \-r +.IR sessionid | sysfsdir +.RB [ \-R ] +.RB [ \-u | \-s | \-o +.IR new ] +] +.PP +.B iscsiadm +.B \-m iface +.RB [ \-hV ] +.RB [ \-d +.IR debug_level ] +.RB [ \-P +.IR printlevel ] +.RB [ \-I +.IR ifacename\ | +.B \-H +.IR hostno|MAC ] +[ +.RB [ \-o +.IR operation ] +.RB [ \-n +.IR name ] +.RB [ \-v +.IR value ] +] +[ +.BI \-C\ ping +.RB [ \-a +.IR ip ] +.RB [ \-b +.IR packetsize ] +.RB [ \-c +.IR count ] +.RB [ \-i +.IR interval ] +] +.PP +.B iscsiadm +.B \-m fw +.RB [ \-d +.IR debug_level ] +.RB [ \-l ] +.RB [ \-W ] +.RB [ \-n +.IR name ] +.RB [ \-v +.IR value ] +.PP +.B iscsiadm +.B \-m host +.RB [ \-P +.IR printlevel ] +.RB [ \-H +.IR hostno|MAC ] +[ +.RB [ \-C +.I chap +.RB [ \-x +.IR chap_tbl_idx ] +] | +.RB [ \-C +.I flashnode +.RB [ \-A +.IR portal_type ] +.RB [ \-x +.IR flashnode_idx ] +] | +.RB [ \-C +.IR stats ] +] +[ +.RB [ \-o +.IR operation ] +.RB [ \-n +.IR name ] +.RB [ \-v +.IR value ] +] +.PP +.B iscsiadm +.B \-k priority +.SH DESCRIPTION +The iscsiadm utility is a command-line tool allowing discovery and login +to iSCSI targets, as well as access and management of the open-iscsi +database. +.PP +Open-iscsi does not use the term \fInode\fR as defined by the iSCSI RFC, +where a node is a single iSCSI initiator or target. Open-iscsi uses the +term \fInode\fR to refer to a portal on a target. +.PP +For \fIsession\fR mode, a session id (\fIsid\fR) is used. The \fIsid\fR of a session can be +found by running \fIiscsiadm \-m session \-P 1\fR. The session id and sysfs +path are not currently persistent and is partially determined by when the +session is setup. +.SH NOTES +.PP +Many of the node and discovery operations require that the iSCSI +daemon (iscsid) be running. If running on a system that uses systemd, +the daemon may start up automatically, if enabled, when needed. +.PP +Open-iscsi has two groups of files it needs to store or get access to, +while running: the \fBHOMEDIR\fR and the \fBDBROOT\fR. The following +describes them: +.TP +.B Home Directory +The \fIhome directory\fR for open-iscsi is @HOMEDIR@. This is +where it keeps it's configuration file (\fIiscsid.conf\fR) and it's +initiator name file (\fIinitiatorname.iscsi\fR). +.TP +.B Database Root Directory +The \fIdatabase root directory\fR for open-iscsi is @DBROOT@. This +is where it keeps its flat database files, such as it's list of \fInode\fRs +(see below). +.SH OPTIONS +.TP +\fB\-a\fR, \fB\-\-ip=\fIipaddr\fP +\fIipaddr\fR can be IPv4 or IPv6. +.IP +This option is only valid for \fIping\fR submode. +.TP +\fB\-A\fR, \fB\-\-portal_type=\fI[ipv4|ipv6]\fR +Specify the portal type for the new flash node entry to be created. +.IP +This option is only valid for \fIflashnode\fR submode of \fIhost\fR mode and only with \fInew\fR operation. +.TP +\fB\-b\fR, \fB\-\-packetsize=\fIpacketsize\fP +Specify the ping \fIpacketsize\fR. +.IP +This option is only valid for \fIping\fR submode. +.TP +\fB\-c\fR, \fB\-\-count=\fIcount\fP +\fIcount\fR specifies the number of ping iterations. +.IP +This option is only valid for \fIping\fR submode. +.TP +\fB\-C\fR, \fB\-\-submode=\fIop\fP +Specify the submode for mode. \fIop\fR must be name of submode. +.IP +Currently iscsiadm supports \fIping\fR as a submode for \fIiface\fR. For example: +.IP +iscsiadm \-m iface \-I ifacename \-C ping \-a ipaddr \-b packetsize \-c count \-i interval +.IP +For \fIhost\fR, it supports \fIchap\fR, \fIflashnode\fR and \fIstats\fR as submodes. For example: +.IP +iscsiadm \-m host \-H hostno \-C chap \-x chap_tbl_idx \-o operation +.IP +iscsiadm \-m host \-H hostno \-C flashnode \-x flashnode_idx \-o operation +.IP +iscsiadm \-m host \-H hostno \-C stats +.TP +\fB\-d\fR, \fB\-\-debug=\fIdebug_level\fP +print debugging information. Valid values for \fIdebug_level\fR are 0 to 8. +.TP +\fB\-h\fR, \fB\-\-help\fR +display help text and exit +.TP +\fB\-H\fR, \fB\-\-host=\fI[hostno|MAC]\fR +The \fIhost\fR argument specifies the SCSI host to use for the operation. It can be +the scsi host number assigned to the host by the kernel's scsi layer, or the +MAC address of a scsi host. +.TP +\fB\-i\fR, \fB\-\-interval=\fIinterval\fP +\fIinterval\fP specifies the delay between two ping iterations. +.IP +This option is only valid for \fIping\fR submode. +.TP +\fB\-I\fR, \fB\-\-interface=\fI[iface]\fR +The \fIinterface\fR argument specifies the iSCSI interface to use for the operation. +iSCSI interfaces (\fIiface\fR) are defined in @DBROOT@/ifaces. For hardware +iSCSI (e.g. qla4xxx) the \fIiface\fR configuration must have the hardware address +(\fIiface.hwaddress\fR = port's MAC address) +and the driver/transport_name (\fIiface.transport_name\fR). The \fIiface\fR's name is +then the filename of the iface configuration. For software iSCSI, the iface configuration +must have either the hardware address (\fIiface.hwaddress\fR), or the network +layer's interface name (\fIiface.net_ifacename\fR), and it must have the +driver/transport_name. +.IP +The available drivers/iscsi_transports are \fItcp\fR (software iSCSI over TCP/IP), +\fIiser\fR (software iSCSI over InfiniBand), +\fIqla4xxx\fR (Qlogic 4XXXX and 82XXX HBAs), +\fIcxgb3i\fR and \fIcxgb4i\fR (Chelsio T3 and T4 adapters), +\fIbnx2i\fR (QLogic Netextreme II adapters), +\fIbe2iscsi\fR (Emulex 10G adapter), +\fIqedi\fR (QLogic QEDI 25/40/100Gb adapter), and +\fIocs\fR (Emulex One Connect storage). +Some of these are considered experimental, as they are not fully tested. +.IP +The \fIhwaddress\fR is the MAC address or for software iSCSI it may be the special +value \fIdefault\fR which directs the initiator to not bind the session to a +specific hardware resource and instead allow the network or InfiniBand layer +to decide what to do. There is no need to create an iface configuration with the default +behavior. If you do not specify an \fIiface\fR, then the default behavior is used. +.IP +As mentioned above there is a special iface name \fIdefault\fR. There are +others which do not bind the session to a specific card, but instead bind +the session to the transport: +\fIiser\fR, +\fIcxgb3i\fR, +\fIcxgb4i\fR, and +\fIbnx2i\fR. +.IP +In \fIdiscovery\fR mode multiple interfaces can be specified by passing in +multiple \fI\-I/\-\-interface\fR instances. For example: +.IP +\fBsh#\fR iscsiadm \-m discoverydb \-t st \-p ip:port \-I iface0 \-I iface2 \-\-discover +.IP +Will direct iscsiadm to setup the node db to create records which will create +sessions through the two interfaces passed in. +.IP +In \fInode\fR mode, only a single interface is supported in each call to iscsiadm. +.IP +This option is valid for \fIdiscovery\fR, \fInode\fR and \fIiface\fR modes. +.TP +\fB\-k\fR, \fB\-\-killiscsid=\fI[priority]\fR +Currently \fIpriority\fR must be zero. This will immediately stop all iscsid +operations and shutdown iscsid. It does not logout any sessions. Running +this command is the same as doing \fIkillall iscsid\fR. Neither should +normally be used, because if iscsid is doing error recovery or if there +is an error while iscsid is not running, the system may not be able to recover. +This command and iscsid's SIGTERM handling are experimental. +.TP +\fB\-D\fR, \fB\-\-discover\fR +Discover targets using the discovery record with the \fIrecid\fR matching +the the discovery type and portal passed in. If there is no matching record, +it will be created using the iscsid.conf discovery settings. +This must be passed in to \fIdiscoverydb\fR mode to instruct iscsiadm to perform +discovery. +.IP +This option is only valid for \fISendTargets\fR discovery mode. +.TP +\fB\-l\fR, \fB\-\-login\fR +For \fInode\fR and \fIfw\fR modes, login to a specified record. For \fIdiscovery\fR mode, +login to all discovered targets. +.IP +This option is only valid for \fIdiscovery\fR, \fInode\fR, and \fIfw\fR modes. +For \fIfw\fR mode only, \fIname\fR and \fIvalue\fR pairs can optionally be passed in, +so that those values get used for the sessions created. In this case, no \fIop\fR +is needed, since \fIupdate\fR is assumed. +.TP +\fB\-L\fR, \fB\-\-loginall=\fI[all|manual|automatic|onboot]\fR +For \fInode\fR mode, login to all sessions with the node or conn startup values passed +in or all running session, except ones marked \fIonboot\fR, if \fIall\fR is passed in. +.IP +This option is only valid for \fInode\fR mode (it is valid but not functional +for \fIsession\fR mode). +.TP +\fB\-W\fR, \fB\-\-\-no_wait\fR +In \fInode\fR, \fIdiscovery\fR, or \fIfw\fR (firmware) mode, +do not wait for a response from the target(s). +This means that success will be returned if the command is able to +send the login requests, whether or not they succeed. In this case, it will +be up to the caller to poll for success (i.e. session creation). +.TP +\fB\-m\fR, \fB\-\-mode \fIop\fR +specify the mode. \fIop\fR +must be one of \fIdiscovery\fR, \fIdiscoverydb\fR, \fInode\fR, \fIfw\fR, +\fIhost\fR, \fIiface\fR or \fIsession\fR. +.IP +If no other options are specified: for \fIdiscovery\fR, \fIdiscoverydb\fR and +\fInode\fR mode, all of their respective records are displayed; for \fIsession\fR mode, +all active sessions and connections are displayed; for \fIfw\fR mode, all boot +firmware values are displayed; for \fIhost\fR mode, all iSCSI hosts are displayed; +and for \fIiface\fR mode, all interfaces setup in @DBROOT@/ifaces are displayed. +.TP +\fB\-n\fR, \fB\-\-name=\fIname\fR +In \fInode\fR mode, specify a field \fIname\fR in a record. In \fIflashnode\fR submode +of \fIhost\fR mode, specify name of the flash node parameter. +.IP +For use with the \fIupdate\fR operator. +.TP +\fB\-o\fR, \fB\-\-op=\fIop\fR +Specifies a database operator \fIop\fR. \fIop\fR must be one of +\fInew\fR, \fIdelete\fR, \fIupdate\fR, \fIshow\fR or \fInonpersistent\fR. +.IP +For \fIiface\fR mode, \fIapply\fR and \fIapplyall\fR are also applicable. +.IP +For \fIflashnode\fR submode of \fIhost\fR mode, \fIlogin\fR and \fIlogout\fR are also applicable. +.IP +This option is valid for all modes except \fIfw\fR. Delete should not be used +on a running session. If it is iscsiadm will stop the session and then delete the +record. +.IP +An \fIop\fR of \fInew\fR creates a new database record for a given object. In \fInode\fR mode, the +\fIrecid\fR is the target name and portal (IP:port). In \fIiface\fR mode, the \fIrecid\fR +is the iface name. In \fIdiscovery\fR mode, the \fIrecid\fR is the portal and +discovery type. +.IP +In \fIsession\fR mode, the \fInew\fR operation logs in a new session using +the same node database and iface information as the specified session. +.IP +In \fIdiscovery\fR mode, if the \fIrecid\fR and \fInew\fR operation is passed in, +but the \fI\-\-discover\fR argument is not passed in, then iscsiadm will only create a +discovery record (it will not perform discovery). If the \fI\-\-discover\fR +argument is passed in with the portal and discovery type, then iscsiadm +will create the discovery record if needed, and it will create records +for portals returned by the target that do not yet have a node DB record. +.IP +Setting \fIop\fR to \fIdelete\fR deletes the specified \fIrecid\fR. In \fIdiscovery\fR mode, if +iscsiadm is performing discovery, it will delete records for portals that +are no longer returned. +.IP +Setting \fIop\fR to \fIupdate\fR will update the \fIrecid\fR with \fIname\fR to the specified +\fIvalue\fR. In discovery mode, if iscsiadm is performing discovery the +\fIrecid\fR, \fIname\fR and \fIvalue\fR arguments are not needed. The +update operation will operate on the portals returned by the target, +and will update the node records with information from the configuration file and +command line. +.IP +The \fIop\fR value of \fIshow\fR is the default behaviour for \fInode\fR, +\fIdiscovery\fR and \fIiface\fR mode. It is +also used when there are no commands passed into \fIsession\fR mode and a +running \fIsid\fR is passed in. +If \fIname\fR and \fIvalue\fR are passed in, they are currently ignored in \fIshow\fR mode. +.IP +An \fIop\fR value of \fInonpersistent\fR instructs iscsiadm to not manipulate the node DB. +.IP +An \fIop\fR value of \fIapply\fR will cause the network settings to take effect on the specified iface. +.IP +An \fIop\fR value of \fIapplyall\fR will cause the network settings to take effect on all the +ifaces whose MAC address or host number matches that of the specific host. +.IP +An \fIop\fR value of \fIlogin\fR will log into the specified flash node entry. +.IP +An \fIop\fR value of \fIlogout\fR does the logout from the given flash node entry. +.TP +\fB\-p\fR, \fB\-\-portal=\fIip[:port]\fR +Use target portal with IP address \fIip\fR and port \fIport\fR. If \fIport\fI is not passed +in the default value of 3260 is used. +.IP +IPv6 addresses can be specified as \fI[ddd.ddd.ddd.ddd]:port\fI or \fIddd.ddd.ddd.ddd\fR. +.IP +Hostnames can also be used for the \fIip\fI argument. +.IP +This option is only valid for \fIdiscovery\fR, or for \fInode\fR operations with +the \fInew\fR operator. +.IP +This should be used along with \fI\-\-target\fR in \fInode\fR mode, to specify what +the open-iscsi documents refer to as a node or node record. Note: open-iscsi's +use of the word node, does not match the iSCSI RFC's iSCSI Node term. +.TP +\fB\-P\fR, \fB\-\-print=\fIprintlevel\fR +If in \fInode\fR mode print nodes in tree format. If in \fIsession\fR mode print +sessions in tree format. If in \fIdiscovery\fR mode print the nodes in +tree format. +.TP +\fB\-T\fR, \fB\-\-targetname=\fItargetname\fR +Use target \fItargetname\fR. +.IP +This should be used along with \fI\-\-portal\fR in \fInode\fR mode, to specify what +the open-iscsi documents refer to as a node or node record. Note: open-iscsi's +use of the word node, does not match the iSCSI RFC's iSCSI Node term. +.TP +\fB\-r\fR, \fB\-\-sid=\fIsid | sysfsdir\fR +Use session ID \fIsid\fR. The session ID of a session can be found from running +iscsiadm in session mode with the \fI\-\-info\fR argument. +.IP +Instead of a session ID, a sysfs path containing the session can be used. +For example using one of the following: +/sys/devices/platform/hostH/sessionS/targetH:B:I/H:B:I:L, +/sys/devices/platform/hostH/sessionS/targetH:B:I, or +/sys/devices/platform/hostH/sessionS, for the \fIsysfsdir\fR argument would +result in the session with session ID \fIS\fR to be used. +.IP +\fIsid | sysfsdir\fR is only required for \fIsession\fR mode. +.TP +\fB\-R\fR, \fB\-\-rescan\fR +In \fIsession\fR mode, if \fIsid\fR is also passed in, rescan the session. +If no \fIsid\fR has been passed in rescan all running sessions. +.IP +In \fInode\fR mode, rescan a session running through the target, portal, iface +tuple passed in. +.TP +\fB\-s\fR, \fB\-\-stats\fR +Display session statistics. +This option when used with \fIhost\fR mode, displays host statistics. +.TP +\fB\-S\fR, \fB\-\-show\fR +When displaying records, do not hide masked values, such as the CHAP +secret (password). +.IP +This option is only valid for \fInode\fR and \fIsession\fR mode. +.TP +\fB\-t\fR, \fB\-\-type=\fItype\fR +\fItype\fR must be \fIsendtargets\fR (or abbreviated as \fIst\fR), +\fIslp\fR, \fIisns\fR or \fIfw\fR. Currently only \fIsendtargets\fR, \fIfw\fR, and +\fIiSNS\fR are supported, see the \fBDISCOVERY TYPES\fR section. +.IP +This option is only valid for \fIdiscovery\fR mode. +.TP +\fB\-u\fR, \fB\-\-logout\fR +Logout for the specified record. +.IP +This option is only valid for \fInode\fR and \fIsession\fR mode. +.TP +\fB\-U\fR, \fB\-\-logoutall=\fI[all,manual,automatic|onboot]\fR +Logout of all sessions with the node or conn startup values passed in or all +running sessions, except ones marked \fIonboot\fR, if \fIall\fR is passed in. +.IP +This option is only valid for \fInode\fR mode (it is valid but not functional +for \fIsession\fR mode). +.TP +\fB\-v\fR, \fB\-\-value=\fIvalue\fR +Specify a \fIvalue\fR for use with the \fIupdate\fR operator, or for firmware login mode. +.IP +This option is only valid for \fInode\fR mode and \fIflashnode\fR submode of \fIhost\fR mode. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version and exit. +.TP +\fB\-x\fR, \fB\-\-index=\fIindex\fR +Specify the \fIindex\fR of the entity to operate on. +.IP +This option is only valid for \fIchap\fR and \fIflashnode\fR submodes of \fIhost\fR mode. +.SH DISCOVERY TYPES +iSCSI defines 3 discovery types: \fISendTargets\fR, \fISLP\fR, and \fIiSNS\fR. +.PP +A special discovery type called +.I fw +(for firmware) is also supported, for discovering firmware interfaces, +and populating the interface database in the process. +.TP +.B +SendTargets +A native iSCSI protocol which allows each iSCSI +target to send a list of available targets to the initiator. +.TP +.B +SLP +Optionally an iSCSI target can use the Service Location Protocol (SLP) +to announce the available targets. The initiator can either implement +SLP queries directly or can use a separate tool to acquire the +information about available targets. +.TP +.B +iSNS +iSNS (Internet Storage Name Service) records information about storage +volumes within a larger network. To utilize iSNS, pass the address and +optionally the port of the iSNS server to do discovery to. +.TP +.B +fw +Firmware mode. +Several NICs and systems contain a mini iSCSI initiator which can be used +for boot. To get the values used for boot the \fIfw\fR option can be used. +Doing \fIfw\fR discovery does not store persistent records in the node or +discovery DB, because the values are stored in the system's or NIC's +resource. +.IP +Performing \fIfw\fR discovery will print the portals, like with other discovery +methods. To see other settings like CHAP values and initiator settings, +like you would in \fInode\fR mode, run \fIiscsiadm \-m fw\fR. +.P +Note that the \fISLP\fR implementation is under development and currently +is not supported. +.SH EXIT STATUS +On success 0 is returned. On error one of the return codes below will +be returned. +.PP +Commands that operate on multiple objects (sessions, records, etc), +iscsiadm/iscsistart will return the first error that is encountered. +iscsiadm/iscsistart will attempt to execute the operation on the objects it +can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is returned. +.TP +.B +0 +ISCSI_SUCCESS - command executed successfully. +.TP +.B +1 +ISCSI_ERR - generic error code. +.TP +.B +2 +ISCSI_ERR_SESS_NOT_FOUND - session could not be found. +.TP +.B +3 +ISCSI_ERR_NOMEM - could not allocate resource for operation. +.TP +.B +4 +ISCSI_ERR_TRANS - connect problem caused operation to fail. +.TP +.B +5 +ISCSI_ERR_LOGIN - generic iSCSI login failure. +.TP +.B +6 +ISCSI_ERR_IDBM - error accessing/managing iSCSI DB. +.TP +.B +7 +ISCSI_ERR_INVAL - invalid argument. +.TP +.B +8 +ISCSI_ERR_TRANS_TIMEOUT - connection timer expired while trying to connect. +.TP +.B +9 +ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure. +.TP +.B +10 +ISCSI_ERR_LOGOUT - iSCSI logout failed. +.TP +.B +11 +ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timed out. +.TP +.B +12 +ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in kernel or iscsid. +.TP +.B +13 +ISCSI_ERR_ACCESS - did not have proper OS permissions to access iscsid or execute iscsiadm command. +.TP +.B +14 +ISCSI_ERR_TRANS_CAPS - transport module did not support operation. +.TP +.B +15 +ISCSI_ERR_SESS_EXISTS - session is logged in. +.TP +.B +16 +ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request. +.TP +.B +17 +ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported. +.TP +.B +18 +ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed. +.TP +.B +19 +ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error. +.TP +.B +20 +ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid. +.TP +.B +21 +ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals found to execute operation on. +.TP +.B +22 +ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs. +.TP +.B +23 +ISCSI_ERR_HOST_NOT_FOUND - could not lookup host. +.TP +.B +24 +ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization failure. +.TP +.B +25 +ISCSI_ERR_ISNS_QUERY - iSNS query failure. +.TP +.B +26 +ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration failed. +.TP +.B +27 +ISCSI_ERR_OP_NOT_SUPP - operation not support +.TP +.B +28 +ISCSI_ERR_BUSY - device or resource in use +.TP +.B +29 +ISCSI_ERR_AGAIN - operation failed, but retrying later may succeed +.TP +.B +30 +ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE - unknown discovery type +.TP +.B +31 +ISCSI_ERR_CHILD_TERMINATED - child process terminated +.TP +.B +32 +ISCSI_ERR_SESSION_NOT_CONNECTED - session likely not connected +.SH EXAMPLES +Discover targets at a given IP address: +.IP +\fBsh#\fR iscsiadm \-\-mode discoverydb \-\-type sendtargets \-\-portal 192.168.1.10 \-\-discover +.PP +Login, must use a node record id found by the discovery: +.IP +\fBsh#\fR iscsiadm \-\-mode node \-\-targetname iqn.2001-05.com.doe:test \-\-portal 192.168.1.1:3260 \-\-login +.PP +Logout: +.IP +\fBsh#\fR iscsiadm \-\-mode node \-\-targetname iqn.2001-05.com.doe:test \-\-portal 192.168.1.1:3260 \-\-logout +.PP +List node records: +.IP +\fBsh#\fR iscsiadm \-\-mode node +.PP +Display all data for a given node record: +.IP +\fBsh#\fR iscsiadm \-\-mode node \-\-targetname iqn.2001-05.com.doe:test \-\-portal 192.168.1.1:3260 +.SH FILES +.TP +@HOMEDIR@/iscsid.conf +The configuration file read by \fBiscsid\fR and \fBiscsiadm\fR on startup. +.TP +@HOMEDIR@/initiatorname.iscsi +The file containing the iSCSI InitiatorName and InitiatorAlias read by +\fBiscsid\fR and \fBiscsiadm\fR on startup. +.TP +@DBROOT@/nodes/ +This directory contains the nodes with their targets. +.TP +@DBROOT@/send_targets +This directory contains the portals. +.SH "SEE ALSO" +.BR iscsid (8) +.SH AUTHORS +Open-iSCSI project +.br +Alex Aizman +.br +Dmitry Yusupov diff --git a/doc/iscsid.8 b/doc/iscsid.8 deleted file mode 100644 index db996b4..0000000 --- a/doc/iscsid.8 +++ /dev/null @@ -1,84 +0,0 @@ -.TH ISCSID 8 "July 2005" "" "Linux Administrator's Manual" -.SH NAME -iscsid \- Open-iSCSI daemon -.SH SYNOPSIS -.BI iscsid -[OPTION] -.SH "DESCRIPTION" -The -.B iscsid -implements the control path of iSCSI protocol, plus some management -facilities. For example, the daemon could be configured to automatically -re-start discovery at startup, based on the contents of persistent -iSCSI database. -.SH OPTIONS -.TP -.BI [-c|--config=]\fIconfig\-file\fP -Read configuration from \fIconfig\-file\fR rather than the default -\fI/etc/iscsi/iscsid.conf\fR file. -.TP -.BI [-i|--initiatorname=]\fIiname\-file\fP -Read initiator name from \fIiname\-file\fR rather than the default -\fI/etc/iscsi/initiatorname.iscsi\fR file. -.TP -.BI [-f|--foreground] -run -.B iscsid -in the foreground. Implies -.BR --no-pid-file . -.TP -.BI [-d|--debug=] debug_level -print debugging information. Valid values for debug_level are 0 to 8. -.TP -.BI [-u|--uid=] uid -run under user ID \fIuid\fR (default is the current user ID). -.TP -.BI [-g|--gid=] gid -run under user group ID \fIgid\fR (default is the current user group ID). -.TP -.BI [-n|--no-pid-file] -do not write a process ID file. Conflicts with the -.BI --pid= -option. -.TP -.BI [-p|--pid=] pid\-file -write process ID to \fIpid\-file\fR rather than the default -\fI/run/iscsid.pid\fR. Conflicts with the -.BI --no-pid-file -option. -.TP -.BI [-h|--help] -display this help and exit -.TP -.BI [-v|--version] -display version and exit. - -.SH FILES -.TP -/etc/iscsi/iscsid.conf -The configuration file read by -.B iscsid -and -.B iscsiadm -on startup. -.TP -/etc/iscsi/initiatorname.iscsi -The file containing the iSCSI initiatorname -and initiatoralias read by -.B iscsid -and -.B iscsiadm -on startup. -.TP -/etc/iscsi/nodes -Open-iSCSI persistent configuration database - -.SH "SEE ALSO" -.BR iscsiadm (8) - -.SH AUTHORS -Open-iSCSI project -.br -Alex Aizman -.br -Dmitry Yusupov diff --git a/doc/iscsid.8.template b/doc/iscsid.8.template new file mode 100644 index 0000000..0d122a0 --- /dev/null +++ b/doc/iscsid.8.template @@ -0,0 +1,84 @@ +.TH ISCSID 8 "July 2005" "" "Linux Administrator's Manual" +.SH NAME +iscsid \- Open-iSCSI daemon +.SH SYNOPSIS +.BI iscsid +[OPTION] +.SH "DESCRIPTION" +The +.B iscsid +implements the control path of iSCSI protocol, plus some management +facilities. For example, the daemon could be configured to automatically +re-start discovery at startup, based on the contents of persistent +iSCSI database. +.SH OPTIONS +.TP +.BI [-c|--config=]\fIconfig\-file\fP +Read configuration from \fIconfig\-file\fR rather than the default +\fI@HOMEDIR@/iscsid.conf\fR file. +.TP +.BI [-i|--initiatorname=]\fIiname\-file\fP +Read initiator name from \fIiname\-file\fR rather than the default +\fI@HOMEDIR@/initiatorname.iscsi\fR file. +.TP +.BI [-f|--foreground] +run +.B iscsid +in the foreground. Implies +.BR --no-pid-file . +.TP +.BI [-d|--debug=] debug_level +print debugging information. Valid values for debug_level are 0 to 8. +.TP +.BI [-u|--uid=] uid +run under user ID \fIuid\fR (default is the current user ID). +.TP +.BI [-g|--gid=] gid +run under user group ID \fIgid\fR (default is the current user group ID). +.TP +.BI [-n|--no-pid-file] +do not write a process ID file. Conflicts with the +.BI --pid= +option. +.TP +.BI [-p|--pid=] pid\-file +write process ID to \fIpid\-file\fR rather than the default +\fI/run/iscsid.pid\fR. Conflicts with the +.BI --no-pid-file +option. +.TP +.BI [-h|--help] +display this help and exit +.TP +.BI [-v|--version] +display version and exit. + +.SH FILES +.TP +@HOMEDIR@/iscsid.conf +The configuration file read by +.B iscsid +and +.B iscsiadm +on startup. +.TP +@HOMEDIR@/initiatorname.iscsi +The file containing the iSCSI initiatorname +and initiatoralias read by +.B iscsid +and +.B iscsiadm +on startup. +.TP +@DBROOT@/nodes +Open-iSCSI persistent configuration database + +.SH "SEE ALSO" +.BR iscsiadm (8) + +.SH AUTHORS +Open-iSCSI project +.br +Alex Aizman +.br +Dmitry Yusupov -- cgit v1.2.1