Red Hat Knowledgebase

After proper configuration, iSCSI-based storage will appear as a standard SCSI disk on a Red Hat Enterprise Linux 3 or 4 system.

Initiator configuration, Part 1

In iSCSI parlance, the device where data is stored is called the target. This is usually a SAN or NAS device like an EMC Clariion, Hitachi TagmaStore, IBM System Storage or NetApp Filer. The program or device on the server that handles communication with the iSCSI target is called the initiator. Red Hat ships a software-based initiator with Red Hat Enterprise Linux.

1. Install the iscsi-initiator-utils package

   After registering the system with the Red Hat Network (RHN) run this command to install the iscsi initiator pacakge:

   # up2date iscsi-initiator-utils

2. Create an /etc/initiatorname.iscsi file

   Each iSCSI device on the network, be it initiator or target, has a unique iSCSI node name. Red Hat uses the iSCSI Qualified Name (IQN) format with the initiator that ships with Red Hat Enterprise Linux. In the IQN format, a node name consists of a predefined section, chosen based on the initiator manufacturer, and a unique device name section which is editable by the administrator.

   iSCSI Node Name Guidelines

   • The entire node name can be up to 223 bytes in length
   • No white space is allowed
   • Node names are not case sensitive
   • The following ASCII characters can be used:
     • dash ('-')
     • dot ('.')
     • colon (":")
     • numbers 0-9
     • lower-case letters a-z

   The node name of the initiator is stored in the /etc/initiatorname.iscsi file. Red Hat recommends the use of the command /sbin/iscsi-iname to generate a random node name, which can then be customized by the administrator. Using the system name or function (i.e. mail-server-1 or oracle-3) as the unique portion of the name can simplify iSCSI administration. An example initiatorname.iscsi file is shown below:

   ## DO NOT EDIT OR REMOVE THIS FILE!
   ## If you remove this file, the iSCSI daemon will not start.
   ## If you change the InitiatorName, existing access control lists
   ## may reject this initiator.  The InitiatorName must be unique
   ## for each iSCSI initiator.  Do NOT duplicate iSCSI InitiatorNames.
   InitiatorName=iqn.1987-05.com.cisco:01.oracle-3
   

   For this example, the user editable portion of the file follows the characters :01.. Try running /sbin/iscsi-iname command several times to see which portions of the names are identical and which ones change every time. The portion of the name that changes is the random portion that can safely be changed to a name chosen by the administrator.

3. Edit the /etc/iscsi.conf file

   These are the most common options storage vendors recommend for the iscsi.conf configuration file. Administrators should check with their iSCSI storage hardware vendors to determine if these options are correct for their hardware. These options are already included in the example file provided by the iscsi-initiator-utils package. Simply uncomment the appropriate lines and add any necessary values to make them active. Note that the IP address of the iSCSI target being used must be added on the DiscoveryAddress line. Administrators should use multiple DiscoveryAddress lines if there are targets on multiple machines.

   Continuous=no
   
   HeaderDigest=never
   
   DataDigest=never
   
   ConnFailTimeout=180
   
   ImmediateData=yes
   
   DiscoveryAddress=<IP address of target> 
   

   This file also stores security settings. If incoming, outgoing or bi-directional security is desired, modify these lines in the iscsi.conf file to enable security:

   OutgoingUsername=<username>
   OutgoingPassword=<password>
   
   IncomingUsername=<anotherusername>
   IncomingPassword=<anotherpassword>
   

   Note that the username and password used for incoming security cannot match the username and password used for outgoing security. See the related articles section at the bottom of the page for more information about setting security parameters.

Target Configuration

Each type of target has its own configuration parameters and method for setting up LUNs, but there is a common set of tasks on all targets that must be performed to prepare storage for export as an iSCSI LUN.

1. Create the LUN(s)

   Using the directions provided by the iSCSI target hardware vendor, set up space on the storage system to be exported as an iSCSI LUN to the Red Hat Enterprise Linux system.

2. Create a LUN masking group

   Most iSCSI targets allow for LUN masking, which permits only certain LUNs to be visible from any particular host. This simplifies storage management by preventing systems from seeing LUNs that are unrelated to that system. Follow the hardware vendor's directions for creating a LUN masking group to ensure that LUNs are only seen by systems that should have access to them.

3. Add appropriate LUNs to LUN masking group

   Add the LUNs created in step one to the LUN masking group created in step two.

4. Add initiator names to LUN masking group

   Add the initiator name(s) of the appropriate systems to the LUN masking group.

5. Set up security (optional)

   Set up security on the target to match the security settings in the /etc/icsi.conf file on the initiator system. Security is optional but security settings on the target must match those on the initiator.

Initiator configuration, Part 2

1. Start the iSCSI initiator service and configure it to start automatically on boot:
   

   service iscsi start

   chkconfig iscsi --level 2345 on

   It may take a few moments for the service to start. This is normal behavior.

2. Scan for LUNs:
   

   fdisk -l

3. Create new partitions on the LUNs:
   

   fdisk /dev/sdX

4. Create filesystems on the LUNs, using disk labels
   

   mke2fs -j -L <label> /dev/sdXY

   It is extremely important to use disk labels when working with iSCSI storage. Delays in network traffic may cause the LUNs to be discovered in a different order the next time the system is booted. The only way to guarantee that the correct partition will be mounted at the proper mount point is to use disk labels to identify them.

5. Edit the /etc/fstab file to enable the iSCSI LUNs to mount at boot time

   The following example shows /etc/fstab entries for two iSCSI LUNs:

   #device		mount point	FS	Options	Backup	fsck
   LABEL=data1	/mnt/data1	ext3	_netdev	0	0
   LABEL=data2	/mnt/data2	ext3	_netdev	0	0
   

   Note the special _netdev option needed for mounting iSCSI storage

6. Mount the partitions:
   

   mount /mnt/data1

For more information about iSCSI, please see the related articles section at the bottom of this page.