.TH ISCSIADM 8 "Sep 2006" "" "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 ]

[\

.BI \-I\  iface\  \-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 ]

[\

.BI \-I\  iface\  \-t\  type\  \-p\  ip:port

.RB [ \-l ]

] | [

.RB [ \-p

.IR ip:port ]

.RB [ \-l | \-D ]

]

.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 [ \-U

.IR all,manual,automatic,onboot ]

.RB [ \-S ]

[

.RB [ \-T

.IB targetname\  \-p\  ip:port\  \-I\  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 ]

[

.B \-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 ]

[

.BI \-I\  ifacename

|

.BI \-H\  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 ]

.PP

.B iscsiadm

.B \-m host

.RB [ \-P

.IR printlevel ]

.RB [ \-H

.IR hostno|MAC ]

[

.RB [\  \-C

.IR chap

.RB [ \-x

.IR chap_tbl_idx ]

] |

.RB [\  \-C

.IR 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 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.

.PP

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\-a\fR, \fB\-\-ip=\fIipaddr\fP

\fIipaddr\fR can be IPv4 or IPv6.

.IP

This option is only valid for ping 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 flashnode submode of host 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 ping submode.

.TP

\fB\-c\fR, \fB\-\-count=\fIcount\fP

\fIcount\fR specify number of ping iterations.

.IP

This option is only valid for ping submode.

.TP

\fB\-C\fR, \fB\-\-submode=\fIop\fP

Specify the submode for mode. op must be name of submode.

.IP

Currently iscsiadm support ping as submode for iface. For example:

.IP

iscsiadm \-m iface \-I ifacename \-C ping \-a ipaddr \-b packetsize \-c count \-i interval

.IP

For host, it supports chap , flashnode and stats 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 debug_level 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 host 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 specify delay between two ping iterations.

.IP

This option is only valid for ping submode.

.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 /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.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

.IP

The available drivers/iscsi_transports are tcp (software iSCSI over TCP/IP),

iser (software iSCSI over InfiniBand), 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 InfiniBand layer

to decide what to do. There is no need to create an iface config with the default

behavior. If you do not specify an iface, then the default behavior is used.

.IP

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.

.IP

In discovery mode multiple interfaces can be specified by passing in multiple

\-I/\-\-interface instances. For example:

.IP

"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 intefaces passed in.

.IP

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 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 \fIdiscoverydb\fR mode to instruct iscsiadm to perform

discovery.

.IP

This option is only valid for SendTargets discovery mode.

.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|onboot]\fR

For node mode, login all sessions with the node or conn startup values passed

in or all running session, 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, \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, 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 /var/lib/iscsi/ifaces are displayed.

.TP

\fB\-n\fR, \fB\-\-name=\fIname\fR

In node mode, specify a field \fIname\fR in a record. In flashnode submode

of host 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 iface mode, \fIapply\fR and \fIapplyall\fR  are also applicable.

.IP

For flashnode submode of host mode, \fIlogin\fR and \fIlogout\fR are also applicable.

.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 object. In node mode, the

\fIrecid\fR is the target name and portal (IP:port). In iface mode, the \fIrecid\fR

is the iface name. In discovery mode, the \fIrecid\fR is the portal and

discovery type.

.IP

In session mode, the \fInew\fR operation logs in a new session using

the same node database and iface information as the specified session.

.IP

In discovery mode, if the \fIrecid\fR and new operation is passed in,

but the \fI--discover\fR argument is not, 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

\fIdelete\fR deletes a specified \fIrecid\fR. In discovery mode, if

iscsiadm is performing discovery it 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 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 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.

.IP

\fInonpersistent\fR instructs iscsiadm to not manipulate the node DB.

.IP

\fIapply\fR will cause the network settings to take effect on the specified iface.

.IP

\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

\fIlogin\fR will log into the specified flash node entry.

.IP

\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 \fIport\fR. If port is not passed

in the default \fIport\fR value is 3260.

.IP

IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or

ddd.ddd.ddd.ddd.

.IP

Hostnames can also be used for the ip argument.

.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.

.IP

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.

.IP

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.

This option when used with host 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 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|onboot]\fR

logout all sessions with the node or conn startup values passed in or all

running session, 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 and flashnode submode of host 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 chap and flashnode submodes of host mode.

.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, pass the address and

optionally the port of the iSNS server to do discovery to.

.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.

.IP

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".

.IP

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 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 exired 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 timedout.

.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.

.SH EXAMPLES

Discover targets at a given IP address:

.IP

iscsiadm \-\-mode discoverydb \-\-type sendtargets \-\-portal 192.168.1.10 \-\-discover

.PP

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

.IP

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

.PP

Logout:

.IP

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

.PP

List node records:

.IP

iscsiadm \-\-mode node

.PP

Display all data for a given node record:

.IP

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

/var/lib/iscsi/nodes/

This directory contains the nodes with their targets.

.TP

/var/lib/iscsi/send_targets

This directory contains the portals.

.SH "SEE ALSO"

.BR iscsid (8)

.SH AUTHORS

Open-iSCSI project <http://www.open-iscsi.com/>

.br

Alex Aizman <itn780@yahoo.com>

.br

Dmitry Yusupov <dmitry_yus@yahoo.com>