ISCSIADM(8) Linux Administrator's Manual ISCSIADM(8)NAMEiscsiadm - open-iscsi administration utility
SYNOPSISiscsiadm-m discoverydb [ -hV ] [ -d debug_level ] [ -P printlevel ] [
-I iface -t type -p ip:port [ -lD ] ] | [ [ -p ip:port -t type ] [ -o
operation ] [ -n name ] [ -v value ] [ -lD ] ]
iscsiadm-m discovery [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I
iface -t type -p ip:port [ -l ] ] | [ [ -p ip:port ] [ -l | -D ] ]
iscsiadm-m node [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -L
all,manual,automatic ] [ -U all,manual,automatic ] [ -S ] [ [ -T tar‐
getname -p ip:port -I iface ] [ -l | -u | -R | -s] ] [ [ -o operation ]
[ -n name ] [ -v value ] [ -p ip:port ] ]
iscsiadm-m session [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -r
sessionid | sysfsdir [ -R ] [ -u | -s | -o new ] ]
iscsiadm-m iface [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I
ifacename | -H hostno|MAC ] [ [ -o operation ] [ -n name ] [ -v
value ] ]
iscsiadm-m fw [-l]
iscsiadm-m host [ -P printlevel ] [ -H hostno|MAC ]
iscsiadm-k priority
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.
Note that many of the node and discovery operations require that the
iSCSI daemon (iscsid) be running.
OPTIONS-d, --debug=debug_level
print debugging information. Valid values for debug_level are 0
to 8.
-h, --help
display help text and exit
-H, --host=[hostno|MAC]
The host agrument specifies the SCSI host to use for the opera‐
tion. 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.
-I, --interface=[iface]
The interface argument specifies the iSCSI interface to use for
the operation. iSCSI interfaces (iface) are defined in
/var/lib/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.trans‐
port_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 specified by pass‐
ing in multiple -I/--interface instances. For example,
"iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2
--discover"
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.
This option is valid for discovery, node and iface mode.
-k, --killiscsid=[priority]
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 com‐
mand and iscsid's SIGTERM handling are experimental.
-D, --discover
Discover targets using the discovery record with the recid
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 discoverydb mode to
instruct iscsiadm to perform discovery.
This option is only valid for SendTargets discovery mode.
-l, --login
For node and fw mode, login to a specified record. For discovery
mode, login to all discovered targets.
This option is only valid for discovery and node modes.
-L, --loginall==[all|manual|automatic]
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.
This option is only valid for node mode (it is valid but not
functional for session mode).
-m, --mode op
specify the mode. op must be one of discoverydb, node, fw, host
iface or session.
If no other options are specified: for discoverydb and node, all
of their respective records are displayed; for session, all
active sessions and connections are displayed; for fw, all boot
firmware values are displayed; for host, all iSCSI hosts are
displayed; and for iface, all ifaces setup in
/var/lib/iscsi/ifaces are displayed.
-n, --name=name
Specify a field name in a record. For use with the update opera‐
tor.
-o, --op=op
Specifies a database operator op. op must be one of new, delete,
update, show or nonpersistent.
For iface mode, apply and applyall are also applicable.
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.
new creates a new database record for a given object. In node
mode, the recid is the target name and portal (IP:port). In
iface mode, the recid is the iface name. In discovery mode, the
recid is the portal and discovery type.
In session mode, the new operation logs in a new session using
the same node database and iface information as the specified
session.
In discovery mode, if the recid and new operation is passed in,
but the --discover argument is not, then iscsiadm will only cre‐
ate a discovery record (it will not perform discovery). If the
--discover 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.
delete deletes a specified recid. In discovery node, if iscsiadm
is performing discovery it will delete records for portals that
are no longer returned.
update will update the recid with name to the specified value.
In discovery node, if iscsiadm is performing discovery the
recid, name and value arguments are not needed. The update
operation will operate on the portals returned by the target,
and will update the node records with info from the config file
and command line.
show 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. name and value are
currently ignored when used with show.
nonpersistent instructs iscsiadm to not manipulate the node DB.
apply will cause the network settings to take effect on the
specified iface.
applyall will cause the network settings to take effect on all
the ifaces whose MAC address or host number matches that of the
specific host.
-p, --portal=ip[:port]
Use target portal with ip-address ip and port. If port is not
passed in the default port value is 3260.
IPv6 addresses can bs specified as [ddd.ddd.ddd.ddd]:port or
ddd.ddd.ddd.ddd.
Hostnames can also be used for the ip argument.
This option is only valid for discovery, or for node operations
with the new operator.
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.
-P, --print=printlevel
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.
-T, --targetname=targetname
Use target targetname.
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.
-r, --sid=sid | sysfsdir
Use session ID sid. The sid of a session can be found from run‐
ning 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/plat‐
form/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/devices/plat‐
form/hostH/sessionS/targetH:B:I, or /sys/devices/plat‐
form/hostH/sessionS, for the sysfsdir argument would result in
the session with sid S to be used.
sid | sysfsdir is only required for session mode.
-R, --rescan
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, por‐
tal, iface tuple passed in.
-s, --stats
Display session statistics.
-S, --show
When displaying records, do not hide masked values, such as the
CHAP secret (password).
This option is only valid for node and session mode.
-t, --type=type
type must be sendtargets (or abbreviated as st), slp, isns or
fw. Currently only sendtargets, fw, and iSNS is supported, see
the DISCOVERY TYPES section.
This option is only valid for discovery mode.
-u, --logout
logout for a specified record.
This option is only valid for node and session mode.
-U, --logoutall==[all,manual,automatic]
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.
This option is only valid for node mode (it is valid but not
functional for session mode).
-v, --value=value
Specify a value for use with the update operator.
This option is only valid for node mode.
-V, --version
display version and exit
DISCOVERY TYPES
iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.
SendTargets
A native iSCSI protocol which allows each iSCSI target to send a
list of available targets to the initiator.
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.
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.
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 persis‐
tent 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 isc‐
siadm syntax and output format may change.
iscsiadm supports the iSNS (isns) or SendTargets (st) discovery type.
An SLP implementation is under development.
EXIT STATUS
On success 0 is returned. On error one of the return codes below will
be returned.
Commands that operation 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.
0 ISCSI_SUCCESS - command executed successfully.
1 ISCSI_ERR - generic error code.
2 ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
3 ISCSI_ERR_NOMEM - could not allocate resource for operation.
4 ISCSI_ERR_TRANS - connect problem caused operation to fail.
5 ISCSI_ERR_LOGIN - generic iSCSI login failure.
6 ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
7 ISCSI_ERR_INVAL - invalid argument.
8 ISCSI_ERR_TRANS_TIMEOUT - connection timer exired while trying
to connect.
9 ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
10 ISCSI_ERR_LOGOUT - iSCSI logout failed.
11 ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
12 ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
kernel or iscsid.
13 ISCSI_ERR_ACCESS - did not have proper OS permissions to access
iscsid or execute iscsiadm command.
14 ISCSI_ERR_TRANS_CAPS - transport module did not support opera‐
tion.
15 ISCSI_ERR_SESS_EXISTS - session is logged in.
16 ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
17 ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
18 ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
19 ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
20 ISCSI_ERR_ISCSID_NOTCONN - could ont connect to iscsid.
21 ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals
found to execute operation on.
22 ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
23 ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
24 ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization
failure.
25 ISCSI_ERR_ISNS_QUERY - iSNS query failure.
26 ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration
failed.
EXAMPLES
Discover targets at a given IP address:
iscsiadm--mode discoverydb --type sendtargets --portal 192.168.1.10 --discover
Login, must use a node record id found by the discovery:
iscsiadm--mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --login
Logout:
iscsiadm--mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --logout
List node records:
iscsiadm--mode node
Display all data for a given node record:
iscsiadm--mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260
FILES
/etc/iscsi/iscsid.conf
The configuration file read by iscsid and iscsiadm on startup.
/etc/iscsi/initiatorname.iscsi
The file containing the iSCSI InitiatorName and InitiatorAlias
read by iscsid and iscsiadm on startup.
/var/lib/iscsi/nodes/
This directory contains the nodes with their targets.
/var/lib/iscsi/send_targets
This directory contains the portals.
SEE ALSOiscsid(8)AUTHORS
Open-iSCSI project <http://www.open-iscsi.org/>
Alex Aizman <itn780@yahoo.com>
Dmitry Yusupov <dmitry_yus@yahoo.com>
Sep 2006 ISCSIADM(8)
