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

                Linux* Open-iSCSI

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

                                                November 8, 2006

Contents
========

- 1. In This Release
- 2. Introduction
- 3. Installation
- 4. Open-iSCSI daemon
- 5. Open-iSCSI Configuration Utility
- 6. Configuration
- 7. Getting Started


1. In This Release
==================

This file describes the Linux* Open-iSCSI Initiator. 

    1.1. Features
    
    - highly optimized and very small-footprint data path;
    - persistent configuration database;
    - SendTargets discovery;
    - CHAP;
    - PDU header Digest;
    - multiple sessions;
    
    For the most recent list of features please refer to:
    http://www.open-iscsi.org/cgi-bin/wiki.pl/Roadmap

2. Introduction
===============

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

To install the iSCSI tools run:

rpm -ivh iscsi-initiator-utils-<your version>.rpm

This will install iscsid and iscsiadm to /sbin. It will also install
default config files to /etc/iscsi:

/etc/iscsi/iscsid.conf - All new session will inherit settings from
this file when they are first discovered. To override a value for a specific
target see the iscsiadm op command below and in the iscsiadm man page.
See Configuration section below.

/etc/iscsi/initiatorname.iscsi - The default initaitor name for software
iSCSI initiator.


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

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 implemented as a set of 
iSCSI database files.

- Discovery (/var/lib/iscsi/send_targets);
- Node (/var/lib/iscsi/nodes).

The iscsiadm utility is a command-line tool to manage (update, delete,
insert, query) the persistent database.

The utility presents a set of operations that a user can perform 
on iSCSI nodes, sessions, connections, and discovery records.

Note that some of the iSCSI Node and iSCSI Discovery operations 
do not require iSCSI daemon (iscsid) loaded.

For help, run:

	./iscsiadm --help

Usage: iscsiadm [OPTION]

  -m, --mode <op>         specify operational mode op = <discovery|node>
  -m discovery --type=[type] --portal=[ip:port] --login
                          perform [type] discovery for target portal with
                          ip-address [ip] and port [port]. Initiate Login for
                          each discovered target if --login is specified
  -m discovery            display all discovery records from internal
                          persistent discovery database
  -m discovery --portal=[ip:port] --login
                          perform discovery based on portal in database
  -m discovery --portal=[ip:port] --op=[op] [--name=[name] --value=[value]]
                          perform specific DB operation [op] for specific
                          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
  -m node                 display all discovered nodes from internal
                          persistent discovery database
  -m node --targetname=[name] --portal=[ip:port] [--login|--logout]
  -m node --targetname=[name] --portal=[ip:port] --op=[op] [--name=[name] \
							--value=[value]]
                          perform specific DB operation [op] for specific
                          portal on target. 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
  -m node --logoutall=[all,manual,automatic]
			  Logout "all" the running sessions or just the ones
			  with a node or conn 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 or conn startup value manual or automatic.
			  Nodes marked as ONBOOT are skipped.
  -m session              display all active sessions and connections
  -m session --sid=[sid] [--info | --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, --rescan, --op only work on single session.
			  --logout and --op work like they do in node mode,
			  but in session mode targetname and portal info is
			  is not passed in.

			  If no sid and no operation is given print out the
			  running sessions.
  -d, --debug debuglevel  print debugging information
  -V, --version           display version and exit
  -h, --help              display this help and exit


    Usage examples (using the one-letter options):

    1) SendTargets iSCSI Discovery:

	    iscsiadm -m discovery -t sendtargets -p 192.168.1.1:3260

    2) iSCSI Login:

            login to a specific target:

	    iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 -l

            login to all targets:

            iscsiadm -m node --loginall=all

    3) iSCSI Logout:

            logout of a specific target:

	    iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260  -u

            logout of all targets:

            iscsiadm -m node --logoutall=all

    4) Changing iSCSI parameter:

	    iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260 \
	       -o update -n node.cnx[0].iscsi.MaxRecvDataSegmentLength -v 65536

    5) Adding custom iSCSI Node:

	    iscsiadm -m node -o new -p 192.168.0.1:3260

    6) Removing iSCSI Node:

	    iscsiadm -m node -o delete -T iqn.2005-03.com.max -p 192.168.0.4:3260

    7) Display iSCSI Node configuration:

	    iscsiadm -m node -T iqn.2005-03.com.max -p 192.168.0.4:3260

	or

	    iscsiadm -m node -o show -T iqn.2005-03.com.max -p 192.168.0.4:3260

    8) Show all node records:

            iscsiadm -m node

    9) Show all records in discovery database:

            iscsiadm -m discovery

   10) Display discovery record setting:

            iscsiadm -m discovery -p 192.168.0.4:3260

   11) Display session statistics:

            iscsiadm -m session -r 1 --stats

   12) Display session and device info:

            iscsiadm -m session -i

6. Configuration
================

The default configuration file is /etc/iscsi/iscsid.conf. This file contains
only configuration that could be overwritten by iSCSI Discovery,
or manualy updated via iscsiadm utility. It's OK if this file does not
exist in which case compiled-in default configuration will take place
for newer discovered Target nodes. See the example file for the current syntax.


7. Getting Started
==================
There are three steps needed to set up a system to use iSCSI storage:
1. automate iSCSI startup using the init script.
2. discover targets.
3. automate target logins for future system reboots.

1. automate iSCSI startup using the init script
-----------------------------------------------

To start the iSCSI daemon and log into targets with the node.startup value 
"automatic" you can do:

	service iscsi start

By default, when the system starts up this will be run for you once
you have installed the iscsi-initiator-utils package.

To automatically mount a file system during startup
you must have the partition entry in /etc/fstab marked with the "_netdev"
option. For example this would mount a iscsi disk sdb:

	/dev/sdb /mnt/iscsi ext3 _netdev 0 0


2. discover targets
-------------------
Once the iSCSI service is up, you can perform discovery to targets using:
iscsiadm -m discovery -t sendtargets -p 192.168.1.1:3260

While discovery targets are kept in the discovery db, they are
usefull only for re-discovery. The discovered targets (a.k.a. nodes)
are stored as records in the node db.

The discovered targets are not logged into yet like in past RHEL
iscsi-initiator-utils packages.

If you want to access the newly discovered target manually, run the
iscsiadm login command in section 5. In this example if

iscsiadm -m discovery -t sendtargets -p 192.168.1.1:3260

found a targe with two portals:

10.15.85.19:3260,3 iqn.1992-08.com.netapp:sn.33615311
10.15.84.19:3260,2 iqn.1992-08.com.netapp:sn.33615311

You could run:

iscsiadm -m node -T iqn.1992-08.com.netapp:sn.33615311 -p 10.15.85.19:3260 -l

to log into the first one listed.

3. automate target logins for future system reboots
---------------------------------------------------
To automate login to a node, use the following with the record ID of the
node discovered in the discovery above:
	iscsiadm -m node -T targetname -p ip:port --op update -n node.startup -v automatic

Or to set the "node.statup" attribute to "startup" as default for
all sessions that will be discovered add the following to the
/etc/iscsi/iscsid.conf:

	node.conn[0].startup = automatic

The next time the iSCSI service is started up, the target will be logged into
automatically.

The default setting is to automatically create a session to every portal
on the target. If you would like to disable automatic startup, set the startup
value to "manual".
