path: root/doc/iscsiadm.8

.TH ISCSIADM 8 "Sep 2006" "" "Linux Administrator's Manual"
.SH NAME
iscsiadm \- open-iscsi administration utility
.SH SYNOPSIS
\fBiscsiadm\fR -m discovery [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I iface -t type -p ip:port [ -l ] ] | 
[ -o operation ] [ -n name ] [ -v value ]

\fBiscsiadm\fR -m node [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -L all,manual,automatic ] [ -U all,manual,automatic ] [ -S ] [ [ -T targetname -p ip:port -I iface ] [ -l | -u | -R | -s] ]
[ [ -o operation ]  [ -n name ] [ -v value ] [ -p ip:port ] ]

\fBiscsiadm\fR -m session [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -r sessionid | sysfsdir [ -R ] [ -u | -s ] ]

\fBiscsiadm\fR -m iface [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I ifacename ] [ [ -o  operation  ] [ -n name ] [ -v value ] ]

\fBiscsiadm\fR -m fw [-l]

\fBiscsiadm\fR -m host [ -P printlevel ] [ -H hostno ]

\fBiscsiadm\fR -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.

Open-iscsi does not use the term node as defined by the iSCSI RFC,
where a node is a single iSCSI initiator or target. Open-iscsi uses the
term node to refer to a portal on a target.

For session mode, a session id (sid) is used. The sid of a session can be
found by running iscsiadm -m session -P 1. 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 node and discovery operations require that the iSCSI
daemon (iscsid) be running.

.SH OPTIONS

.TP
\fB\-d\fR, \fB\-\-debug=\fIdebug_level\fP
print debugging information. Valid values for debug_level are 0 to 8.

.TP
\fB\-h\fR, \fB\-\-help\fR
display help text and exit

.TP
\fB\-I\fR, \fB\-\-interface\fI[iface]\fR
The interface argument specifies the iSCSI interface to use for the operation.
iSCSI interfaces (iface) are defined in /etc/iscsi/ifaces. For hardware
iSCSI (qla4xxx) the iface config must have the hardware address
(iface.hwaddress = port's MAC address)
and the driver/transport_name (iface.transport_name). The iface's name is
then the filename of the iface config. For software iSCSI, the iface config
must have either the hardware address (iface.hwaddress), or the network
layer's interface name (iface.net_ifacename), and it must have the
driver/transport_name

The available drivers/iscsi_transports are tcp (software iSCSI over TCP/IP),
iser (software iSCSI over infinniband), or qla4xxx (Qlogic 4XXXX HBAs). The
hwaddress is the MAC address or for software iSCSI it may be the special
value "default" which directs the initiator to not bind the session to a
specific hardware resource and instead allow the network or infinniband layer
to decide what to do. There is no need to create a iface config with the default
behavior. If you do not specify a iface, then the default behavior is used.

As mentioned above there is a special iface name default. There are three
others -- cxgb3i, bnx2i and iser, which does not bind the session to a specific card, but will bind the session to the cxgb3i, bnx2i or iser transport. These
are experimental and the use is not supported as a stable interface yet.

In discovery mode multiple interfaces can be specific by passing in multiple
-I/--interface instances. For example, 

"iscsiadm -m discovery -t st -p mytarget -I iface0 -I iface2"

Will direct iscsiadm to setup the node db to create records which will create
sessions though the two intefaces passed in.

In node mode, only a single interface is supported in each call to iscsiadm.
.IP
This option is valid for discovery, node and iface mode.

.TP
\fB\-k\fR, \fB\-\-killiscsid=\fI[priority]\fR
Currently priority 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 "killall iscsid". Neither should
normally not 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\-l\fR, \fB\-\-login\fR
For node and fw mode, login to a specified record. For discovery mode, login to
all discovered targets.
.IP
This option is only valid for discovery and node modes.

.TP
\fB\-L\fR, \fB\-\-loginall==\fI[all|manual|automatic]\fR
For node mode, login all sessions with the node or conn startup values passed
in or all running sesssion, except ones marked onboot, if all is passed in.
.IP
This option is only valid for node mode (it is valid but not functional
for session mode).


.TP
\fB\-m, \-\-mode \fIop\fR
specify the mode. \fIop\fR
must be one of \fIdiscovery\fR, \fInode\fR, \fIfw\fR, \fIhost\fR \fIiface\fR or \fIsession\fR.
.IP
If no other options are specified: for \fIdiscovery\fR and \fInode\fR, all
of their respective records are displayed; for \fIsession\fR, all active
sessions and connections are displayed; for \fIfw\fR, all boot firmware
values are displayed; for \fIhost\fR, all iSCSI hosts are displayed; and
for \fIiface\fR, all ifaces setup in /etc/iscsi/ifaces are displayed.

.TP
\fB\-n\fR, \fB\-\-name=\fIname\fR
Specify a field \fIname\fR in a record. For use with the \fIupdate\fR
operator.
.IP

.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 or \fIshow\fR.
.IP
This option is valid for all modes except fw. Delete should not be used on a running session. If it is iscsiadm will stop the session and then delete the
record.
.IP
\fInew\fR creates a new database record for a given \fIportal\fR (IP address and port number). In discovery mode, iscsiadm will create new records for portals returned by the target.
.IP
\fIdelete\fR deletes a specified \fIrecid\fR. In discovery node, iscsiadm will delete records for portals that are no longer returned.
.IP
\fIupdate\fR will update the \fIrecid\fR with \fIname\fR to the specified \fIvalue\fR. In discovery node 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 record with info from the config file and command line.
.IP
\fIshow\fR is the default behaviour for node, discovery and iface mode. It is
also used when there are no commands passed into session mode and a running
sid is passed in.
\fIname\fR and \fIvalue\fR are currently ignored when used with \fIshow\fR.

.TP
\fB\-p\fR, \fB\-\-portal=\fIip[:port]\fR
Use target portal with ip-address \fIip\fR and \fIport\fR, the default
\fIport\fR value is 3260.
.IP
This option is only valid for discovery, or for node operations with
the \fInew\fR operator.
.IP
This should be used along with --target in node mode, to specify what the open-iscsi docs 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 node mode print nodes in tree format. If in session mode print
sessions in tree format. If in discovery 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 --portal in node mode, to specify what the open-iscsi docs 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 sid of a session can be found from running
iscsiadm in session mode with the --info argument.

Instead of sid, 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 sysfsdir argument would result in the session with sid S to be used.
.IP
\fIsid | sysfsdir\fR is only required for session mode.

.TP
\fB\-R\fR,  \fB\-\-rescan\fR
In session mode, if sid is also passed in rescan the session. If no sid has
been passed in  rescan all running sessions.

In node mode, rescan a session running through the target, portal, iface
tuple passed in.

.TP
\fB\-s\fR, \fB\-\-stats\fR
Display session 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 node and session 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 sendtargets, fw, and
iSNS is supported, see the DISCOVERY TYPES section.
.IP
This option is only valid for discovery mode.

.TP
\fB\-u\fR, \fB\-\-logout\fR
logout for a specified record.
.IP
This option is only valid for node and session mode.

.TP
\fB\-U\fR, \fB\-\-logoutall==\fI[all,manual,automatic]\fR
logout all sessions with the node or conn startup values passed in or all
running sesssion, except ones marked onboot, if all is passed in.
.IP
This option is only valid for node mode (it is valid but not functional
for session mode).

.TP
\fB\-v\fR, \fB\-\-value=\fIvalue\fR
Specify a \fIvalue\fR for use with the \fIupdate\fR operator.
.IP
This option is only valid for node mode.

.TP
\fB\-V\fR, \fB\-\-version\fR
display version and exit

.SH DISCOVERY TYPES
iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.

.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, the address of the
iSNS server must be set in iscsid.conf using the "isns.address" value,
and iscsiadm must be run in discovery mode with the "isns" discovery type.

iSNS support in open-iscsi is experimental. The iscsid.conf settings,
iscsiadm syntax and node DB layout may change.

.TP
.B
fw
Several NICs and systems contain a mini iSCSI initiator which can be used
for boot. To get the values used for boot the fw option can be used.
Doing fw 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.

Performing fw discovery will print the portals, like with other discovery
methods. To see other settings like CHAP values and initiator settings,
like you would in node mode, run "iscsiadm -m fw".

fw support in open-iscsi is experimental. The settings and iscsiadm
syntax and output format may change.

.P
iscsiadm supports the
.B
iSNS (isns)
or
.B
SendTargets (st)
discovery type. An SLP implementation is under development.

.SH EXAMPLES

.nf
Discover targets at a given IP address:

.ft R
	iscsiadm --mode discovery --type sendtargets --portal 192.168.1.10
.nf

Login, must use a node record id found by the discovery:

.ft R
	iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --login
.nf

Logout:

.ft R
	iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --logout
.nf

List node records:

.ft R
	iscsiadm --mode node

.nf

Display all data for a given node record:

.ft R
	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 <http://www.open-iscsi.org/>
.br
Alex Aizman <itn780@yahoo.com>
.br
Dmitry Yusupov <dmitry_yus@yahoo.com>