=================================================================

                Linux* Open-iSCSI

=================================================================

                                                   Sep 29, 2016

Contents

========

- 1. In This Release

- 2. Introduction

- 3. Installation

- 4. Open-iSCSI daemon

- 5. Open-iSCSI Configuration Utility

- 6. Configuration

- 7. Getting Started

- 8. Advanced Configuration

- 9. iSCSI System Info

1. In This Release

==================

This file describes the Linux* Open-iSCSI Initiator. The software was

tested on AMD Opteron (TM) and Intel Xeon (TM).

The latest development release is available at:

	http://www.open-iscsi.com

For questions, comments, contributions send e-mail to:

	open-iscsi@googlegroups.com

1.1. Features

=============

- highly optimized and very small-footprint data path;

- persistent configuration database;

- SendTargets discovery;

- CHAP;

- PDU header Digest;

- multiple sessions;

2. Introduction

===============

The Open-iSCSI project is a high-performance, transport independent,

multi-platform implementation of RFC3720 iSCSI.

Open-iSCSI is partitioned into user and kernel parts.

The kernel portion of Open-iSCSI is a from-scratch code

licensed under GPL. The kernel part implements iSCSI data path

(that is, iSCSI Read and iSCSI Write), and consists of three

loadable modules: scsi_transport_iscsi.ko, libiscsi.ko and iscsi_tcp.ko.

User space contains the entire control plane: configuration

manager, iSCSI Discovery, Login and Logout processing,

connection-level error processing, Nop-In and Nop-Out handling,

and (in the future:) Text processing, iSNS, SLP, Radius, etc.

The user space Open-iSCSI consists of a daemon process called

iscsid, and a management utility iscsiadm.

3. Installation

===============

As of today, the Open-iSCSI Initiator requires a host running the

Linux operating system with kernel version 2.6.16 or later. 2.6.14 and

2.6.15 are partially supported. Known issues with 2.6.14 - .15 support:

- If the device is using a write back cache, during session logout

the cache sync command will fail.

- iscsiadm's -P 3 option will not print out scsi devices.

- iscsid will not automatically online devices.

The userspace components iscsid, iscsiadm and iscsistart require the

open-isns library, which can be found here:

	https://github.com/gonzoleeman/open-isns/releases

To install the open-isns headers and library required for open-iscsi, download

the current release and run:

	./configure

	make

	make install

	make install_hdrs

	make install_lib

By default the kernel's iSCSI modules will be used. Running:

	make

	make install

will install the iSCSI tools iscsiadm and iscsid to /sbin.

For 2.6.14 - 2.6.34 the modules in the kernel dir can be built and installed

by running:

	make kernel

When building those modules the kernel source found at

	/lib/modules/`uname -r`/build

will be used to compile the open-iscsi modules. To specify a different

kernel to build against, use:

	make kernel KSRC=<kernel-src>

or to use cross-compilation:

	make kernel KSRC=<kernel-src> KARCH="ARCH=um"

To compile on SUSE Linux you'll have to use

	make kernel KSRC=/usr/src/linux \

	     KBUILD_OUTPUT=/usr/src/linux-obj/<arch>/<config>

where <config> is the kernel configuration to use (eg. 'smp').

To install the kernel modules that were built, run:

	make install_kernel

This will copy iscsi_tcp.ko, libiscsi_tcp.ko, libiscsi.ko and

scsi_transport_iscsi.ko to

	/lib/modules/`uname -r`/kernel/drivers/scsi/

overwriting existing iscsi modules.

For Debian, be sure to install the linux-headers package that

corresponds to your kernel in order to compile the kernel modules

('aptitude install linux-headers-`uname -r`').  You may also wish to

run 'make -C kernel/ dpkg_divert' before installing kernel modules if

you run a Debian-provided kernel.  This will use dpkg-divert(8) to

move the packaged kernel modules out of the way, and ensure that

future kernel upgrades will not overwrite them.

Also, please be aware that the compatibility patches that enable these

iscsi modules to run on kernels older than 2.6.25 will not update the

ib_iser module; you may get warnings related to mismatched symbols on

this driver, in which case you'll be unable to load ib_iser and

open-iscsi simultaneously.

4. Open-iSCSI daemon

====================

The daemon implements 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 (see next section).

For help, run:

	iscsid --help

The output will be similar to the following.

Usage: iscsid [OPTION]

  -c, --config=[path]     Execute in the config file (/etc/iscsi/iscsid.conf).

  -f, --foreground        run iscsid in the foreground

  -d, --debug debuglevel  print debugging information

  -u, --uid=uid           run as uid, default is current user

  -g, --gid=gid           run as gid, default is current user group

  -h, --help              display this help and exit

  -v, --version           display version and exit

5. Open-iSCSI Configuration Utility

===================================

Open-iSCSI persistent configuration is stored in a number of

directories under a configuration root directory, using a flat-file

format. This configuration root directory is /var/lib/iscsi by default.

Configuration is contained in directories for:

- nodes

- slp

- isns

- static

- fw

- send_targets

- ifaces

The iscsiadm utility is a command-line tool to manage (update, delete,

insert, query) the persistent database.

The utility presents set of operations that a user can perform

on iSCSI nodes, sessions, connections, and discovery records.

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, so tools like iscsiadm

require that --targetname and --portal argument be used when in node mode.

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 is not currently persistent and is partially determined by

when the session is setup.

Note that some of the iSCSI Node and iSCSI Discovery operations

do not require iSCSI daemon (iscsid) loaded.

For help, run:

	iscsiadm --help

The output will be similar to the following.

iscsiadm -m discoverydb [ -hV ] [ -d debug_level ] [-P printlevel] [ -t type -p ip:port -I ifaceN ... [ -Dl ] ] | [ [ -p ip:port -t type] [ -o operation ] [ -n name ] [ -v value ] [ -lD ] ] 

iscsiadm -m discovery [ -hV ] [ -d debug_level ] [-P printlevel] [ -t type -p ip:port -I ifaceN ... [ -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 targetname -p ip:port -I ifaceN ] [ -l | -u | -R | -s] ] [ [ -o  operation  ] [ -n name ] [ -v value ] ]

iscsiadm -m session [ -hV ] [ -d debug_level ] [ -P  printlevel] [ -r sessionid | sysfsdir [ -R | -u | -s ] [ -o operation ] [ -n name ] [ -v value ] ]

iscsiadm -m iface [ -hV ] [ -d debug_level ] [ -P printlevel ] [ -I ifacename | -H hostno|MAC ] [ [ -o  operation  ] [ -n name ] [ -v value ] ] [ -C ping [ -a ip ] [ -b packetsize ] [ -c count ] [ -i interval ] ]

iscsiadm -m fw [ -d debug_level ] [ -l ]

iscsiadm -m host [ -P printlevel ] [ -H hostno|MAC ] [ [ -C chap [ -x chap_tbl_idx ] ] | [ -C flashnode [ -A portal_type ] [ -x flashnode_idx ] ] | [ -C stats ] ] [ [ -o operation ] [ -n name ] [ -v value ] ] 

iscsiadm -k priority

The first parameter specifies the mode to operate in:

  -m, --mode <op>	specify operational mode op =

			<discoverydb|discovery|node|session|iface|fw|host>

Mode "discoverydb"

------------------

  -m discoverydb --type=[type] --interface=[iface…] --portal=[ip:port] \

			--print=[N] \

			--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT] \

			--discover

			  This command will use the discovery record settings

			  matching the record with type=type and

			  portal=ip:port]. If a record does not exist, it will

			  create a record using the iscsid.conf discovery

			  settings.

			  By default, it will then remove records for

			  portals no longer returned. And,

			  if a portal is returned by the target, then the

			  discovery command will create a new record or modify

			  an existing one with values from iscsi.conf and the

			  command line.

			  [op] can be passed in multiple times to this

			  command, and it will alter the node DB manipulation.

			  If [op] is passed in and the value is

			  "new", iscsiadm will add records for portals that do

			  not yet have records in the db.

			  If [op] is passed in and the value is

			  "update", iscsiadm will update node records using

			  info from iscsi.conf and the command line for portals

			  that are returned during discovery and have

			  a record in the db.

			  If [op] is passed in and the value is "delete",

			  iscsiadm will delete records for portals that

			  were not returned during discovery.

			  If [op] is passed in and the value is

			  "nonpersistent", iscsiadm will not store

			  the portals found in the node DB. This is

			  only useful with the --login command.

			  See the example section for more info.

			  See below for how to setup iscsi ifaces for

			  software iscsi or override the system defaults.

			  Multiple ifaces can be passed in during discovery.

			  For the above commands, "print" is optional. If

			  used, N can be 0 or 1.

			  0 = The old flat style of output is used.

			  1 = The tree style with the inteface info is used.

			  If print is not used, the old flat style is used.

  -m discoverydb --interface=[iface...] --type=[type] --portal=[ip:port] \

			--print=[N] \

			--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT] \

			--discover --login

			  This works like the previous discoverydb command

			  with the --login argument passed in will also

			  log into the portals that are found.

  -m discoverydb --portal=[ip:port] --type=[type] \

			--op=[op] [--name=[name] --value=[value]]

			  Perform specific DB operation [op] for

			  discovery portal. It could be one of:

			  [new], [delete], [update] or [show]. In case of

			  [update], you have to provide [name] and [value]

			  you wish to update

			  op=NEW will create a new discovery record

			  using the iscsid.conf discovery settings. If it

			  already exists, it will be overwritten using

			  iscsid.conf discovery settings.

			  op=DELETE will delete the discovery record

			  and records for the targets found through

			  that discovery source.

			  op=SHOW will display the discovery record

			  values. The --show argument can be used to

			  force the CHAP passwords to be displayed.

Mode "discovery"

----------------

  -m discovery --type=[type] --interface=iscsi_ifacename \

			--portal=[ip:port] --login --print=[N] \

			--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT]

			  perform [type] discovery for target portal with

			  ip-address [ip] and port [port].

			  This command will not use the discovery record

			  settings. It will use the iscsid.conf discovery

			  settings and it will overwrite the discovery

			  record with iscsid.conf discovery settings if it

			  exists. By default, it will then remove records for

			  portals no longer returned. And,

			  if a portal is returned by the target, then the

			  discovery command will create a new record or modify

			  an existing one with values from iscsi.conf and the

			  command line.

			  [op] can be passed in multiple times to this

			  command, and it will alter the DB manipulation.

			  If [op] is passed in and the value is

			  "new", iscsiadm will add records for portals that do

			  not yet have records in the db.

			  If [op] is passed in and the value is

			  "update", iscsiadm will update node records using

			  info from iscsi.conf and the command line for portals

			  that are returned during discovery and have

			  a record in the db.

			  If [op] is passed in and the value is "delete",

			  iscsiadm will delete records for portals that

			  were not returned during discovery.

			  If [op] is passed in and the value is

			  "nonpersistent", iscsiadm will not store

			  the portals found in the node DB.

			  See the example section for more info.

			  See below for how to setup iscsi ifaces for

			  software iscsi or override the system defaults.

			  Multiple ifaces can be passed in during discovery.

  -m discovery --print=[N]

			  display all discovery records from internal

			  persistent discovery database.

Mode "node"

-----------

  -m node		  display all discovered nodes from internal

			  persistent discovery database

  -m node --targetname=[name] --portal=[ip:port] \

			--interface=iscsi_ifacename] \

			[--login|--logout|--rescan|--stats]

  -m node --targetname=[name] --portal=[ip:port]

			--interface=[driver,HWaddress] \

			--op=[op] [--name=[name] --value=[value]]

  -m node --targetname=[name] --portal=[ip:port]

			--interface=iscsi_ifacename] \

			--print=[level]

			  perform specific DB operation [op] for specific

			  interface on host that will connect to portal on

			  target. targetname, portal and interface are optional.

			  See below for how to setup iscsi ifaces for

			  software iscsi or override the system defaults.

			  op could be one of:

			  [new], [delete], [update] or [show]. In case of

			  [update], you have to provide [name] and [value]

			  you wish to update.

			  [delete] - Note that if a session is using the

			  node record, the session will be logged out then

			  the record will be deleted.

			  --rescan will perform a SCSI layer scan of the session

			  to find new LUNs.

			  --stats prints the iSCSI stats for the session.

			  Print level can be 0 to 1.

  -m node --logoutall=[all|manual|automatic]

			  Logout "all" the running sessions or just the ones

			  with a node startup value manual or automatic.

			  Nodes marked as ONBOOT are skipped.

  -m node --loginall=[all|manual|automatic]

			  Login "all" the running sessions or just the ones

			  with a node startup value manual or automatic.

			  Nodes marked as ONBOOT are skipped.

Mode "session"

--------------

  -m session		  display all active sessions and connections

  -m session --sid=[sid] [ --print=level | --rescan | --logout ]

			--op=[op] [--name=[name] --value=[value]]

			  perform operation for specific session with

			  session id sid. If no sid is given, the operation

			  will be performed on all running sessions if possible.

			  --logout and --op work like they do in node mode,

			  but in session mode targetname and portal info

			  is not passed in.

			  Print level can be 0 to 2.

			  1 = Print basic session info like node we are

			  connected to and whether we are connected.

			  2 = Print iscsi params used.

			  3 = Print SCSI info like LUNs, device state.

			  If no sid and no operation is given print out the

			  running sessions.

Mode "iface"

------------

  -m iface --interface=iscsi_ifacename --op=[op] [--name=[name] --value=[value]]

			--print=level

			  perform operation on given interface with name

			  iscsi_ifacename.

			  See below for examples.

  -m iface --interface=iscsi_ifacename -C ping --ip=[ipaddr] --packetsize=[size]

			--count=[count] --interval=[interval]

Mode "host"

-----------

  -m host [--host=hostno|MAC] --print=level -C chap --op=[SHOW]

			  Display information for a specific host. The host

			  can be passed in by host number or by MAC address.

			  If a host is not passed in, then info

			  for all hosts is printed.

			  Print level can be 0 to 4.

			  1 = Print info for how like its state, MAC, and

			  netinfo if possible.

			  2 = Print basic session info for nodes the host

			  is connected to.

			  3 = Print iscsi params used.

			  4 = Print SCSI info like LUNs, device state.

  -m host --host=hostno|MAC -C chap --op=[DELETE] --index=[chap_tbl_idx]

			  Delete chap entry at the given index from chap table.

  -m host --host=hostno|MAC -C chap --op=[NEW | UPDATE] --index=[chap_tbl_idx] \

			--name=[name] --value=[value]

			  Add new or update existing chap entry at the given

			  index with given username and password pair. If index

			  is not passed then entry is added at the first free

			  index in chap table.

  -m host --host=hostno|MAC -C flashnode

			  Display list of all the targets in adapter's

			  flash (flash node), for the specified host,

			  with ip, port, tpgt and iqn.

  -m host --host=hostno|MAC -C flashnode --op=[NEW] --portal_type=[ipv4|ipv6]

			  Create new flash node entry for the given host of the

			  specified portal_type. This returns the index of the

			  newly created entry on success.

  -m host --host=hostno|MAC -C flashnode --index=[flashnode_index] \

			--op=[UPDATE] --name=[name] --value=[value]

			  Update the params of the speficied flash node.

			  The [name] and [value] pairs must be provided for the

			  params that need to be updated. Multiple params can

			  be updated using a single command.

  -m host --host=hostno|MAC -C flashnode --index=[flashnode_index] \

			--op=[SHOW | DELETE | LOGIN | LOGOUT]

			  op=DELETE|LOGIN|LOGOUT will perform deletion/login/

			  logout operation on the specified flash node.

			  op=SHOW will list all params with the values for the

			  specified flash node. This is the default operation.

			  See the iscsiadm example section for more info.

Other arguments

---------------

  -d, --debug debuglevel  print debugging information

  -V, --version		  display version and exit

  -h, --help		  display this help and exit

5.1 iSCSI iface setup

=====================

The next sections describe how to setup iSCSI ifaces so you can bind

a session to a NIC port when using software iscsi (section 5.1.1), and

it describes how to setup ifaces for use with offload cards from Chelsio

and Broadcom (section 5.1.2).

5.1.1 How to setup iSCSI interfaces (iface) for binding

=======================================================

If you wish to allow the network susbsystem to figure out

the best path/NIC to use, then you can skip this section. For example

if you have setup your portals and NICs on different subnets, then

the following is not needed for software iscsi.

Warning!!!!!!

This feature is experimental. The interface may change. When reporting

bugs, if you cannot do a "ping -I ethX target_portal", then check your

network settings first. Make sure the rp_filter setting is set to 0 or 2

(see Prep section below for more info). If you cannot ping the portal,

then you will not be able to bind a session to a NIC.

What is a scsi_host and iface for software, hardware and partial

offload iscsi?

Software iscsi, like iscsi_tcp and iser, allocates a scsi_host per session

and does a single connection per session. As a result

/sys/class_scsi_host and /proc/scsi will report a scsi_host for

each connection/session you have logged into. Offload iscsi, like

Chelsio cxgb3i, allocates a scsi_host for each PCI device (each

port on a HBA will show up as a different PCI device so you get

a scsi_host per HBA port).

To manage both types of initiator stacks, iscsiadm uses the interface (iface)

structure. For each HBA port or for software iscsi for each network

device (ethX) or NIC, that you wish to bind sessions to you must create

a iface config /var/lib/iscsi/ifaces.

Prep

----

The iface binding feature requires the sysctl setting

net.ipv4.conf.default.rp_filter to be set to 0 or 2.

This can be set in /etc/sysctl.conf by having the line:

	net.ipv4.conf.default.rp_filter = N

where N is 0 or 2. Note that when setting this you may have to reboot

for the value to take effect.

rp_filter information from Documentation/networking/ip-sysctl.txt:

rp_filter - INTEGER

	0 - No source validation.

	1 - Strict mode as defined in RFC3704 Strict Reverse Path

	    Each incoming packet is tested against the FIB and if the interface

	    is not the best reverse path the packet check will fail.

	    By default failed packets are discarded.

	2 - Loose mode as defined in RFC3704 Loose Reverse Path

	    Each incoming packet's source address is also tested against the FIB

	    and if the source address is not reachable via any interface

	    the packet check will fail.

Running

-------

The command

	iscsiadm -m iface

will report iface configurations that are setup in /var/lib/iscsi/ifaces:

	iface0 qla4xxx,00:c0:dd:08:63:e8,20.15.0.7,default,iqn.2005-06.com.redhat:madmax

	iface1 qla4xxx,00:c0:dd:08:63:ea,20.15.0.9,default,iqn.2005-06.com.redhat:madmax

The format is:

	iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname

For software iscsi, you can create the iface configs by hand, but it is

recommended that you use iscsiadm's iface mode. There is an iface.example in

/var/lib/iscsi/ifaces which can be used as a template for the daring.

For each network object you wish to bind a session to, you must create

a separate iface config in /var/lib/iscsi/ifaces and each iface config file

must have a unique name which is less than or equal to 64 characters.

Example

-------

If you have NIC1 with MAC address 00:0F:1F:92:6B:BF and NIC2 with

MAC address 00:C0:DD:08:63:E7, and you wanted to do software iscsi over

TCP/IP, then in /var/lib/iscsi/ifaces/iface0 you would enter:

	iface.transport_name = tcp

	iface.hwaddress = 00:0F:1F:92:6B:BF

and in /var/lib/iscsi/ifaces/iface1 you would enter:

	iface.transport_name = tcp

	iface.hwaddress = 00:C0:DD:08:63:E7

Warning: Do not name an iface config file  "default" or "iser".

They are special values/files that are used by the iscsi tools for

backward compatibility. If you name an iface default or iser, then

the behavior is not defined.

To use iscsiadm to create an iface0 similar to the above example, run:

	iscsiadm -m iface -I iface0 --op=new

(This will create a new empty iface config. If there was already an iface

with the name "iface0", this command will overwrite it.)

Next, set the hwaddress:

	iscsiadm -m iface -I iface0 --op=update \

		-n iface.hwaddress -v 00:0F:1F:92:6B:BF

If you had sessions logged in, iscsiadm will not update or overwrite

an iface. You must log out first. If you have an iface bound to a node/portal

but you have not logged in, then iscsiadm will update the config and

all existing bindings.

You should now skip to 5.1.3 to see how to log in using the iface, and for

some helpful management commands.

5.1.2 Setting up an iface for an iSCSI offload card

===================================================

This section describes how to setup ifaces for use with Chelsio, Broadcom and

QLogic cards.

By default, iscsiadm will create an iface for each Broadcom, QLogic and Chelsio

port. The iface name will be of the form:

	$transport/driver_name.$MAC_ADDRESS

Running the following command:

	iscsiadm -m iface

will report iface configurations that are setup in /var/lib/iscsi/ifaces:

	default tcp,<empty>,<empty>,<empty>,<empty>

	iser iser,<empty>,<empty>,<empty>,<empty>

	cxgb3i.00:07:43:05:97:07 cxgb3i,00:07:43:05:97:07,<empty>,<empty>,<empty>

	qla4xxx.00:0e:1e:04:8b:2e qla4xxx,00:0e:1e:04:8b:2e,<empty>,<empty>,<empty>

The format is:

	iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname

iface_name:		name of iface

transport_name:		name of driver

hwaddress:		MAC address

ipaddress:		IP address to use for this port

net_iface_name:		will be <empty> because change between reboots.

			It is used for software iSCSI's vlan or alias binding.

initiatorname:		Initiatorname to be used if you want to override the

			default one in /etc/iscsi/initiatorname.iscsi.

To display these values in a more friendly way, run:

	iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07

Example output:

	# BEGIN RECORD 2.0-871

	iface.iscsi_ifacename = cxgb3i.00:07:43:05:97:07

	iface.net_ifacename = <empty>

	iface.ipaddress = <empty>

	iface.hwaddress = 00:07:43:05:97:07

	iface.transport_name = cxgb3i

	iface.initiatorname = <empty>

	# END RECORD

Before you can use the iface, you must set the IP address for the port.

We determine the corresponding variable name that we want to update from

the output above, which is "iface.ipaddress".

Then we fill this empty variable with the value we desire, with this command:

	iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07 -o update \

		-n iface.ipaddress -v 20.15.0.66

Note for QLogic ports: After updating the iface record, you must apply or

applyall the settings for the changes to take effect:

	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2e -o apply

	iscsiadm -m iface -H 00:0e:1e:04:8b:2e -o applyall

With "apply", the network settings for the specified iface will take effect.

With "applyall", the network settings for all ifaces on a specific host will

take effect. The host can be specified using the -H/--host argument by either

the MAC address of the host or the host number.

Here is an example of setting multiple IPv6 addresses on a single iSCSI

interface port.

First interface (no need to set iface_num, it is 0 by default):

	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \

		 -n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9392

Create the second interface if it does not exist (iface_num is mandatory here):

	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a.1 -op=new

	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \

		 -n iface.iface_num -v 1

	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \

		 -n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9393

	iscsiadm -m iface -H 00:0e:1e:04:8b:2a --op=applyall

Note: If there are common settings for multiple interfaces then the

settings from 0th iface would be considered valid.

Now, we can use this iface to login into targets, which is described in the

next section.

5.1.3 Discoverying iSCSI targets/portals

========================================

Be aware that iscsiadm will use the default route to do discovery. It will

not use the iface specified. So if you are using an offload card, you will

need a separate network connection to the target for discovery purposes.

*This will be fixed in the next version of open-iscsi*

For compatibility reasons, when you run iscsiadm to do discovery, it

will check for interfaces in /var/lib/iscsi/iscsi/ifaces that are using

tcp for the iface.transport, and it will bind the portals that are discovered

so that they will be logged in through those ifaces. This behavior can also

be overridden by passing in the interfaces you want to use. For the case

of offload, like with cxgb3i and bnx2i, this is required because the transport

will not be tcp.

For example if you had defined two interfaces but only wanted to use one,

you can use the --interface/-I argument:

	iscsiadm -m discoverydb -t st -p ip:port -I iface1 --discover -P 1

If you had defined interfaces but wanted the old behavior, where we do not

bind a session to an iface, then you can use the special iface "default":

	iscsiadm -m discoverydb -t st -p ip:port -I default --discover -P 1

And if you did not define any interfaces in /var/lib/iscsi/ifaces and do

not pass anything into iscsiadm, running iscsiadm will do the default

behavior, allowing the network subsystem to decide which device to use.

If you later want to remove the bindings for a specific target and

iface, then you can run:

	iscsiadm -m node -T my_target -I iface0 --op=delete

To do this for a specific portal on a target, run:

	iscsiadm -m node -T my_target -p ip:port -I iface0 --op=delete

If you wanted to delete all bindinds for iface0, then you can run:

	iscsiadm -m node -I iface0 --op=delete

And for equalogic targets it is sometimes useful to remove just by portal:

	iscsiadm -m node -p ip:port -I iface0 --op=delete

Now logging into targets is the same as with software iscsi. See section 7

for how to get started.

5.2 iscsiadm examples

=====================

Usage examples using the one-letter options (see iscsiadm man page

for long options):

Discovery mode

--------------

- SendTargets iSCSI Discovery using the default driver and interface and

		using the discovery settings for the discovery record with the

		ID [192.168.1.1:3260]:

	iscsiadm -m discoverydb -t st -p 192.168.1.1:3260 --discover

	This will search /var/lib/iscsi/send_targets for a record with the

	ID [portal = 192.168.1.1:3260 and type = sendtargets. If found it

	will perform discovery using the settings stored in the record.

	If a record does not exist, it will be created using the iscsid.conf

	discovery settings.

	The argument to -p may also be a hostname instead of an address:

		iscsiadm -m discoverydb -t st -p somehost --discover

	For the ifaces, iscsiadm will first search /var/lib/iscsi/ifaces for

	interfaces using software iscsi. If any are found then nodes found

	during discovery will be setup so that they can logged in through

	those interfaces. To specify a specific iface, pass the

	-I argument for each iface.

- SendTargets iSCSI Discovery updating existing target records:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		-o update --discover

	If there is a record for targetX, and portalY exists in the DB, and

	is returned during discovery, it will be updated with the info from

	the iscsi.conf. No new portals will be added and stale portals

	will not be removed.

- SendTargets iSCSI Discovery deleting existing target records:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		-o delete --discover

	If there is a record for targetX, and portalY exists in the DB, but

	is not returned during discovery, it will be removed from the DB.

	No new portals will be added and existing portal records will not

	be changed.

	Note: If a session is logged into portal we are going to delete

	a record for, it will be logged out then the record will be

	deleted.

- SendTargets iSCSI Discovery adding new records:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		-o new --discover

	If there is targetX, and portalY is returned during discovery, and does

	not have a record, it will be added. Existing records are not modified.

- SendTargets iSCSI Discovery using multiple ops:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		-o new -o delete --discover

	This command will add new portals and delete records for portals

	no longer returned. It will not change the record information for

	existing portals.

- SendTargets iSCSI Discovery in nonpersistent mode:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		-o nonpersistent --discover

	This command will perform discovery, but not manipulate the node DB.

- SendTargets iSCSI Discovery with a specific interface.

		If you wish to only use a subset of the interfaces in

		/var/lib/iscsi/ifaces, then you can pass them in during discovery:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		--interface=iface0 --interface=iface1 --discover

	Note that for software iscsi, we let the network layer select

	which NIC to use for discovery, but for later logins iscsiadm

	will use the NIC defined in the iface config.

	qla4xxx support is very basic and experimental. It does not store

	the record info in the card's FLASH or the node DB, so you must

	rerun discovery every time the driver is reloaded.

- Manipulate SendTargets DB: Create new SendTargets discovery record or

		overwrite an existing discovery record with iscsid.conf

		discovery settings:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o new

- Manipulate SendTargets DB: Display discovery settings:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o show

- Manipulate SendTargets DB: Display hidden discovery settings like

		 CHAP passwords:

	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \

		-o show --show