====== Using the Linux iSCSI software initiator ======


===== Requirements =====
You'll need:
  * An iSCSI-enabled kernel (or kernel modules).  This is standard in kernels >= 2.6.18.
  * Userland tools from the "open-iscsi" package.  Probably not installed by default, so install with your favorite package manager (or tarball, if that's how you roll).

===== Overview =====
There are two halves to the iSCSI software initiator:
  - Kernel parts, which do "read block", "write block"
  - Userland parts: administration, login, logout, etc.

Basically, the process of mounting a LUN works as follows:
  - In userland, "discover" the target & lun, save info to a config file.
  - In userland, "login" to target, which makes the kernel create a /dev/sd? device for the LUN(s)
  - Mess with device as normal.

===== Procedure =====
  * Install package "open-iscsi" (userland tools) from your distributions package manager.  In Ubuntu:

  $ sudo apt-get install open-iscsi

  * Check/set iSCSI initiator name.  This may be in '''/etc/initiatorname.iscsi''' or '''/etc/iscsi/initiatorname.iscsi'''

  $ sudo YourEditorOfChoice /etc/iscsi/initiatorname.iscsi

  * Load the modules & start the iscsid service.  Your package manager may have done this for you, but make sure.

In RedHat:

  $ sudo service open-iscsi start

Elsewhere:

  $ sudo /etc/init.d/open-iscsi start

This makes dmesg say:

  Loading iSCSI transport class v2.0-724.
  iscsi: registered transport (tcp)
  iscsi: registered transport (iser)

  * Associate given initiator with an iGroup and LUN on the filer.

  * Perform iSCSI discovery to populate your config files:

  $ iscsiadm -m discovery -t sendtargets -p 10.60.118.14:3260
  10.60.118.14:3260,1001 iqn.1992-08.com.netapp:sn.101166881

  * "Log in" to the filer to attach the LUN:

  $ iscsiadm -m node -T iqn.1992-08.com.netapp:sn.101166881 -p 10.60.118.14:3260 -l

This makes dmesg say:

  scsi4 : iSCSI Initiator over TCP/IP
  scsi 4:0:0:0: Direct-Access     NETAPP   LUN              0.2  PQ: 0 ANSI: 4
  SCSI device sdb: 16777216 512-byte hdwr sectors (8590 MB)
  sdb: Write Protect is off
  sdb: Mode Sense: bd 00 00 08
  SCSI device sdb: write cache: disabled, read cache: enabled, doesn't support DPO or FUA
  SCSI device sdb: 16777216 512-byte hdwr sectors (8590 MB)
  sdb: Write Protect is off
  sdb: Mode Sense: bd 00 00 08
  SCSI device sdb: write cache: disabled, read cache: enabled, doesn't support DPO or FUA
   sdb: sdb1 sdb2
  sd 4:0:0:0: Attached scsi disk sdb
  sd 4:0:0:0: Attached scsi generic sg1 type 0

  * The LUN is now treated like a local SCSI drive, so we can do things like:

  $ fdisk /dev/sdb
  $ mount /dev/sdb2 /mnt/mylun

  * Optional - make the iSCSI login occur automatically at boot:
    * First, make our LUN be attached whenever the iscsid service is started:
      * Edit /etc/iscsi/nodes/<Target_IQN>/<Target_IP_and_port>
      * Change "node.startup = manual" to "node.startup = automatic"
    * Second, make the iscsi service load at boot.  For Ubuntu, run "services-admin".  For RedHat, do:

  $ chkconfig --level <levels> open-iscsi on