open-iscsi

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

            Linux* Open-iSCSI

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

                                               Jun 6, 2022

Contents

• 1. In This Release
• 1. Introduction
• 1. Installation
• 1. Open-iSCSI daemon
• 1. Open-iSCSI Configuration Utility
• 1. Configuration
• 1. Getting Started
• 1. Advanced Configuration
• 1. iSCSI System Info

1. In This Release

This file describes the Linux* Open-iSCSI Initiator. The software was tested on AMD Opteron (TM) and Intel Xeon (TM).

The latest development release is available at:

https://github.com/open-iscsi/open-iscsi

For questions, comments, contributions post an issue on github, or send e-mail to:

[email protected]

You can also raise an issue on the github page.

1.1. Features

• highly optimized and very small-footprint data path
• persistent configuration database
• SendTargets discovery
• CHAP
• PDU header Digest
• multiple sessions

1.2 Licensing

The daemon and other top-level commands are licensed as GPLv3, while the libopeniscsiusr library used by some of those commmands is licensed as LGPLv3.

1. Introduction

The Open-iSCSI project is a high-performance, transport independent, multi-platform implementation of RFC3720 iSCSI.

Open-iSCSI is partitioned into user and kernel parts.

The kernel portion of Open-iSCSI was originally part of this project repository, but now is built into the linux kernel itself. It includes loadable modules: scsi_transport_iscsi.ko, libiscsi.ko and scsi_tcp.ko. The kernel code handles the "fast" path, i.e. data flow.

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 (perhaps 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. There are also helper programs, and iscsiuio, which is used for certain iSCSI adapters.

1. Installation

NOTE: You will need to be root to install the Open-iSCSI code, and you will also need to be root to run it.

As of today, the Open-iSCSI Initiator requires a host running the Linux operating system with kernel.

The userspace components iscsid, iscsiadm and iscsistart require the open-isns library, unless open-isns use is diabled when building (see below).

If this package is not available for your distribution, you can download and install it yourself. To install the open-isns headers and library required for Open-iSCSI, download the current release from:

https://github.com/open-iscsi/open-isns

Then, from the top-level directory, run:

./configure []
make
make install

For the open-iscsi project and iscsiuio, the original build system used make and autoconf the build the project. These build systems are being depcreated in favor of meson (and ninja). See below for how to build using make and autoconf, but migrating as soon as possible to meson would be a good idea.

Building open-iscsi/iscsiuio using meson

For Open-iSCSI and iscsiuio, the system is built using meson and ninja (see https://github.com/mesonbuild/meson). If these packages aren't available to you on your Linux distribution, you can download the latest release from: https://github.com/mesonbuild/meson/releases). The README.md file describes in detail how to build it yourself, including how to get ninja.

To build the open-iscsi project, including iscsiuio, first run meson to configure the build, from the top-level open-iscsi directory, e.g.:

rm -rf builddir
mkdir builddir
meson [] builddir

Then, to build the code:

ninja -C builddir

If you change any code and want to rebuild, you simply run ninja again.

When you are ready to install:

[DESTDIR=] ninja -C builddir install

This will install the iSCSI tools, configuration files, interfaces, and documentation. If you do not set DESTDIR, it defaults to "/".

Note that if you install open-iscsi using meson/ninja, you will also need to manually create/set up an initiatorname.iscsi file in ${HOMEDIR} (see below for location). There are several tools supplied for manually creating an initiator name.

MESON-OPTIONS:

One can override several default values when building with meson:

Option Description ===================== =====================================================

--libdir= Where library files go [/lib64] --sbindir= Meson 0.63 or newer: Where binaries go [/usr/sbin] -Dc_flags="" Add in addition flags to the C compiler -Dno_systemd= Enables systemd usage [false] (set to "true" to disable systemd) -Dsystemddir= Set systemd unit directory [/usr/lib/systemd] -Dhomedir= Set config file directory [/etc/iscsi] -Ddbroot= Set Database directory [/var/lib/iscsi] -Dlockdir= Set Lock directory [/run/lock/iscsi] -Drulesdir= Set udev rules directory [/usr/lib/udev/rules.d] -Discsi_sbindir= Where binaries go [/usr/sbin] (for use when sbindir can't be set, in older versions of meson) -Disns_supported= Enable/disable iSNS support [true] (set to "false" to disable use of open-isns)

Building open-iscsi/iscsiuio using make/autoconf (Deprecated)

If you wish to build using the older deprecated system, you can simply run:

make []
make [DESTDIR=] install

Where MAKE-OPTIONS are from: * SBINDIR= [/usr/bin] for executables * DBROOT= [/var/lib/iscsi] for iscsi database files * HOMEDIR= [/etc/iscsi] for iscsi config files

1. Open-iSCSI daemon

The iscsid daemon implements control path of iSCSI protocol, plus some management facilities. For example, the daemon could be configured to automatically re-start discovery at startup, based on the contents of persistent iSCSI database (see next section).

For help, run:

iscsid --help

The output will be similar to the following (assuming a default install):

Usage: iscsid [OPTION]

-c, --config=[path] Execute in the config file (${HOMEDIR}/iscsid.conf). -i, --initiatorname=[path] read initiatorname from file (${HOMEDIR}/initiatorname.iscsi). -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 -n, --no-pid-file do not use a pid file -p, --pid=pidfile use pid file (default /run/iscsid.pid). -h, --help display this help and exit -v, --version display version and exit

1. Open-iSCSI Configuration and Administration Utility

Open-iSCSI persistent configuration is stored in a number of directories under a configuration root directory, using a flat-file format. This configuration (database) root directory is /var/lib/iscsi by default, but may also commonly be in /etc/iscsi (see "DBROOT" in the meson options discussed earlier).

Configuration is contained in directories for (some of which may not be present, if they haven't been needed yet):

- nodes
- isns
- static
- fw
- send_targets
- ifaces

The iscsiadm utility is a command-line tool to manage (update, delete, insert, query) the persistent database, as well manage discovery, session establishment (login), and ending sessions (logout).

This utility presents set of operations that a user can perform on iSCSI node, session, connection, and discovery records.

Open-iSCSI does not use the term node as defined by the iSCSI RFC, where a node is a single iSCSI initiator or target. Open-iSCSI uses the term node to refer to a portal on a target, so tools like iscsiadm require that the '--targetname' and '--portal' arguments be used when in node mode.

For session mode, a session id (sid) is used. The sid of a session can be found by running:

iscsiadm -m session -P 1

The session id is not currently persistent and is partially determined by when the session is setup.

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

For help on the command, run:

iscsiadm --help

The output will be similar to the following.

iscsiadm -m discoverydb [-hV] [-d debug_level] [-P printlevel] [-t type -p ip:port -I ifaceN ... [-Dl]] | [[-p ip:port -t type] [-o operation] [-n name] [-v value] [-lD]] iscsiadm -m discovery [-hV] [-d debug_level] [-P printlevel] [-t type -p ip:port -I ifaceN ... [-l]] | [[-p ip:port] [-l | -D]] [-W] iscsiadm -m node [-hV] [-d debug_level] [-P printlevel] [-L all,manual,automatic,onboot] [-W] [-U all,manual,automatic,onboot] [-S] [[-T targetname -p ip:port -I ifaceN] [-l | -u | -R | -s]] [[-o operation ] [-n name] [-v value]] iscsiadm -m session [-hV] [-d debug_level] [-P printlevel] [-r sessionid | sysfsdir [-R | -u | -s] [-o operation] [-n name] [-v value]] iscsiadm -m iface [-hV] [-d debug_level] [-P printlevel] [-I ifacename | -H hostno|MAC] [[-o operation ] [-n name] [-v value]] [-C ping [-a ip] [-b packetsize] [-c count] [-i interval]] iscsiadm -m fw [-d debug_level] [-l] [-W] [[-n name] [-v value]] iscsiadm -m host [-P printlevel] [-H hostno|MAC] [[-C chap [-x chap_tbl_idx]] | [-C flashnode [-A portal_type] [-x flashnode_idx]] | [-C stats]] [[-o operation] [-n name] [-v value]] iscsiadm -k priority

The first parameter specifies the mode to operate in:

-m, --mode specify operational mode op =

Mode "discoverydb"

-m discoverydb --type=[type] --interface=[iface…] --portal=[ip:port]
--print=[N]
--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT]
--discover

		  This command will use the discovery record settings
		  matching the record with type=type and
		  portal=ip:port]. If a record does not exist, it will
		  create a record using the iscsid.conf discovery
		  settings.

		  By default, it will then remove records for
		  portals no longer returned. And,
		  if a portal is returned by the target, then the
		  discovery command will create a new record or modify
		  an existing one with values from iscsi.conf and the
		  command line.

		  [op] can be passed in multiple times to this
		  command, and it will alter the node DB manipulation.

		  If [op] is passed in and the value is
		  "new", iscsiadm will add records for portals that do
		  not yet have records in the db.

		  If [op] is passed in and the value is
		  "update", iscsiadm will update node records using
		  info from iscsi.conf and the command line for portals
		  that are returned during discovery and have
		  a record in the db.

		  If [op] is passed in and the value is "delete",
		  iscsiadm will delete records for portals that
		  were not returned during discovery.

		  If [op] is passed in and the value is
		  "nonpersistent", iscsiadm will not store
		  the portals found in the node DB. This is
		  only useful with the --login command.

		  See the example section for more info.

		  See below for how to setup iSCSI ifaces for
		  software iSCSI or override the system defaults.

		  Multiple ifaces can be passed in during discovery.

		  For the above commands, "print" is optional. If
		  used, N can be 0 or 1.
		  0 = The old flat style of output is used.
		  1 = The tree style with the inteface info is used.

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

-m discoverydb --interface=[iface...] --type=[type] --portal=[ip:port]
--print=[N]
--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT]
--discover --login

		  This works like the previous discoverydb command
		  with the --login argument passed in will also
		  log into the portals that are found.

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