Open-iSCSI - ArchWiki

Jump to content

# Open-iSCSI

From ArchWiki

This article describes how to access an iSCSI target with the Open-iSCSI initiator.

Note iSCSI is not encrypted. Transmitting data over an unsecured channel is not recommended.

## Installation

Install the open-iscsi package.

Note An older initiator, Linux-iSCSI, was merged with Open-iSCSI in April 2005. This should not be confused with linux-iscsi.org, the website for the LIO target.

## Overview

The following diagram shows how the Components work together:

     +--------------------------------------------------------+
     | Targets & Sessions configuration files and directories |
     +--------------------------------------------------------+

     +--------------------------+     +----------------------------------+
     | iscsiadm                 |     | iscsid: iSCSI daemon             |
     |                          |     |                                  |
     |  * Command line tool     |<--->|  * Implements Session management |
     |  * Manages database of   |     |  * Communicates with iscsiadm    |
     |    sessions and targets  |     |    and iscsi kernel modules      |
     +--------------------------+     +---------------+------------------+
                                                      |
     User space                                       |
    - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - -
     Kernel                                           v
             +-----------------------------------------------------------+
             | kernel modules: scsi_transport_iscsi, iscsi_tcp, libiscsi |
             +-----------------------------------------------------------+

From the Open-iSCSI README:

Persistent configuration is implemented as a tree of files and directories, which are contained in two directories:

Note The database home changed from `/etc/iscsi/` to `/var/lib/iscsi/` in open-iscsi 2.1.9-2. The migration is not done automatically. Please disconnect targets, stop the service, migrate and connect again. Also verify filesystem permissions.

`/etc/iscsi/` should only contain `initiatorname.iscsi` and `iscsid.conf`

- Discovery directory `/var/lib/iscsi/send_targets` which has directories named after target addresses.
- Node directory `/var/lib/iscsi/nodes` which has directories named after IQN (ISCSI Unique Name) of particular device.

## Configuration

### Start the Service

`iscsid` is managed by a systemd Unit.

Start `iscsid.service` or `iscsid.socket`.

### ISCSI Qualified Name (IQN)

IQN is used for identifying every device.

Open-ISCSI stores its initiator IQN in the `/etc/iscsi/initiatorname.iscsi` file with a format `InitiatorName=iqn`

During installation the initial IQN will be generated. If you wish to generate new IQN the `iscsi-iname` utility can be used which prints out new IQN.

### Authentication

If the ISCSI target requires authentication by the initiator, the configuration file `/etc/iscsi/iscsid.conf` may need to be updated.

The following parameters are used for authenticating a login session of an initiator to a target:

    node.session.auth.authmethod = CHAP
    node.session.auth.username = initiators_username
    node.session.auth.password = initiators_password

If your target has two-way authentication enabled then those lines also need to be edited:

    node.session.auth.username_in = targets_username
    node.session.auth.password_in = targets_password

If your target requires authentication to get the list of its nodes (most will not) then following lines should be edited:

    discovery.sendtargets.auth.authmethod = CHAP
    discovery.sendtargets.auth.username = initiators_username
    discovery.sendtargets.auth.password = initiators_password

If your target has two-way authentication enabled then those lines also need to be edited:

    discovery.sendtargets.auth.username_in = targets_username
    discovery.sendtargets.auth.password_in = targets_password

Warning No two passwords may be the same. This means that you need four unique passwords in the configuration above.
Note The authentication data is saved in per-node configuration files. To update them, edit `/var/lib/iscsi/nodes/iqn.node-name/node-ip-address,port,1/default` and add/adjust the options as necessary.[1]

### Target discovery

Request the target its nodes.

    # iscsiadm --mode discovery --portal target_ip --type sendtargets

On success information about nodes and target will be saved on your initiator.

### Add target manually

    # iscsiadm -m node --target targetname --portal target_ip -o new

A possible scenario to use this is when server does not allow discovery.

### Delete obsolete targets

    # iscsiadm -m discovery -p target_ip -o delete

### Login to available targets

    # iscsiadm -m node -L all

or login to specific target

    # iscsiadm -m node --targetname=targetname --login

logout:

    # iscsiadm -m node -U all

### Info

For running session

    # iscsiadm -m session -P 3

The last line of the above command will show the name of the attached device e.g

    Attached scsi disk sdd State: running

For the known nodes

    # iscsiadm -m node

### Online resize of volumes

If the iscsi blockdevice contains a partitiontable, you will not be able to do an online resize. In this case you have to unmount the filesystem and alter the size of the affected partition.

1. Rescan active nodes in current session

       # iscsiadm -m node -R

2. If you use multipath, you also have to rescan multipath volume information.

       # multipathd -k"resize map sdx"

3. Finally resize the filesystem.

       # resize2fs /dev/sdx

## Tips and tricks

### Check for attached iSCSI devices

You can also check where the attached iSCSI devices are located in the `/dev/` tree with:

    $ ls -l /dev/disk/by-path/ip-*

### Login to targets on boot

To log in to a target during boot, enable `iscsi.service` and make sure the nodes have `node.startup = automatic` in their configuration (`/var/lib/iscsi/nodes/iqn.node-name/node-ip-address,port`).

Note The systemd unit name is `iscsi.service` not `iscsid.service`.[2]

## Troubleshooting

### Client IQN

At the server (target) you might need to include the client IQN from `/etc/iscsi/initiatorname.iscsi` in the account configuration.

### Debugging the iSCSI daemon

To run the iSCSI daemon in debug mode (make sure you stopped `iscsid.service` before)

    # iscsid -d 8 -c /etc/iscsi/iscsid.conf -i /etc/iscsi/initiatorname.iscsi -f

Categories:

- Storage
- Networking

Open-iSCSI
Add topic