How to Configure the FC QLogic Target Driver


WARNING: This procedure changes live kernel, HBA, firmware, boot, Fibre Channel fabric and storage state. It unloads and blacklists drivers, can flash HBA firmware, rebuilds an initial RAM disk, writes sysfs, enables target ports and exports writable storage. Do not run it without authorization for the exact host, HBA ports, firmware image, fabric, initiators and backing devices. Verify recovery and rollback plans before changing firmware or boot configuration.

TARGET SYSTEM


  1. Identify the exact HBA PCI device, board model and firmware from existing hardware inventory, read-only sysfs attributes and retained kernel logs. Do not clear the kernel log or unload and reload a storage driver merely to identify the adapter. The current supported PCI IDs are defined by qla2xxx_pci_tbl[] in the selected tree's legacy or newer qla2xxx source.
  2. Obtain firmware and any management utility from current vendor or distribution support for the exact PCI and board model. Do not treat the historical version recommendation in this document as current vendor policy.
  3. The ql2xfwloadbin module parameter controls whether the driver requests a firmware file, loads firmware from adapter flash or uses its default semantics. When file loading is selected, use the exact FW_FILE_* name defined by the selected tree's legacy or newer qla2xxx source. Do not rename an arbitrary firmware image according to a historical model table.
  4. If the approved deployment requires updating firmware stored in the HBA, follow the current vendor or distribution procedure for the exact board model. Perform the update in a maintenance window with a tested recovery plan. SCST does not define a universal HBA flash command.
  5. Install the current build prerequisites listed in INSTALL.md. Distribution package names and supported kernel versions change over time; the lists in that document and nightly/conf/nightly.conf are authoritative.
  6. Obtain a current SCST release or Git checkout as described by the project README. The remaining relative paths assume commands are run from the root of that source tree.
  7. The top-level build selects qla2x00t-32gbit, the newer QLogic tree, by default. Set QLA_32GBIT=no for both build and install only when selecting the alternative legacy qla2x00t tree. Do not mix an initiator/HBA module from one tree with the target adapter from the other.
  8. Unload the qla2xxx kernel module provided by your Linux distribution and blacklist it: 
    [root@proj ]# echo blacklist qla2xxx >/etc/modprobe.d/blacklist-qla2xxx.conf
[root@proj ]# rmmod qla2xxx
  9. Select the build mode from the source-tree root. For example, select the release mode before compiling: 
    [root@proj scst ]# make 2release
  10. Build and install SCST by following INSTALL.md. For a source build, keep BUILD_2X_MODULE=y, CONFIG_SCSI_QLA_FC=y and CONFIG_SCSI_QLA2XXX_TARGET=y consistent across the separate build and privileged install commands. Also keep the same QLA_32GBIT selection in both commands.
  11. Load only the modules required by the approved configuration, using the service or manual workflow documented in INSTALL.md. The qla2xxx_scst initiator/HBA module and qla2x00tgt target adapter must come from the same selected source tree. Do not use historical module sizes or log transcripts to validate the installation.
  12. If the approved deployment requires qla2xxx_scst in the initial RAM disk, back up the current image and follow the distribution's procedure for the exact installed kernel. Verify that the replacement modules are present before rebuilding and retain a bootable recovery entry. There is no portable SCST command that can safely select or replace an initial RAM disk.
  13. Now let's create our virtual device: 
    [root@proj ]# dd if=/dev/zero of=/mnt/disk1 bs=1024k count=512
512+0 records in
512+0 records out

[root@proj ]# ls -l /mnt/disk1
-rw-r--r--  1 root root 536870912 Jun 23 13:27 /mnt/disk1

[root@proj ]# file /mnt/disk1
/mnt/disk1: data
  14. The repository-wide source or package installation workflow includes scstadmin. Verify that the installed command matches the SCST version before applying the configuration below; do not perform a second uncoordinated installation from this HOWTO.
  15. Initiator and target modes

    The qla2xxx_scst module has parameter "qlini_mode", which determines when initiator mode will be enabled.
    Possible values:
    Usage of mode "disabled" is recommended, if you have incorrectly functioning your target's initiators, which if once seen a port in initiator mode, later refuse to see it as a target.

    qla2x00t (old qlogic driver):

    Use mode "enabled" if you need your QLA adapters to work in both initiator and target modes at the same time.
    You can always see which modes are currently active in active_mode sysfs attribute.
    In all the modes you can at any time use sysfs attribute ini_mode_force_reverse to force enable or disable initiator mode on any particular port. Setting this attribute to 1 will reverse current status of the initiator mode from enabled to disabled and vice versa.
    Changing ini_mode_force_reverse requests an ISP abort and waits for the HBA to return online.

    qla2x00t-32gbit (new qlogic driver):

    Use mode "dual" if you need your QLA adapters to work in both initiator and target modes at the same time. In this mode, each qlogic host has individual qlini_mode, ql2xexchoffld, ql2xiniexchg attributes that can be changed dynamically.
    For example, you can change qlini_mode to "disabled" for specific qlogic host: 
    echo "disabled" > /sys/class/scsi_host/host1/qlini_mode
    An accepted dynamic mode change can request an ISP abort, and some transitions are rejected while target mode is active. Check the target state and kernel log before and after changing the attribute.
  16. To see the device on the initiator we have to add it in the LUNs set of our target.
    We must have a LUN with number 0 (LUs numeration must not start from, e.g., 1).

    The simplest way to do that is to generate an scstadmin config file, e.g. as follows: WARNING: This template enumerates every discovered QLogic target port and maps LUN 0 without initiator groups. Restrict the generated targets and access controls before applying it. 
    {
cat <<EOF
HANDLER vdisk_fileio {
        DEVICE disk1 {
                filename /mnt/disk1
        }
}
EOF
for p in /sys/kernel/scst_tgt/targets/qla2x00t/*; do
[ -d $p ] || continue
cat <<EOF

TARGET_DRIVER qla2x00t {
        TARGET $(basename $p) {
                enabled 1

                LUN 0 disk1
        }
}
EOF
done
} >scst.conf
    Review the generated file against the current configuration, restrict its targets and initiators and preserve a backup before placing it at /etc/scst.conf. Do not replace an existing configuration by following an unreviewed example. Applying the file is a live operation that opens the backing file, maps the LUN and enables each configured target: 
    [root@proj ]# scstadmin -config /etc/scst.conf
    The same can be done directly via the sysfs interface of SCST: 
    [root@proj ]# echo "add_device disk1 filename=/mnt/disk1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
[root@proj ]# echo "add disk1 0" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/luns/mgmt
[root@proj ]# echo "1" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/enabled
  17. If you want to configure LUN masking the next step is to configure one initiator group per initiator. To do that you need to discover the initiator port WWNs. One way to discover these is as follows: 
    [root@proj ]# ls -d /sys/kernel/scst_tgt/targets/qla2x00t/*/sessions/*|sed 's,.*/,,' | sort -u
10:00:00:00:c9:95:c7:1a
10:00:00:00:c9:95:c7:1b
21:00:00:24:ff:46:c0:84
21:00:00:24:ff:46:c0:85
21:00:00:24:ff:6c:ca:d8
21:00:00:24:ff:6c:ca:d9
21:00:00:24:ff:6c:ca:da
21:00:00:24:ff:6c:ca:db
    More information about initiator group configuration together with an example can be found in the scst.conf man page.

INITIATOR SYSTEM

  1. After enabling the target mode on the target, to see new targets and devices on the initiator, use the discovery procedure for that initiator driver and the exact fabric port. Do not use a reboot or module unload as a generic discovery method: either can disrupt unrelated sessions and storage. A LIP or other fabric rediscovery is also a live operation and must be scoped to the intended port. If the initiator is already connected and only new LUNs were added, rescan the corresponding SCSI host as follows: 
    [root@initiator ]# echo "- - -" >/sys/class/scsi_host/hostX/scan
    where X is the host number.