Blame README

Packit eace71
=================================================================
Packit eace71
Packit eace71
                Linux* Open-iSCSI
Packit eace71
Packit eace71
=================================================================
Packit eace71
Packit eace71
                                                   Sep 29, 2016
Packit eace71
Contents
Packit eace71
========
Packit eace71
Packit eace71
- 1. In This Release
Packit eace71
- 2. Introduction
Packit eace71
- 3. Installation
Packit eace71
- 4. Open-iSCSI daemon
Packit eace71
- 5. Open-iSCSI Configuration Utility
Packit eace71
- 6. Configuration
Packit eace71
- 7. Getting Started
Packit eace71
- 8. Advanced Configuration
Packit eace71
- 9. iSCSI System Info
Packit eace71
Packit eace71
Packit eace71
1. In This Release
Packit eace71
==================
Packit eace71
Packit eace71
This file describes the Linux* Open-iSCSI Initiator. The software was
Packit eace71
tested on AMD Opteron (TM) and Intel Xeon (TM).
Packit eace71
Packit eace71
The latest development release is available at:
Packit eace71
	http://www.open-iscsi.com
Packit eace71
Packit eace71
For questions, comments, contributions send e-mail to:
Packit eace71
	open-iscsi@googlegroups.com
Packit eace71
Packit eace71
Packit eace71
1.1. Features
Packit eace71
=============
Packit eace71
Packit eace71
- highly optimized and very small-footprint data path;
Packit eace71
- persistent configuration database;
Packit eace71
- SendTargets discovery;
Packit eace71
- CHAP;
Packit eace71
- PDU header Digest;
Packit eace71
- multiple sessions;
Packit eace71
Packit eace71
Packit eace71
2. Introduction
Packit eace71
===============
Packit eace71
Packit eace71
The Open-iSCSI project is a high-performance, transport independent,
Packit eace71
multi-platform implementation of RFC3720 iSCSI.
Packit eace71
Packit eace71
Open-iSCSI is partitioned into user and kernel parts.
Packit eace71
Packit eace71
The kernel portion of Open-iSCSI is a from-scratch code
Packit eace71
licensed under GPL. The kernel part implements iSCSI data path
Packit eace71
(that is, iSCSI Read and iSCSI Write), and consists of three
Packit eace71
loadable modules: scsi_transport_iscsi.ko, libiscsi.ko and iscsi_tcp.ko.
Packit eace71
Packit eace71
User space contains the entire control plane: configuration
Packit eace71
manager, iSCSI Discovery, Login and Logout processing,
Packit eace71
connection-level error processing, Nop-In and Nop-Out handling,
Packit eace71
and (in the future:) Text processing, iSNS, SLP, Radius, etc.
Packit eace71
Packit eace71
The user space Open-iSCSI consists of a daemon process called
Packit eace71
iscsid, and a management utility iscsiadm.
Packit eace71
Packit eace71
Packit eace71
3. Installation
Packit eace71
===============
Packit eace71
Packit eace71
As of today, the Open-iSCSI Initiator requires a host running the
Packit eace71
Linux operating system with kernel version 2.6.16 or later. 2.6.14 and
Packit eace71
2.6.15 are partially supported. Known issues with 2.6.14 - .15 support:
Packit eace71
Packit eace71
- If the device is using a write back cache, during session logout
Packit eace71
the cache sync command will fail.
Packit eace71
- iscsiadm's -P 3 option will not print out scsi devices.
Packit eace71
- iscsid will not automatically online devices.
Packit eace71
Packit eace71
The userspace components iscsid, iscsiadm and iscsistart require the
Packit eace71
open-isns library, which can be found here:
Packit eace71
	https://github.com/gonzoleeman/open-isns/releases
Packit eace71
Packit eace71
To install the open-isns headers and library required for open-iscsi, download
Packit eace71
the current release and run:
Packit eace71
Packit eace71
	./configure
Packit eace71
	make
Packit eace71
	make install
Packit eace71
	make install_hdrs
Packit eace71
	make install_lib
Packit eace71
Packit eace71
By default the kernel's iSCSI modules will be used. Running:
Packit eace71
Packit eace71
	make
Packit eace71
	make install
Packit eace71
Packit eace71
will install the iSCSI tools iscsiadm and iscsid to /sbin.
Packit eace71
Packit eace71
For 2.6.14 - 2.6.34 the modules in the kernel dir can be built and installed
Packit eace71
by running:
Packit eace71
Packit eace71
	make kernel
Packit eace71
Packit eace71
When building those modules the kernel source found at
Packit eace71
	/lib/modules/`uname -r`/build
Packit eace71
Packit eace71
will be used to compile the open-iscsi modules. To specify a different
Packit eace71
kernel to build against, use:
Packit eace71
	make kernel KSRC=<kernel-src>
Packit eace71
Packit eace71
or to use cross-compilation:
Packit eace71
	make kernel KSRC=<kernel-src> KARCH="ARCH=um"
Packit eace71
Packit eace71
To compile on SUSE Linux you'll have to use
Packit eace71
Packit eace71
	make kernel KSRC=/usr/src/linux \
Packit eace71
	     KBUILD_OUTPUT=/usr/src/linux-obj/<arch>/<config>
Packit eace71
Packit eace71
where <config> is the kernel configuration to use (eg. 'smp').
Packit eace71
Packit eace71
To install the kernel modules that were built, run:
Packit eace71
Packit eace71
	make install_kernel
Packit eace71
Packit eace71
This will copy iscsi_tcp.ko, libiscsi_tcp.ko, libiscsi.ko and
Packit eace71
scsi_transport_iscsi.ko to
Packit eace71
	/lib/modules/`uname -r`/kernel/drivers/scsi/
Packit eace71
overwriting existing iscsi modules.
Packit eace71
Packit eace71
For Debian, be sure to install the linux-headers package that
Packit eace71
corresponds to your kernel in order to compile the kernel modules
Packit eace71
('aptitude install linux-headers-`uname -r`').  You may also wish to
Packit eace71
run 'make -C kernel/ dpkg_divert' before installing kernel modules if
Packit eace71
you run a Debian-provided kernel.  This will use dpkg-divert(8) to
Packit eace71
move the packaged kernel modules out of the way, and ensure that
Packit eace71
future kernel upgrades will not overwrite them.
Packit eace71
Packit eace71
Also, please be aware that the compatibility patches that enable these
Packit eace71
iscsi modules to run on kernels older than 2.6.25 will not update the
Packit eace71
ib_iser module; you may get warnings related to mismatched symbols on
Packit eace71
this driver, in which case you'll be unable to load ib_iser and
Packit eace71
open-iscsi simultaneously.
Packit eace71
Packit eace71
Packit eace71
4. Open-iSCSI daemon
Packit eace71
====================
Packit eace71
Packit eace71
The daemon implements control path of iSCSI protocol, plus some management
Packit eace71
facilities. For example, the daemon could be configured to automatically
Packit eace71
re-start discovery at startup, based on the contents of persistent
Packit eace71
iSCSI database (see next section).
Packit eace71
Packit eace71
For help, run:
Packit eace71
	iscsid --help
Packit eace71
Packit eace71
The output will be similar to the following.
Packit eace71
Packit eace71
Usage: iscsid [OPTION]
Packit eace71
Packit eace71
  -c, --config=[path]     Execute in the config file (/etc/iscsi/iscsid.conf).
Packit eace71
  -f, --foreground        run iscsid in the foreground
Packit eace71
  -d, --debug debuglevel  print debugging information
Packit eace71
  -u, --uid=uid           run as uid, default is current user
Packit eace71
  -g, --gid=gid           run as gid, default is current user group
Packit eace71
  -h, --help              display this help and exit
Packit eace71
  -v, --version           display version and exit
Packit eace71
Packit eace71
Packit eace71
5. Open-iSCSI Configuration Utility
Packit eace71
===================================
Packit eace71
Packit eace71
Open-iSCSI persistent configuration is stored in a number of
Packit eace71
directories under a configuration root directory, using a flat-file
Packit Service 15966b
format. This configuration root directory is /var/lib/iscsi by default.
Packit eace71
Packit eace71
Configuration is contained in directories for:
Packit eace71
Packit eace71
- nodes
Packit eace71
- slp
Packit eace71
- isns
Packit eace71
- static
Packit eace71
- fw
Packit eace71
- send_targets
Packit eace71
- ifaces
Packit eace71
Packit eace71
The iscsiadm utility is a command-line tool to manage (update, delete,
Packit eace71
insert, query) the persistent database.
Packit eace71
Packit eace71
The utility presents set of operations that a user can perform
Packit eace71
on iSCSI nodes, sessions, connections, and discovery records.
Packit eace71
Packit eace71
Open-iSCSI does not use the term node as defined by the iSCSI RFC,
Packit eace71
where a node is a single iSCSI initiator or target. Open-iSCSI uses the
Packit eace71
term node to refer to a portal on a target, so tools like iscsiadm
Packit eace71
require that --targetname and --portal argument be used when in node mode.
Packit eace71
Packit eace71
For session mode, a session id (sid) is used. The sid of a session can be
Packit eace71
found by running
Packit eace71
	iscsiadm -m session -P 1
Packit eace71
Packit eace71
The session id is not currently persistent and is partially determined by
Packit eace71
when the session is setup.
Packit eace71
Packit eace71
Note that some of the iSCSI Node and iSCSI Discovery operations
Packit eace71
do not require iSCSI daemon (iscsid) loaded.
Packit eace71
Packit eace71
For help, run:
Packit eace71
	iscsiadm --help
Packit eace71
Packit eace71
The output will be similar to the following.
Packit eace71
Packit eace71
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 ] ] 
Packit eace71
iscsiadm -m discovery [ -hV ] [ -d debug_level ] [-P printlevel] [ -t type -p ip:port -I ifaceN ... [ -l ] ] | [ [ -p ip:port ] [ -l | -D ] ] 
Packit eace71
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 ] ]
Packit eace71
iscsiadm -m session [ -hV ] [ -d debug_level ] [ -P  printlevel] [ -r sessionid | sysfsdir [ -R | -u | -s ] [ -o operation ] [ -n name ] [ -v value ] ]
Packit eace71
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 ] ]
Packit eace71
iscsiadm -m fw [ -d debug_level ] [ -l ]
Packit eace71
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 ] ] 
Packit eace71
iscsiadm -k priority
Packit eace71
Packit eace71
Packit eace71
The first parameter specifies the mode to operate in:
Packit eace71
  -m, --mode <op>	specify operational mode op =
Packit eace71
			<discoverydb|discovery|node|session|iface|fw|host>
Packit eace71
Packit eace71
Mode "discoverydb"
Packit eace71
------------------
Packit eace71
Packit eace71
  -m discoverydb --type=[type] --interface=[ifaceā€¦] --portal=[ip:port] \
Packit eace71
			--print=[N] \
Packit eace71
			--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT] \
Packit eace71
			--discover
Packit eace71
Packit eace71
			  This command will use the discovery record settings
Packit eace71
			  matching the record with type=type and
Packit eace71
			  portal=ip:port]. If a record does not exist, it will
Packit eace71
			  create a record using the iscsid.conf discovery
Packit eace71
			  settings.
Packit eace71
Packit eace71
			  By default, it will then remove records for
Packit eace71
			  portals no longer returned. And,
Packit eace71
			  if a portal is returned by the target, then the
Packit eace71
			  discovery command will create a new record or modify
Packit eace71
			  an existing one with values from iscsi.conf and the
Packit eace71
			  command line.
Packit eace71
Packit eace71
			  [op] can be passed in multiple times to this
Packit eace71
			  command, and it will alter the node DB manipulation.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is
Packit eace71
			  "new", iscsiadm will add records for portals that do
Packit eace71
			  not yet have records in the db.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is
Packit eace71
			  "update", iscsiadm will update node records using
Packit eace71
			  info from iscsi.conf and the command line for portals
Packit eace71
			  that are returned during discovery and have
Packit eace71
			  a record in the db.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is "delete",
Packit eace71
			  iscsiadm will delete records for portals that
Packit eace71
			  were not returned during discovery.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is
Packit eace71
			  "nonpersistent", iscsiadm will not store
Packit eace71
			  the portals found in the node DB. This is
Packit eace71
			  only useful with the --login command.
Packit eace71
Packit eace71
			  See the example section for more info.
Packit eace71
Packit eace71
			  See below for how to setup iscsi ifaces for
Packit eace71
			  software iscsi or override the system defaults.
Packit eace71
Packit eace71
			  Multiple ifaces can be passed in during discovery.
Packit eace71
Packit eace71
			  For the above commands, "print" is optional. If
Packit eace71
			  used, N can be 0 or 1.
Packit eace71
			  0 = The old flat style of output is used.
Packit eace71
			  1 = The tree style with the inteface info is used.
Packit eace71
Packit eace71
			  If print is not used, the old flat style is used.
Packit eace71
Packit eace71
  -m discoverydb --interface=[iface...] --type=[type] --portal=[ip:port] \
Packit eace71
			--print=[N] \
Packit eace71
			--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT] \
Packit eace71
			--discover --login
Packit eace71
Packit eace71
			  This works like the previous discoverydb command
Packit eace71
			  with the --login argument passed in will also
Packit eace71
			  log into the portals that are found.
Packit eace71
Packit eace71
  -m discoverydb --portal=[ip:port] --type=[type] \
Packit eace71
			--op=[op] [--name=[name] --value=[value]]
Packit eace71
Packit eace71
			  Perform specific DB operation [op] for
Packit eace71
			  discovery portal. It could be one of:
Packit eace71
			  [new], [delete], [update] or [show]. In case of
Packit eace71
			  [update], you have to provide [name] and [value]
Packit eace71
			  you wish to update
Packit eace71
Packit eace71
			  op=NEW will create a new discovery record
Packit eace71
			  using the iscsid.conf discovery settings. If it
Packit eace71
			  already exists, it will be overwritten using
Packit eace71
			  iscsid.conf discovery settings.
Packit eace71
Packit eace71
			  op=DELETE will delete the discovery record
Packit eace71
			  and records for the targets found through
Packit eace71
			  that discovery source.
Packit eace71
Packit eace71
			  op=SHOW will display the discovery record
Packit eace71
			  values. The --show argument can be used to
Packit eace71
			  force the CHAP passwords to be displayed.
Packit eace71
Packit eace71
Mode "discovery"
Packit eace71
----------------
Packit eace71
Packit eace71
  -m discovery --type=[type] --interface=iscsi_ifacename \
Packit eace71
			--portal=[ip:port] --login --print=[N] \
Packit eace71
			--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT]
Packit eace71
Packit eace71
			  perform [type] discovery for target portal with
Packit eace71
			  ip-address [ip] and port [port].
Packit eace71
Packit eace71
			  This command will not use the discovery record
Packit eace71
			  settings. It will use the iscsid.conf discovery
Packit eace71
			  settings and it will overwrite the discovery
Packit eace71
			  record with iscsid.conf discovery settings if it
Packit eace71
			  exists. By default, it will then remove records for
Packit eace71
			  portals no longer returned. And,
Packit eace71
			  if a portal is returned by the target, then the
Packit eace71
			  discovery command will create a new record or modify
Packit eace71
			  an existing one with values from iscsi.conf and the
Packit eace71
			  command line.
Packit eace71
Packit eace71
			  [op] can be passed in multiple times to this
Packit eace71
			  command, and it will alter the DB manipulation.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is
Packit eace71
			  "new", iscsiadm will add records for portals that do
Packit eace71
			  not yet have records in the db.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is
Packit eace71
			  "update", iscsiadm will update node records using
Packit eace71
			  info from iscsi.conf and the command line for portals
Packit eace71
			  that are returned during discovery and have
Packit eace71
			  a record in the db.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is "delete",
Packit eace71
			  iscsiadm will delete records for portals that
Packit eace71
			  were not returned during discovery.
Packit eace71
Packit eace71
			  If [op] is passed in and the value is
Packit eace71
			  "nonpersistent", iscsiadm will not store
Packit eace71
			  the portals found in the node DB.
Packit eace71
Packit eace71
			  See the example section for more info.
Packit eace71
Packit eace71
			  See below for how to setup iscsi ifaces for
Packit eace71
			  software iscsi or override the system defaults.
Packit eace71
Packit eace71
			  Multiple ifaces can be passed in during discovery.
Packit eace71
Packit eace71
  -m discovery --print=[N]
Packit eace71
Packit eace71
			  display all discovery records from internal
Packit eace71
			  persistent discovery database.
Packit eace71
Packit eace71
Mode "node"
Packit eace71
-----------
Packit eace71
Packit eace71
  -m node		  display all discovered nodes from internal
Packit eace71
			  persistent discovery database
Packit eace71
Packit eace71
  -m node --targetname=[name] --portal=[ip:port] \
Packit eace71
			--interface=iscsi_ifacename] \
Packit eace71
			[--login|--logout|--rescan|--stats]
Packit eace71
  -m node --targetname=[name] --portal=[ip:port]
Packit eace71
			--interface=[driver,HWaddress] \
Packit eace71
			--op=[op] [--name=[name] --value=[value]]
Packit eace71
  -m node --targetname=[name] --portal=[ip:port]
Packit eace71
			--interface=iscsi_ifacename] \
Packit eace71
			--print=[level]
Packit eace71
Packit eace71
			  perform specific DB operation [op] for specific
Packit eace71
			  interface on host that will connect to portal on
Packit eace71
			  target. targetname, portal and interface are optional.
Packit eace71
			  See below for how to setup iscsi ifaces for
Packit eace71
			  software iscsi or override the system defaults.
Packit eace71
Packit eace71
			  op could be one of:
Packit eace71
			  [new], [delete], [update] or [show]. In case of
Packit eace71
			  [update], you have to provide [name] and [value]
Packit eace71
			  you wish to update.
Packit eace71
			  [delete] - Note that if a session is using the
Packit eace71
			  node record, the session will be logged out then
Packit eace71
			  the record will be deleted.
Packit eace71
Packit eace71
			  --rescan will perform a SCSI layer scan of the session
Packit eace71
			  to find new LUNs.
Packit eace71
Packit eace71
			  --stats prints the iSCSI stats for the session.
Packit eace71
Packit eace71
			  Print level can be 0 to 1.
Packit eace71
Packit eace71
  -m node --logoutall=[all|manual|automatic]
Packit eace71
			  Logout "all" the running sessions or just the ones
Packit eace71
			  with a node startup value manual or automatic.
Packit eace71
			  Nodes marked as ONBOOT are skipped.
Packit eace71
Packit eace71
  -m node --loginall=[all|manual|automatic]
Packit eace71
			  Login "all" the running sessions or just the ones
Packit eace71
			  with a node startup value manual or automatic.
Packit eace71
			  Nodes marked as ONBOOT are skipped.
Packit eace71
Packit eace71
Mode "session"
Packit eace71
--------------
Packit eace71
Packit eace71
  -m session		  display all active sessions and connections
Packit eace71
Packit eace71
  -m session --sid=[sid] [ --print=level | --rescan | --logout ]
Packit eace71
			--op=[op] [--name=[name] --value=[value]]
Packit eace71
Packit eace71
			  perform operation for specific session with
Packit eace71
			  session id sid. If no sid is given, the operation
Packit eace71
			  will be performed on all running sessions if possible.
Packit eace71
			  --logout and --op work like they do in node mode,
Packit eace71
			  but in session mode targetname and portal info
Packit eace71
			  is not passed in.
Packit eace71
Packit eace71
			  Print level can be 0 to 2.
Packit eace71
			  1 = Print basic session info like node we are
Packit eace71
			  connected to and whether we are connected.
Packit eace71
			  2 = Print iscsi params used.
Packit eace71
			  3 = Print SCSI info like LUNs, device state.
Packit eace71
Packit eace71
			  If no sid and no operation is given print out the
Packit eace71
			  running sessions.
Packit eace71
Packit eace71
Mode "iface"
Packit eace71
------------
Packit eace71
Packit eace71
  -m iface --interface=iscsi_ifacename --op=[op] [--name=[name] --value=[value]]
Packit eace71
			--print=level
Packit eace71
Packit eace71
			  perform operation on given interface with name
Packit eace71
			  iscsi_ifacename.
Packit eace71
Packit eace71
			  See below for examples.
Packit eace71
Packit eace71
  -m iface --interface=iscsi_ifacename -C ping --ip=[ipaddr] --packetsize=[size]
Packit eace71
			--count=[count] --interval=[interval]
Packit eace71
Packit eace71
Mode "host"
Packit eace71
-----------
Packit eace71
Packit eace71
  -m host [--host=hostno|MAC] --print=level -C chap --op=[SHOW]
Packit eace71
Packit eace71
			  Display information for a specific host. The host
Packit eace71
			  can be passed in by host number or by MAC address.
Packit eace71
			  If a host is not passed in, then info
Packit eace71
			  for all hosts is printed.
Packit eace71
Packit eace71
			  Print level can be 0 to 4.
Packit eace71
			  1 = Print info for how like its state, MAC, and
Packit eace71
			  netinfo if possible.
Packit eace71
			  2 = Print basic session info for nodes the host
Packit eace71
			  is connected to.
Packit eace71
			  3 = Print iscsi params used.
Packit eace71
			  4 = Print SCSI info like LUNs, device state.
Packit eace71
Packit eace71
  -m host --host=hostno|MAC -C chap --op=[DELETE] --index=[chap_tbl_idx]
Packit eace71
Packit eace71
			  Delete chap entry at the given index from chap table.
Packit eace71
Packit eace71
  -m host --host=hostno|MAC -C chap --op=[NEW | UPDATE] --index=[chap_tbl_idx] \
Packit eace71
			--name=[name] --value=[value]
Packit eace71
Packit eace71
			  Add new or update existing chap entry at the given
Packit eace71
			  index with given username and password pair. If index
Packit eace71
			  is not passed then entry is added at the first free
Packit eace71
			  index in chap table.
Packit eace71
Packit eace71
  -m host --host=hostno|MAC -C flashnode
Packit eace71
Packit eace71
			  Display list of all the targets in adapter's
Packit eace71
			  flash (flash node), for the specified host,
Packit eace71
			  with ip, port, tpgt and iqn.
Packit eace71
Packit eace71
  -m host --host=hostno|MAC -C flashnode --op=[NEW] --portal_type=[ipv4|ipv6]
Packit eace71
Packit eace71
			  Create new flash node entry for the given host of the
Packit eace71
			  specified portal_type. This returns the index of the
Packit eace71
			  newly created entry on success.
Packit eace71
Packit eace71
  -m host --host=hostno|MAC -C flashnode --index=[flashnode_index] \
Packit eace71
			--op=[UPDATE] --name=[name] --value=[value]
Packit eace71
Packit eace71
			  Update the params of the speficied flash node.
Packit eace71
			  The [name] and [value] pairs must be provided for the
Packit eace71
			  params that need to be updated. Multiple params can
Packit eace71
			  be updated using a single command.
Packit eace71
Packit eace71
  -m host --host=hostno|MAC -C flashnode --index=[flashnode_index] \
Packit eace71
			--op=[SHOW | DELETE | LOGIN | LOGOUT]
Packit eace71
Packit eace71
			  op=DELETE|LOGIN|LOGOUT will perform deletion/login/
Packit eace71
			  logout operation on the specified flash node.
Packit eace71
Packit eace71
			  op=SHOW will list all params with the values for the
Packit eace71
			  specified flash node. This is the default operation.
Packit eace71
Packit eace71
			  See the iscsiadm example section for more info.
Packit eace71
Packit eace71
Other arguments
Packit eace71
---------------
Packit eace71
Packit eace71
  -d, --debug debuglevel  print debugging information
Packit eace71
Packit eace71
  -V, --version		  display version and exit
Packit eace71
Packit eace71
  -h, --help		  display this help and exit
Packit eace71
Packit eace71
Packit eace71
5.1 iSCSI iface setup
Packit eace71
=====================
Packit eace71
Packit eace71
The next sections describe how to setup iSCSI ifaces so you can bind
Packit eace71
a session to a NIC port when using software iscsi (section 5.1.1), and
Packit eace71
it describes how to setup ifaces for use with offload cards from Chelsio
Packit eace71
and Broadcom (section 5.1.2).
Packit eace71
Packit eace71
Packit eace71
5.1.1 How to setup iSCSI interfaces (iface) for binding
Packit eace71
=======================================================
Packit eace71
Packit eace71
If you wish to allow the network susbsystem to figure out
Packit eace71
the best path/NIC to use, then you can skip this section. For example
Packit eace71
if you have setup your portals and NICs on different subnets, then
Packit eace71
the following is not needed for software iscsi.
Packit eace71
Packit eace71
Warning!!!!!!
Packit eace71
This feature is experimental. The interface may change. When reporting
Packit eace71
bugs, if you cannot do a "ping -I ethX target_portal", then check your
Packit eace71
network settings first. Make sure the rp_filter setting is set to 0 or 2
Packit eace71
(see Prep section below for more info). If you cannot ping the portal,
Packit eace71
then you will not be able to bind a session to a NIC.
Packit eace71
Packit eace71
What is a scsi_host and iface for software, hardware and partial
Packit eace71
offload iscsi?
Packit eace71
Packit eace71
Software iscsi, like iscsi_tcp and iser, allocates a scsi_host per session
Packit eace71
and does a single connection per session. As a result
Packit eace71
/sys/class_scsi_host and /proc/scsi will report a scsi_host for
Packit eace71
each connection/session you have logged into. Offload iscsi, like
Packit eace71
Chelsio cxgb3i, allocates a scsi_host for each PCI device (each
Packit eace71
port on a HBA will show up as a different PCI device so you get
Packit eace71
a scsi_host per HBA port).
Packit eace71
Packit eace71
To manage both types of initiator stacks, iscsiadm uses the interface (iface)
Packit eace71
structure. For each HBA port or for software iscsi for each network
Packit eace71
device (ethX) or NIC, that you wish to bind sessions to you must create
Packit Service 15966b
a iface config /var/lib/iscsi/ifaces.
Packit eace71
Packit eace71
Prep
Packit eace71
----
Packit eace71
Packit eace71
The iface binding feature requires the sysctl setting
Packit eace71
net.ipv4.conf.default.rp_filter to be set to 0 or 2.
Packit eace71
This can be set in /etc/sysctl.conf by having the line:
Packit eace71
	net.ipv4.conf.default.rp_filter = N
Packit eace71
Packit eace71
where N is 0 or 2. Note that when setting this you may have to reboot
Packit eace71
for the value to take effect.
Packit eace71
Packit eace71
Packit eace71
rp_filter information from Documentation/networking/ip-sysctl.txt:
Packit eace71
Packit eace71
rp_filter - INTEGER
Packit eace71
	0 - No source validation.
Packit eace71
	1 - Strict mode as defined in RFC3704 Strict Reverse Path
Packit eace71
	    Each incoming packet is tested against the FIB and if the interface
Packit eace71
	    is not the best reverse path the packet check will fail.
Packit eace71
	    By default failed packets are discarded.
Packit eace71
	2 - Loose mode as defined in RFC3704 Loose Reverse Path
Packit eace71
	    Each incoming packet's source address is also tested against the FIB
Packit eace71
	    and if the source address is not reachable via any interface
Packit eace71
	    the packet check will fail.
Packit eace71
Packit eace71
Running
Packit eace71
-------
Packit eace71
Packit eace71
The command
Packit eace71
	iscsiadm -m iface
Packit eace71
Packit Service 15966b
will report iface configurations that are setup in /var/lib/iscsi/ifaces:
Packit eace71
Packit eace71
	iface0 qla4xxx,00:c0:dd:08:63:e8,20.15.0.7,default,iqn.2005-06.com.redhat:madmax
Packit eace71
	iface1 qla4xxx,00:c0:dd:08:63:ea,20.15.0.9,default,iqn.2005-06.com.redhat:madmax
Packit eace71
Packit eace71
The format is:
Packit eace71
	iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname
Packit eace71
Packit eace71
For software iscsi, you can create the iface configs by hand, but it is
Packit eace71
recommended that you use iscsiadm's iface mode. There is an iface.example in
Packit Service 15966b
/var/lib/iscsi/ifaces which can be used as a template for the daring.
Packit eace71
Packit eace71
For each network object you wish to bind a session to, you must create
Packit Service 15966b
a separate iface config in /var/lib/iscsi/ifaces and each iface config file
Packit eace71
must have a unique name which is less than or equal to 64 characters.
Packit eace71
Packit eace71
Example
Packit eace71
-------
Packit eace71
Packit eace71
If you have NIC1 with MAC address 00:0F:1F:92:6B:BF and NIC2 with
Packit eace71
MAC address 00:C0:DD:08:63:E7, and you wanted to do software iscsi over
Packit Service 15966b
TCP/IP, then in /var/lib/iscsi/ifaces/iface0 you would enter:
Packit eace71
Packit eace71
	iface.transport_name = tcp
Packit eace71
	iface.hwaddress = 00:0F:1F:92:6B:BF
Packit eace71
Packit Service 15966b
and in /var/lib/iscsi/ifaces/iface1 you would enter:
Packit eace71
Packit eace71
	iface.transport_name = tcp
Packit eace71
	iface.hwaddress = 00:C0:DD:08:63:E7
Packit eace71
Packit eace71
Warning: Do not name an iface config file  "default" or "iser".
Packit eace71
They are special values/files that are used by the iscsi tools for
Packit eace71
backward compatibility. If you name an iface default or iser, then
Packit eace71
the behavior is not defined.
Packit eace71
Packit eace71
To use iscsiadm to create an iface0 similar to the above example, run:
Packit eace71
	iscsiadm -m iface -I iface0 --op=new
Packit eace71
Packit eace71
(This will create a new empty iface config. If there was already an iface
Packit eace71
with the name "iface0", this command will overwrite it.)
Packit eace71
Packit eace71
Next, set the hwaddress:
Packit eace71
	iscsiadm -m iface -I iface0 --op=update \
Packit eace71
		-n iface.hwaddress -v 00:0F:1F:92:6B:BF
Packit eace71
Packit eace71
If you had sessions logged in, iscsiadm will not update or overwrite
Packit eace71
an iface. You must log out first. If you have an iface bound to a node/portal
Packit eace71
but you have not logged in, then iscsiadm will update the config and
Packit eace71
all existing bindings.
Packit eace71
Packit eace71
You should now skip to 5.1.3 to see how to log in using the iface, and for
Packit eace71
some helpful management commands.
Packit eace71
Packit eace71
Packit eace71
5.1.2 Setting up an iface for an iSCSI offload card
Packit eace71
===================================================
Packit eace71
Packit eace71
This section describes how to setup ifaces for use with Chelsio, Broadcom and
Packit eace71
QLogic cards.
Packit eace71
Packit eace71
By default, iscsiadm will create an iface for each Broadcom, QLogic and Chelsio
Packit eace71
port. The iface name will be of the form:
Packit eace71
	$transport/driver_name.$MAC_ADDRESS
Packit eace71
Packit eace71
Running the following command:
Packit eace71
	iscsiadm -m iface
Packit eace71
Packit Service 15966b
will report iface configurations that are setup in /var/lib/iscsi/ifaces:
Packit eace71
Packit eace71
	default tcp,<empty>,<empty>,<empty>,<empty>
Packit eace71
	iser iser,<empty>,<empty>,<empty>,<empty>
Packit eace71
	cxgb3i.00:07:43:05:97:07 cxgb3i,00:07:43:05:97:07,<empty>,<empty>,<empty>
Packit eace71
	qla4xxx.00:0e:1e:04:8b:2e qla4xxx,00:0e:1e:04:8b:2e,<empty>,<empty>,<empty>
Packit eace71
Packit eace71
The format is:
Packit eace71
	iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname
Packit eace71
Packit eace71
iface_name:		name of iface
Packit eace71
transport_name:		name of driver
Packit eace71
hwaddress:		MAC address
Packit eace71
ipaddress:		IP address to use for this port
Packit eace71
net_iface_name:		will be <empty> because change between reboots.
Packit eace71
			It is used for software iSCSI's vlan or alias binding.
Packit eace71
initiatorname:		Initiatorname to be used if you want to override the
Packit eace71
			default one in /etc/iscsi/initiatorname.iscsi.
Packit eace71
Packit eace71
To display these values in a more friendly way, run:
Packit eace71
	iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07
Packit eace71
Packit eace71
Example output:
Packit eace71
	# BEGIN RECORD 2.0-871
Packit eace71
	iface.iscsi_ifacename = cxgb3i.00:07:43:05:97:07
Packit eace71
	iface.net_ifacename = <empty>
Packit eace71
	iface.ipaddress = <empty>
Packit eace71
	iface.hwaddress = 00:07:43:05:97:07
Packit eace71
	iface.transport_name = cxgb3i
Packit eace71
	iface.initiatorname = <empty>
Packit eace71
	# END RECORD
Packit eace71
Packit eace71
Before you can use the iface, you must set the IP address for the port.
Packit eace71
We determine the corresponding variable name that we want to update from
Packit eace71
the output above, which is "iface.ipaddress".
Packit eace71
Then we fill this empty variable with the value we desire, with this command:
Packit eace71
	iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07 -o update \
Packit eace71
		-n iface.ipaddress -v 20.15.0.66
Packit eace71
Packit eace71
Note for QLogic ports: After updating the iface record, you must apply or
Packit eace71
applyall the settings for the changes to take effect:
Packit eace71
Packit eace71
	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2e -o apply
Packit eace71
	iscsiadm -m iface -H 00:0e:1e:04:8b:2e -o applyall
Packit eace71
Packit eace71
With "apply", the network settings for the specified iface will take effect.
Packit eace71
With "applyall", the network settings for all ifaces on a specific host will
Packit eace71
take effect. The host can be specified using the -H/--host argument by either
Packit eace71
the MAC address of the host or the host number.
Packit eace71
Packit eace71
Here is an example of setting multiple IPv6 addresses on a single iSCSI
Packit eace71
interface port.
Packit eace71
First interface (no need to set iface_num, it is 0 by default):
Packit eace71
	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
Packit eace71
		 -n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9392
Packit eace71
Packit eace71
Create the second interface if it does not exist (iface_num is mandatory here):
Packit eace71
	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a.1 -op=new
Packit eace71
	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
Packit eace71
		 -n iface.iface_num -v 1
Packit eace71
	iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
Packit eace71
		 -n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9393
Packit eace71
	iscsiadm -m iface -H 00:0e:1e:04:8b:2a --op=applyall
Packit eace71
Packit eace71
Note: If there are common settings for multiple interfaces then the
Packit eace71
settings from 0th iface would be considered valid.
Packit eace71
Packit eace71
Now, we can use this iface to login into targets, which is described in the
Packit eace71
next section.
Packit eace71
Packit eace71
Packit eace71
5.1.3 Discoverying iSCSI targets/portals
Packit eace71
========================================
Packit eace71
Packit eace71
Be aware that iscsiadm will use the default route to do discovery. It will
Packit eace71
not use the iface specified. So if you are using an offload card, you will
Packit eace71
need a separate network connection to the target for discovery purposes.
Packit eace71
*This will be fixed in the next version of open-iscsi*
Packit eace71
Packit eace71
For compatibility reasons, when you run iscsiadm to do discovery, it
Packit Service 15966b
will check for interfaces in /var/lib/iscsi/iscsi/ifaces that are using
Packit eace71
tcp for the iface.transport, and it will bind the portals that are discovered
Packit eace71
so that they will be logged in through those ifaces. This behavior can also
Packit eace71
be overridden by passing in the interfaces you want to use. For the case
Packit eace71
of offload, like with cxgb3i and bnx2i, this is required because the transport
Packit eace71
will not be tcp.
Packit eace71
Packit eace71
For example if you had defined two interfaces but only wanted to use one,
Packit eace71
you can use the --interface/-I argument:
Packit eace71
	iscsiadm -m discoverydb -t st -p ip:port -I iface1 --discover -P 1
Packit eace71
Packit eace71
If you had defined interfaces but wanted the old behavior, where we do not
Packit eace71
bind a session to an iface, then you can use the special iface "default":
Packit eace71
	iscsiadm -m discoverydb -t st -p ip:port -I default --discover -P 1
Packit eace71
Packit Service 15966b
And if you did not define any interfaces in /var/lib/iscsi/ifaces and do
Packit eace71
not pass anything into iscsiadm, running iscsiadm will do the default
Packit eace71
behavior, allowing the network subsystem to decide which device to use.
Packit eace71
Packit eace71
If you later want to remove the bindings for a specific target and
Packit eace71
iface, then you can run:
Packit eace71
	iscsiadm -m node -T my_target -I iface0 --op=delete
Packit eace71
Packit eace71
To do this for a specific portal on a target, run:
Packit eace71
	iscsiadm -m node -T my_target -p ip:port -I iface0 --op=delete
Packit eace71
Packit eace71
If you wanted to delete all bindinds for iface0, then you can run:
Packit eace71
	iscsiadm -m node -I iface0 --op=delete
Packit eace71
Packit eace71
And for equalogic targets it is sometimes useful to remove just by portal:
Packit eace71
	iscsiadm -m node -p ip:port -I iface0 --op=delete
Packit eace71
Packit eace71
Packit eace71
Now logging into targets is the same as with software iscsi. See section 7
Packit eace71
for how to get started.
Packit eace71
Packit eace71
Packit eace71
5.2 iscsiadm examples
Packit eace71
=====================
Packit eace71
Packit eace71
Usage examples using the one-letter options (see iscsiadm man page
Packit eace71
for long options):
Packit eace71
Packit eace71
Discovery mode
Packit eace71
--------------
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery using the default driver and interface and
Packit eace71
		using the discovery settings for the discovery record with the
Packit eace71
		ID [192.168.1.1:3260]:
Packit eace71
	iscsiadm -m discoverydb -t st -p 192.168.1.1:3260 --discover
Packit eace71
Packit Service 15966b
	This will search /var/lib/iscsi/send_targets for a record with the
Packit eace71
	ID [portal = 192.168.1.1:3260 and type = sendtargets. If found it
Packit eace71
	will perform discovery using the settings stored in the record.
Packit eace71
	If a record does not exist, it will be created using the iscsid.conf
Packit eace71
	discovery settings.
Packit eace71
Packit eace71
	The argument to -p may also be a hostname instead of an address:
Packit eace71
		iscsiadm -m discoverydb -t st -p somehost --discover
Packit eace71
Packit Service 15966b
	For the ifaces, iscsiadm will first search /var/lib/iscsi/ifaces for
Packit eace71
	interfaces using software iscsi. If any are found then nodes found
Packit eace71
	during discovery will be setup so that they can logged in through
Packit eace71
	those interfaces. To specify a specific iface, pass the
Packit eace71
	-I argument for each iface.
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery updating existing target records:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o update --discover
Packit eace71
Packit eace71
	If there is a record for targetX, and portalY exists in the DB, and
Packit eace71
	is returned during discovery, it will be updated with the info from
Packit eace71
	the iscsi.conf. No new portals will be added and stale portals
Packit eace71
	will not be removed.
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery deleting existing target records:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o delete --discover
Packit eace71
Packit eace71
	If there is a record for targetX, and portalY exists in the DB, but
Packit eace71
	is not returned during discovery, it will be removed from the DB.
Packit eace71
	No new portals will be added and existing portal records will not
Packit eace71
	be changed.
Packit eace71
Packit eace71
	Note: If a session is logged into portal we are going to delete
Packit eace71
	a record for, it will be logged out then the record will be
Packit eace71
	deleted.
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery adding new records:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o new --discover
Packit eace71
Packit eace71
	If there is targetX, and portalY is returned during discovery, and does
Packit eace71
	not have a record, it will be added. Existing records are not modified.
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery using multiple ops:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o new -o delete --discover
Packit eace71
Packit eace71
	This command will add new portals and delete records for portals
Packit eace71
	no longer returned. It will not change the record information for
Packit eace71
	existing portals.
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery in nonpersistent mode:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o nonpersistent --discover
Packit eace71
Packit eace71
	This command will perform discovery, but not manipulate the node DB.
Packit eace71
Packit eace71
- SendTargets iSCSI Discovery with a specific interface.
Packit eace71
		If you wish to only use a subset of the interfaces in
Packit Service 15966b
		/var/lib/iscsi/ifaces, then you can pass them in during discovery:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		--interface=iface0 --interface=iface1 --discover
Packit eace71
Packit eace71
Packit eace71
	Note that for software iscsi, we let the network layer select
Packit eace71
	which NIC to use for discovery, but for later logins iscsiadm
Packit eace71
	will use the NIC defined in the iface config.
Packit eace71
Packit eace71
	qla4xxx support is very basic and experimental. It does not store
Packit eace71
	the record info in the card's FLASH or the node DB, so you must
Packit eace71
	rerun discovery every time the driver is reloaded.
Packit eace71
Packit eace71
- Manipulate SendTargets DB: Create new SendTargets discovery record or
Packit eace71
		overwrite an existing discovery record with iscsid.conf
Packit eace71
		discovery settings:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o new
Packit eace71
Packit eace71
- Manipulate SendTargets DB: Display discovery settings:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o show
Packit eace71
Packit eace71
- Manipulate SendTargets DB: Display hidden discovery settings like
Packit eace71
		 CHAP passwords:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o show --show
Packit eace71
Packit eace71
- Manipulate SendTargets DB: Set discovery setting.
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
Packit eace71
		-o update -n name -v value
Packit eace71
Packit eace71
- Manipulate SendTargets DB: Delete discovery record. This will also delete
Packit eace71
		the records for the targets found through the discovery source.
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o delete
Packit eace71
Packit eace71
- Show all records in discovery database:
Packit eace71
	iscsiadm -m discovery
Packit eace71
Packit eace71
- Show all records in discovery database and show the targets that were
Packit eace71
		discovered from each record:
Packit eace71
	iscsiadm -m discovery -P 1
Packit eace71
Packit eace71
Node mode
Packit eace71
---------
Packit eace71
Packit eace71
In node mode you can specify which records you want to log
Packit eace71
into by specifying the targetname, ip address, port or interface
Packit eace71
(if specifying the interface it must already be setup in the node db).
Packit eace71
iscsiadm will search the node db for records which match the values
Packit eace71
you pass in, so if you pass in the targetname and interface, iscsiadm
Packit eace71
will search for records with those values and operate on only them.
Packit eace71
Passing in none of them will result in all node records being operated on.
Packit eace71
Packit eace71
- iSCSI Login to all portals on every node/starget through each interface
Packit eace71
		set in the db:
Packit eace71
	iscsiadm -m node -l
Packit eace71
Packit eace71
- iSCSI login to all portals on a node/target through each interface set
Packit eace71
		in the db:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -l
Packit eace71
Packit eace71
- iSCSI login to a specific portal through each interface set in the db:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 -l
Packit eace71
Packit eace71
	To specify an iPv6 address, the following can be used:
Packit eace71
		iscsiadm -m node -T iqn.2005-03.com.max \
Packit eace71
			-p 2001:c90::211:9ff:feb8:a9e9 -l
Packit eace71
Packit eace71
	The above command would use the default port, 3260. To specify a
Packit eace71
	port, use the following:
Packit eace71
		iscsiadm -m node -T iqn.2005-03.com.max \
Packit eace71
			-p [2001:c90::211:9ff:feb8:a9e9]:3260 -l
Packit eace71
Packit eace71
	To specify a hostname, the following can be used:
Packit eace71
		iscsiadm -m node -T iqn.2005-03.com.max -p somehost -l
Packit eace71
Packit eace71
- iSCSI Login to a specific portal through the NIC setup as iface0:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 \
Packit eace71
		-I iface0  -l
Packit eace71
Packit eace71
- iSCSI Logout of all portals on every node/starget through each interface
Packit eace71
		set in the db:
Packit eace71
	iscsiadm -m node -u
Packit eace71
Packit eace71
	Warning: this does not check startup values like the logout/login all
Packit eace71
	option. Do not use this if you are running iscsi on your root disk.
Packit eace71
Packit eace71
- iSCSI logout of all portals on a node/target through each interface set
Packit eace71
		in the db:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -u
Packit eace71
Packit eace71
- iSCSI logout of a specific portal through each interface set in the db:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 -u
Packit eace71
Packit eace71
- iSCSI Logout of a specific portal through the NIC setup as iface0:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 \
Packit eace71
		-I iface0
Packit eace71
Packit eace71
- Changing iSCSI parameter:
Packit eace71
	iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 \
Packit eace71
		-o update -n node.cnx[0].iscsi.MaxRecvDataSegmentLength -v 65536
Packit eace71
Packit eace71
	You can also change parameters for multiple records at once, by
Packit eace71
	specifying different combinations of target, portal and interface
Packit eace71
	like above.
Packit eace71
Packit eace71
- Adding custom iSCSI portal:
Packit eace71
	iscsiadm -m node -o new -T iqn.2005-03.com.max \
Packit eace71
		-p 192.168.0.1:3260,2 -I iface4
Packit eace71
Packit eace71
	The -I/--interface is optional. If not passed in, "default" is used.
Packit eace71
	For tcp or iser, this would allow the network layer to decide what is
Packit eace71
	best.
Packit eace71
Packit eace71
	Note that for this command, the Target Portal Group Tag (TPGT) should
Packit eace71
	be passed in. If it is not passed in on the initial creation command,
Packit eace71
	then the user must run iscsiadm again to set the value. Also,
Packit eace71
	if the TPGT is not initially passed in, the old behavior of not
Packit eace71
	tracking whether the record was statically or dynamically created
Packit eace71
	is used.
Packit eace71
Packit eace71
- Adding custom NIC config to multiple targets:
Packit eace71
	iscsiadm -m node -o new -I iface4
Packit eace71
Packit eace71
	This command will add an interface config using the iSCSI and SCSI
Packit eace71
	settings from iscsid.conf to every target that is in the node db.
Packit eace71
Packit eace71
- Removing iSCSI portal:
Packit eace71
	iscsiadm -m node -o delete -T iqn.2005-03.com.max -p 192.168.0.4:3260
Packit eace71
Packit eace71
	You can also delete multiple records at once, by specifying different
Packit eace71
	combinations of target, portal and interface like above.
Packit eace71
Packit eace71
- Display iSCSI portal onfiguration:
Packit eace71
	iscsiadm -m node [-o show] -T iqn.2005-03.com.max -p 192.168.0.4:3260
Packit eace71
Packit eace71
	You can also display multiple records at once, by specifying different
Packit eace71
	combinations of target, portal and interface like above.
Packit eace71
Packit eace71
	Note: running "iscsiadm -m node" will only display the records. It
Packit eace71
	will not display the configuration info. For the latter, run:
Packit eace71
		iscsiadm -m node -o show
Packit eace71
Packit eace71
- Show all node records:
Packit eace71
	iscsiadm -m node
Packit eace71
Packit eace71
	This will print the nodes using the old flat format where the
Packit eace71
	interface and driver are not displayed. To display that info
Packit eace71
	use the -P option with the argument "1":
Packit eace71
		iscsiadm -m node -P 1
Packit eace71
Packit eace71
Session mode
Packit eace71
------------
Packit eace71
Packit eace71
- Display session statistics:
Packit eace71
	iscsiadm -m session -r 1 --stats
Packit eace71
Packit eace71
	This function also works in node mode. Instead of the "-r $sid"
Packit eace71
	argument, you would pass in the node info like targetname and/or portal,
Packit eace71
	and/or interface.
Packit eace71
Packit eace71
- Perform a SCSI scan on a session
Packit eace71
	iscsiadm -m session -r 1 --rescan
Packit eace71
Packit eace71
	This function also works in node mode. Instead of the "-r $sid"
Packit eace71
	argument, you would pass in the node info like targetname and/or portal,
Packit eace71
	and/or interface.
Packit eace71
Packit eace71
	Note: Rescanning does not delete old LUNs. It will only pick up new
Packit eace71
	ones.
Packit eace71
Packit eace71
- Display running sessions:
Packit eace71
	iscsiadm -m session -P 1
Packit eace71
Packit eace71
Host mode with flashnode submode
Packit eace71
--------------------------------
Packit eace71
Packit eace71
- Display list of flash nodes for a host
Packit eace71
	iscsiadm -m host -H 6 -C flashnode
Packit eace71
Packit eace71
	This will print list of all the flash node entries for the given host
Packit eace71
	along with their ip, port, tpgt and iqn values.
Packit eace71
Packit eace71
- Display all parameters of a flash node entry for a host
Packit eace71
	iscsiadm -m host -H 6 -C flashnode -x 0
Packit eace71
Packit eace71
	This will list all the parameter name,value pairs for the
Packit eace71
	flash node entry at index 0 of host 6.
Packit eace71
Packit eace71
- Add a new flash node entry for a host
Packit eace71
	iscsiadm -m host -H 6 -C flashnode -o new -A [ipv4|ipv6]
Packit eace71
Packit eace71
	This will add new flash node entry for the given host 6 with portal
Packit eace71
	type of either ipv4 or ipv6. The new operation returns the index of
Packit eace71
	the newly created flash node entry.
Packit eace71
Packit eace71
- Update a flashnode entry
Packit eace71
	iscsiadm -m host -H 6 -C flashnode -x 1 -o update \
Packit eace71
		-n flashnode.conn[0].ipaddress -v 192.168.1.12 \
Packit eace71
		-n flashnode.session.targetname \
Packit eace71
		-v iqn.2002-03.com.compellent:5000d310004b0716
Packit eace71
Packit eace71
	This will update the values of ipaddress and targetname params of
Packit eace71
	the flash node entry at index 1 of host 6.
Packit eace71
Packit eace71
- Login to a flash node entry
Packit eace71
	iscsiadm -m host -H 6 -C flashnode -x 1 -o login
Packit eace71
Packit eace71
- Logout from a flash node entry
Packit eace71
	Logout can be performed either using the flash node index:
Packit eace71
		iscsiadm -m host -H 6 -C flashnode -x 1 -o logout
Packit eace71
Packit eace71
	or by using the corresponding session index:
Packit eace71
		iscsiadm -m session -r $sid -u
Packit eace71
Packit eace71
- Delete a flash node entry
Packit eace71
	iscsiadm -m host -H 6 -C flashnode -x 1 -o delete
Packit eace71
Packit eace71
Host mode with chap submode
Packit eace71
---------------------------
Packit eace71
Packit eace71
- Display list of chap entries for a host
Packit eace71
	iscsiadm -m host -H 6 -C chap -o show
Packit eace71
Packit eace71
- Delete a chap entry for a host
Packit eace71
	iscsiadm -m host -H 6 -C chap -o delete -x 5
Packit eace71
Packit eace71
	This will delete any chap entry present at index 5.
Packit eace71
Packit eace71
- Add/Update a local chap entry for a host
Packit eace71
	iscsiadm -m host -H 6 -C chap -o update -x 4 -n username \
Packit eace71
			-v value -n password -v value
Packit eace71
Packit eace71
	This will update the local chap entry present at index 4. If index 4
Packit eace71
	is free, then a new entry of type local chap will be created at that
Packit eace71
	index with given username and password values.
Packit eace71
Packit eace71
- Add/Update a bidi chap entry for a host
Packit eace71
	iscsiadm -m host -H 6 -C chap -o update -x 5 -n username_in \
Packit eace71
		-v value -n password_in -v value
Packit eace71
Packit eace71
	This will update the bidi chap entry present at index 5. If index 5
Packit eace71
	is free then entry of type bidi chap will be created at that index
Packit eace71
	with given username_in and password_in values.
Packit eace71
Packit eace71
Host mode with stats submode
Packit eace71
----------------------------
Packit eace71
Packit eace71
- Display host statistics:
Packit eace71
	iscsiadm -m host -H 6 -C stats
Packit eace71
Packit eace71
	This will print the aggregate statistics on the host adapter port.
Packit eace71
	This includes MAC, TCP/IP, ECC & iSCSI statistics.
Packit eace71
Packit eace71
Packit eace71
6. Configuration
Packit eace71
================
Packit eace71
Packit eace71
The default configuration file is /etc/iscsi/iscsid.conf. This file contains
Packit eace71
only configuration that could be overwritten by iSCSI Discovery,
Packit eace71
or manualy updated via iscsiadm utility. Its OK if this file does not
Packit eace71
exist, in which case compiled-in default configuration will take place
Packit eace71
for newer discovered Target nodes.
Packit eace71
Packit eace71
See the man page and the example file for the current syntax.
Packit eace71
The manpages for iscsid, iscsiadm are in the doc subdirectory and can be
Packit eace71
installed in the appropriate man page directories and need to be manually
Packit eace71
copied into e.g. /usr/local/share/man8.
Packit eace71
Packit eace71
Packit eace71
7. Getting Started
Packit eace71
==================
Packit eace71
Packit eace71
There are three steps needed to set up a system to use iSCSI storage:
Packit eace71
7.1. iSCSI startup using the init script or manual startup.
Packit eace71
7.2. Discover targets.
Packit eace71
7.3. Automate target logins for future system reboots.
Packit eace71
Packit eace71
The init scripts will start the iSCSI daemon and log into any
Packit eace71
portals that are set up for automatic login (discussed in 7.2)
Packit eace71
or discovered through the discover daemon iscsid.conf params
Packit eace71
(discussed in 7.1.2).
Packit eace71
Packit eace71
If your distro does not have an init script, then you will have to start the
Packit eace71
daemon and log into the targets manually.
Packit eace71
Packit eace71
Packit eace71
7.1.1 iSCSI startup using the init script
Packit eace71
=========================================
Packit eace71
Packit eace71
Red Hat or Fedora:
Packit eace71
-----------------
Packit eace71
To start open-iscsi in Red Hat/Fedora you can do:
Packit eace71
Packit Service 539fda
	service iscsi start
Packit eace71
Packit eace71
To get open-iscsi to automatically start at run time you may have to
Packit eace71
run:
Packit eace71
	chkconfig --level <levels> open-iscsi on
Packit eace71
Where <levels> are the run levels.
Packit eace71
Packit eace71
And, to automatically mount a file system during startup
Packit eace71
you must have the partition entry in /etc/fstab marked with the "_netdev"
Packit eace71
option. For example this would mount an iscsi disk sdb:
Packit eace71
Packit eace71
	/dev/sdb /mnt/iscsi ext3 _netdev 0 0
Packit eace71
Packit eace71
SUSE or Debian:
Packit eace71
---------------
Packit eace71
Otherwise, if there is an initd script for your distro in etc/initd that
Packit eace71
gets installed with "make install"
Packit eace71
Packit eace71
	/etc/init.d/open-iscsi start
Packit eace71
Packit eace71
will usually get you started.
Packit eace71
Packit eace71
Packit eace71
7.1.2 Manual Startup
Packit eace71
====================
Packit eace71
Packit eace71
7.1.2.1 Starting up the iSCSI daemon (iscsid) and loading modules
Packit eace71
=================================================================
Packit eace71
Packit eace71
If there is no initd script, you must start the tools by hand. First load the
Packit eace71
iscsi modules:
Packit eace71
	modprobe -q iscsi_tcp
Packit eace71
Packit eace71
After that, start iSCSI daemon process:
Packit eace71
	./iscsid
Packit eace71
Packit eace71
or alternatively, start it with debug enabled and with output
Packit eace71
redirected to the current console:
Packit eace71
	./iscsid -d 8 -f &
Packit eace71
Packit eace71
Packit eace71
7.1.2.2 Logging into Targets
Packit eace71
============================
Packit eace71
Packit eace71
Use the configuration utility, iscsiadm, to add/remove/update Discovery
Packit eace71
records, iSCSI Node records or monitor active iSCSI sessions (see above or the
Packit eace71
iscsiadm man files and see section 7.2 below for how to discover targets):
Packit eace71
	./iscsiadm  -m node
Packit eace71
Packit eace71
will print out the nodes that have been discovered as:
Packit eace71
Packit eace71
	10.15.85.19:3260,3 iqn.1992-08.com.netapp:sn.33615311
Packit eace71
	10.15.84.19:3260,2 iqn.1992-08.com.netapp:sn.33615311
Packit eace71
Packit eace71
The format is:
Packit eace71
	ip:port,target_portal_group_tag targetname
Packit eace71
Packit eace71
If you are using the iface argument or want to see the driver
Packit eace71
info, use the following:
Packit eace71
	./iscsiadm -m node -P 1
Packit eace71
Packit eace71
Example output:
Packit eace71
	Target: iqn.1992-08.com.netapp:sn.33615311
Packit eace71
	        Portal: 10.15.84.19:3260,2
Packit eace71
	                Iface Name: iface2
Packit eace71
	        Portal: 10.15.85.19:3260,3
Packit eace71
	                Iface Name: iface2
Packit eace71
Packit eace71
The format is:
Packit eace71
	Target: targetname
Packit eace71
		Portal ip_address:port,tpgt
Packit eace71
			Iface: ifacename
Packit eace71
Packit eace71
where targetname is the name of the target and ip_address:port is the address
Packit eace71
and port of the portal. tpgt is the Target Portal Group Tag of
Packit eace71
the portal, and is not used in iscsiadm commands except for static
Packit eace71
record creation. ifacename is the name of the iscsi interface
Packit Service 15966b
defined in /var/lib/iscsi/ifaces. If no interface was defined in
Packit Service 15966b
/var/lib/iscsi/ifaces or passed in, the default behavior is used.
Packit eace71
Default here is iscsi_tcp/tcp to be used over whichever NIC the
Packit eace71
network layer decides is best.
Packit eace71
Packit eace71
To login, take the ip, port and targetname from above and run:
Packit eace71
	./iscsiadm -m node -T targetname -p ip:port -l
Packit eace71
Packit eace71
In this example we would run:
Packit eace71
	./iscsiadm -m node -T iqn.1992-08.com.netapp:sn.33615311 \
Packit eace71
		-p 10.15.84.19:3260 -l
Packit eace71
Packit eace71
	Note: drop the portal group tag from the "iscsiadm -m node" output.
Packit eace71
Packit eace71
Packit eace71
7.2. Discover Targets
Packit eace71
=====================
Packit eace71
Packit eace71
Once the iSCSI service is running, you can perform discovery using
Packit eace71
SendTarget with:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p ip:port --discover
Packit eace71
Packit eace71
where "ip" is the address of the portal and port is the port.
Packit eace71
Packit eace71
To use iSNS you can run the discovery command with the type as "isns"
Packit eace71
and pass in the ip:port:
Packit eace71
	iscsiadm -m discoverydb -t isns -p ip:port --discover
Packit eace71
Packit eace71
Both commands will print out the list of all discovered targets and their
Packit eace71
portals:
Packit eace71
Packit eace71
	# iscsiadm -m discoverydb -t st -p 10.15.85.19:3260 --discover
Packit eace71
	10.15.84.19:3260,2 iqn.1992-08.com.netapp:sn.33615311
Packit eace71
	10.15.85.19:3260,3 iqn.1992-08.com.netapp:sn.33615311
Packit eace71
Packit eace71
The format for the output is:
Packit eace71
	ip:port,tpgt targetname
Packit eace71
Packit eace71
In this example, for the first target the ip address is 10.15.85.19.
Packit eace71
The port is 3260. The target portal group is 3. The target name
Packit eace71
is iqn.1992-08.com.netapp:sn.33615311.
Packit eace71
Packit eace71
If you would also like to see the iscsi inteface which will be used
Packit eace71
for each session then use the --print=[N]/-P [N] option:
Packit eace71
	iscsiadm -m discoverydb -t sendtargets -p ip:port -P 1 --discover
Packit eace71
Packit eace71
will print:
Packit eace71
    Target: iqn.1992-08.com.netapp:sn.33615311
Packit eace71
        Portal: 10.15.84.19:3260,2
Packit eace71
           Iface Name: iface2
Packit eace71
        Portal: 10.15.85.19:3260,3
Packit eace71
           Iface Name: iface2
Packit eace71
Packit eace71
In this example, The IP address of the first portal is 10.15.84.19.
Packit eace71
The port is 3260. The target portal group is 3. The target name
Packit eace71
is iqn.1992-08.com.netapp:sn.33615311. The iface being used is iface2.
Packit eace71
Packit eace71
While discovery targets are kept in the discovery db, they are
Packit eace71
useful only for re-discovery. The discovered targets (a.k.a. nodes)
Packit eace71
are stored as records in the node db.
Packit eace71
Packit eace71
The discovered targets are not logged into yet. Rather than logging
Packit eace71
into the discovered nodes (making LUs from those nodes available as
Packit eace71
storage), it is better to automate the login to the nodes we need.
Packit eace71
Packit eace71
If you wish to log into a target manually now, see section
Packit eace71
"7.1.2.2 Logging in targets" above.
Packit eace71
Packit eace71
Packit eace71
7.3. Automate Target Logins for Future System Statups
Packit eace71
=====================================================
Packit eace71
Packit eace71
Note: this may only work for distros with init scripts.
Packit eace71
Packit eace71
To automate login to a node, use the following with the record ID
Packit eace71
(record ID is the targetname and portal) of the node discovered in the
Packit eace71
discovery above:
Packit eace71
	iscsiadm -m node -T targetname -p ip:port --op update -n node.startup -v automatic
Packit eace71
Packit eace71
To set the automatic setting to all portals on a target through every
Packit eace71
interface setup for each protal, the following can be run:
Packit eace71
	iscsiadm -m node -T targetname --op update -n node.startup -v automatic
Packit eace71
Packit eace71
Or to set the "node.startup" attribute to "automatic" as default for
Packit eace71
all sessions add the following to the /etc/iscsi/iscsid.conf:
Packit eace71
	node.startup = automatic
Packit eace71
Packit eace71
Setting this in iscsid.conf will not affect existing nodes. It will only
Packit eace71
affect nodes that are discovered after setting the value.
Packit eace71
Packit eace71
To login to all automated nodes, simply restart the iscsi service, e.g. with:
Packit eace71
	/etc/init.d/open-iscsi restart
Packit eace71
Packit eace71
On your next startup the nodes will be logged into automatically.
Packit eace71
Packit eace71
Packit eace71
7.4 Automatic Discovery and Login
Packit eace71
=================================
Packit eace71
Packit eace71
Instead of running the iscsiadm discovery command and editing the
Packit eace71
startup setting, iscsid can be configured so that every X seconds
Packit eace71
it performs discovery and logs in and out of the portals returned or
Packit eace71
no longer returned. In this mode, when iscsid starts it will check the
Packit eace71
discovery db for iSNS records with:
Packit eace71
	discovery.isns.use_discoveryd = Yes
Packit eace71
Packit eace71
and it will check for SendTargets discovery records that have the setting:
Packit eace71
	discovery.sendtargets.use_discoveryd = Yes
Packit eace71
Packit eace71
If set, iscsid will perform discovery to the address every
Packit eace71
discovery.isns.discoveryd_poll_inval or
Packit eace71
discovery.sendtargets.discoveryd_poll_inval seconds,
Packit eace71
and it will log into any portals found from the discovery source using
Packit Service 15966b
the ifaces in /var/lib/iscsi/ifaces.
Packit eace71
Packit eace71
Note that for iSNS the poll_interval does not have to be set. If not set,
Packit eace71
iscsid will only perform rediscovery when it gets a SCN from the server.
Packit eace71
Packit eace71
#   iSNS Note:
Packit eace71
#   For servers like Microsoft's where they allow SCN registrations, but do not
Packit eace71
#   send SCN events, discovery.isns.poll_interval should be set to a non zero
Packit eace71
#   value to auto discover new targets. This is also useful for servers like
Packit eace71
#   linux-isns (SLES's iSNS server) where it sometimes does not send SCN
Packit eace71
#   events in the proper format, so they may not get handled.
Packit eace71
Packit Service 539fda
To set the startup value, so that nodes are not logged into automatically
Packit Service 539fda
use the value "manual".
Packit Service 539fda
Packit eace71
Examples
Packit eace71
--------
Packit eace71
Packit eace71
SendTargets
Packit eace71
-----------
Packit eace71
Packit eace71
- Create a SendTargets record by passing iscsiadm the "-o new" argument in
Packit eace71
		discoverydb mode.
Packit eace71
	iscsiadm -m discoverydb -t st -p 20.15.0.7:3260 -o new
Packit eace71
Packit eace71
	On success, this will output something like:
Packit eace71
		New discovery record for [20.15.0.7,3260] added.
Packit eace71
Packit eace71
- Set the use_discoveryd setting for the record.
Packit eace71
	iscsiadm -m discoverydb -t st -p 20.15.0.7:3260  -o update \
Packit eace71
		-n discovery.sendtargets.use_discoveryd -v Yes
Packit eace71
Packit eace71
- Set the polling interval.
Packit eace71
	iscsiadm -m discoverydb -t st -p 20.15.0.7:3260  -o update \
Packit eace71
		-n discovery.sendtargets.discoveryd_poll_inval -v 30
Packit eace71
Packit eace71
To have the new settings take effect, restart iscsid by restarting the
Packit eace71
iscsi service.
Packit eace71
Packit eace71
Note:
Packit eace71
When iscsiadm is run with the -o new argument, it will use the
Packit eace71
discovery.sendtargets.use_discoveryd and
Packit eace71
discovery.sendtargets.discoveryd_poll_inval
Packit eace71
settings in iscsid.conf for the records initial settings. So if those
Packit eace71
are set in iscsid.conf, then you can skip the iscsiadm -o update
Packit eace71
commands.
Packit eace71
Packit eace71
iSNS
Packit eace71
----
Packit eace71
Packit eace71
- Create an iSNS record by passing iscsiadm the "-o new" argument in
Packit eace71
		discoverydb mode.
Packit eace71
	iscsiadm -m discoverydb -t isns -p 20.15.0.7:3205 -o new
Packit eace71
Packit eace71
	Response on success:
Packit eace71
		New discovery record for [20.15.0.7,3205] added.
Packit eace71
Packit eace71
- Set the use_discoveryd setting for the record.
Packit eace71
	iscsiadm -m discoverydb -t isns -p 20.15.0.7:3205  -o update \
Packit eace71
		-n discovery.isns.use_discoveryd -v Yes
Packit eace71
Packit eace71
- [OPTIONAL: see iSNS note above] Set the polling interval if needed.
Packit eace71
	iscsiadm -m discoverydb -t st -p 20.15.0.7:3205  -o update \
Packit eace71
		-n discovery.isns.discoveryd_poll_inval -v 30
Packit eace71
Packit eace71
To have the new settings take effect, restart iscsid by restarting the
Packit eace71
iscsi service.
Packit eace71
Packit eace71
Note:
Packit eace71
When iscsiadm is run with the -o new argument, it will use the
Packit eace71
discovery.isns.use_discoveryd and discovery.isns.discoveryd_poll_inval
Packit eace71
settings in iscsid.conf for the record's initial settings. So if those
Packit eace71
are set in iscsid.conf, then you can skip the iscsiadm -o update
Packit eace71
commands.
Packit eace71
Packit eace71
Packit eace71
8. Advanced Configuration
Packit eace71
=========================
Packit eace71
Packit eace71
8.1 iSCSI settings for dm-multipath
Packit eace71
===================================
Packit eace71
Packit eace71
When using dm-multipath, the iSCSI timers should be set so that commands
Packit eace71
are quickly failed to the dm-multipath layer. For dm-multipath you should
Packit eace71
then set values like queue if no path, so that IO errors are retried and
Packit eace71
queued if all paths are failed in the multipath layer.
Packit eace71
Packit eace71
Packit eace71
8.1.1 iSCSI ping/Nop-Out settings
Packit eace71
=================================
Packit eace71
To quickly detect problems in the network, the iSCSI layer will send iSCSI
Packit eace71
pings (iSCSI NOP-Out requests) to the target. If a NOP-Out times out, the
Packit eace71
iSCSI layer will respond by failing running commands and asking the SCSI
Packit eace71
layer to requeue them if possible (SCSI disk commands get 5 retries if not
Packit eace71
using multipath). If dm-multipath is being used the SCSI layer will fail
Packit eace71
the command to the multipath layer instead of retrying. The multipath layer
Packit eace71
will then retry the command on another path.
Packit eace71
Packit eace71
To control how often a NOP-Out is sent, the following value can be set:
Packit eace71
	node.conn[0].timeo.noop_out_interval = X
Packit eace71
Packit eace71
Where X is in seconds and the default is 10 seconds. To control the
Packit eace71
timeout for the NOP-Out the noop_out_timeout value can be used:
Packit eace71
	node.conn[0].timeo.noop_out_timeout = X
Packit eace71
Packit eace71
Again X is in seconds and the default is 15 seconds.
Packit eace71
Packit eace71
Normally for these values you can use:
Packit eace71
Packit eace71
	node.conn[0].timeo.noop_out_interval = 5
Packit eace71
	node.conn[0].timeo.noop_out_timeout = 10
Packit eace71
Packit eace71
If there are a lot of IO error messages, then the above values may be too
Packit eace71
aggressive and you may need to increase the values for your network conditions
Packit eace71
and workload, or you may need to check your network for possible problems.
Packit eace71
Packit eace71
Packit eace71
8.1.2 replacement_timeout
Packit eace71
=========================
Packit eace71
Packit eace71
The next iSCSI timer that will need to be tweaked is:
Packit eace71
Packit eace71
node.session.timeo.replacement_timeout = X
Packit eace71
Packit eace71
Here X is in seconds.
Packit eace71
Packit eace71
replacement_timeout will control how long to wait for session re-establishment
Packit eace71
before failing pending SCSI commands and commands that are being operated on by
Packit eace71
the SCSI layer's error handler up to a higher level like multipath or to
Packit eace71
an application if multipath is not being used.
Packit eace71
Packit eace71
Packit eace71
8.1.2.1 Running Commands, the SCSI Error Handler, and replacement_timeout
Packit eace71
=========================================================================
Packit eace71
Packit eace71
Remember from the Nop-out discussion that if a network problem is detected,
Packit eace71
the running commands are failed immediately. There is one exception to this,
Packit eace71
and that is when the SCSI layer's error handler is running. To check if
Packit eace71
the SCSI error handler is running, iscsiadm can be run as:
Packit eace71
	iscsiadm -m session -P 3
Packit eace71
Packit eace71
You will then see:
Packit eace71
	Host Number: X State: Recovery
Packit eace71
Packit eace71
When the SCSI EH is running, commands will not be failed until
Packit eace71
node.session.timeo.replacement_timeout seconds.
Packit eace71
Packit eace71
To modify the timer that starts the SCSI EH, you can either write
Packit eace71
directly to the device's sysfs file:
Packit eace71
	echo X > /sys/block/sdX/device/timeout
Packit eace71
Packit eace71
where X is in seconds.
Packit eace71
Alternatively, on most distros you can modify the udev rule.
Packit eace71
Packit eace71
To modify the udev rule open /etc/udev/rules.d/50-udev.rules, and find the
Packit eace71
following lines:
Packit eace71
Packit eace71
	ACTION=="add", SUBSYSTEM=="scsi" , SYSFS{type}=="0|7|14", \
Packit eace71
		RUN+="/bin/sh -c 'echo 60 > /sys$$DEVPATH/timeout'"
Packit eace71
Packit eace71
And change the "echo 60" part of the line to the value that you want.
Packit eace71
Packit eace71
The default timeout for normal File System commands is 30 seconds when udev
Packit eace71
is not being used. If udev is used the default is the above value which
Packit eace71
is normally 60 seconds.
Packit eace71
Packit eace71
Packit eace71
8.1.2.2 Pending Commands and replacement_timeout
Packit eace71
================================================
Packit eace71
Packit eace71
Commonly, the SCSI/BLOCK layer will queue 256 commands, but the path can
Packit eace71
only take 32. When a network problem is detected, the 32 commands
Packit eace71
in flight will be sent back to the SCSI layer immediately and because
Packit eace71
multipath is being used, this will cause the commands to be sent to the multipath
Packit eace71
layer for execution on another path. However, the other 96 commands that were
Packit eace71
still in the SCSI/BLOCK queue will remain there until the session is
Packit eace71
re-established or until node.session.timeo.replacement_timeout seconds has
Packit eace71
gone by. After replacement_timeout seconds, the pending commands will be
Packit eace71
failed to the multipath layer, and all new incoming commands will be
Packit eace71
immediately failed back to the multipath layer. If a session is later
Packit eace71
re-established, then new commands will be queued and executed. Normally,
Packit eace71
multipathd's path tester mechanism will detect that the session has been
Packit eace71
re-established and the path is accessible again, and it will inform
Packit eace71
dm-multipath.
Packit eace71
Packit eace71
Packit eace71
8.1.3 Optimal replacement_timeout Value
Packit eace71
=======================================
Packit eace71
Packit eace71
The default value for replacement_timeout is 120 seconds, but because
Packit eace71
multipath's queue_if_no_path and no_path_retry setting can prevent IO errors
Packit eace71
from being propagated to the application, replacement_timeout can be set to a
Packit eace71
shorter value like 5 to 15 seconds. By setting it lower, pending IO is quickly
Packit eace71
sent to a new path and executed while the iSCSI layer attempts
Packit eace71
re-establishment of the session. If all paths end up being failed, then the
Packit eace71
multipath and device mapper layer will internally queue IO based on the
Packit eace71
multipath.conf settings, instead of the iSCSI layer.
Packit eace71
Packit eace71
Packit eace71
8.2 iSCSI settings for iSCSI root
Packit eace71
=================================
Packit eace71
Packit eace71
When accessing the root partition directly through an iSCSI disk, the
Packit eace71
iSCSI timers should be set so that iSCSI layer has several chances to try to
Packit eace71
re-establish a session and so that commands are not quickly requeued to
Packit eace71
the SCSI layer. Basically you want the opposite of when using dm-multipath.
Packit eace71
Packit eace71
For this setup, you can turn off iSCSI pings by setting:
Packit eace71
Packit eace71
	node.conn[0].timeo.noop_out_interval = 0
Packit eace71
	node.conn[0].timeo.noop_out_timeout = 0
Packit eace71
Packit eace71
And you can turn the replacement_timer to a very long value:
Packit eace71
	node.session.timeo.replacement_timeout = 86400
Packit eace71
Packit eace71
Packit eace71
9. iSCSI System Info
Packit eace71
====================
Packit eace71
Packit eace71
To get information about the running sessions: including the session and
Packit eace71
device state, session ids (sid) for session mode, and some of the
Packit eace71
negotiated parameters, run:
Packit eace71
	iscsiadm -m session -P 2
Packit eace71
Packit eace71
If you are looking for something shorter, like just the sid to node mapping,
Packit eace71
run:
Packit eace71
	iscsiadm -m session [-P 0]
Packit eace71
Packit eace71
This will print the list of running sessions with the format:
Packit eace71
	driver [sid] ip:port,target_portal_group_tag targetname
Packit eace71
Packit eace71
Example output of "iscsiadm -m session":
Packit eace71
Packit eace71
	tcp [2] 10.15.84.19:3260,2 iqn.1992-08.com.netapp:sn.33615311
Packit eace71
	tcp [3] 10.15.85.19:3260,3 iqn.1992-08.com.netapp:sn.33615311
Packit eace71
Packit eace71
To print the hw address info use the -P option with "1":
Packit eace71
	iscsiadm -m session -P 1
Packit eace71
Packit eace71
This will print the sessions with the following format:
Packit eace71
Target: targetname
Packit eace71
	Current Portal: portal currently logged into
Packit eace71
	Persistent Portal: portal we would fall back to if we had got
Packit eace71
			   redirected during login
Packit eace71
		Iface Transport: driver/transport_name
Packit eace71
		Iface IPaddress: IP address of iface being used
Packit eace71
		Iface HWaddress: HW address used to bind session
Packit eace71
		Iface Netdev: netdev value used to bind session
Packit eace71
		SID: iscsi sysfs session id
Packit eace71
		iSCSI Connection State: iscsi state
Packit eace71
Packit eace71
Note: if an older kernel is being used or if the session is not bound,
Packit eace71
then the keyword "default" is printed to indicate that the default
Packit eace71
network behavior is being used.
Packit eace71
Packit eace71
Example output of "iscsiadm -m session -P 1":
Packit eace71
	Target: iqn.1992-08.com.netapp:sn.33615311
Packit eace71
		Current Portal: 10.15.85.19:3260,3
Packit eace71
		Persistent Portal: 10.15.85.19:3260,3
Packit eace71
			Iface Transport: tcp
Packit eace71
			Iface IPaddress: 10.11.14.37
Packit eace71
			Iface HWaddress: default
Packit eace71
			Iface Netdev: default
Packit eace71
			SID: 7
Packit eace71
			iSCSI Connection State: LOGGED IN
Packit eace71
			Internal iscsid Session State: NO CHANGE
Packit eace71
Packit eace71
The connection state is currently not available for qla4xxx.
Packit eace71
Packit eace71
To get a HBA/Host view of the session, there is the host mode:
Packit eace71
	iscsiadm -m host
Packit eace71
Packit eace71
This prints the list of iSCSI hosts in the system with the format:
Packit eace71
	driver [hostno] ipaddress,[hwaddress],net_ifacename,initiatorname
Packit eace71
Packit eace71
Example output:
Packit eace71
	cxgb3i: [7] 10.10.15.51,[00:07:43:05:97:07],eth3 <empty>
Packit eace71
Packit eace71
To print this info in a more user friendly way, the -P argument can be used:
Packit eace71
	iscsiadm -m host -P 1
Packit eace71
Packit eace71
Example output:
Packit eace71
	Host Number: 7
Packit eace71
		State: running
Packit eace71
		Transport: cxgb3i
Packit eace71
		Initiatorname: <empty>
Packit eace71
		IPaddress: 10.10.15.51
Packit eace71
		HWaddress: 00:07:43:05:97:07
Packit eace71
		Netdev: eth3
Packit eace71
Packit eace71
Here, you can also see the state of the host.
Packit eace71
Packit eace71
You can also pass in any value from 1 - 4 to print more info, like the
Packit eace71
sessions running through the host, what ifaces are being used and what
Packit eace71
devices are accessed through it.
Packit eace71
Packit eace71
To print the info for a specific host, you can pass in the -H argument
Packit eace71
with the host number:
Packit eace71
	iscsiadm -m host -P 1 -H 7