Environment
NetIQ PlateSpin Migrate
Situation
Discovery of physical targets using the Linux RAM Disk (LRD) can fail if no drivers are available for devices such as NICS and storage controllers. While the LRD supports may common devices, it may be required to inject vendor specific drivers into the LRD. This documentation provides detailed steps in injecting the LRD with vendor provided drivers and setting up a proper environment to perform this disk using SUSE Linux Enterprise Server 11 SP 3.
Resolution
Build Environment Requirements
Recommended Linux Distribution
Injecting the drivers into the LRD requires a Linux based system. The LRD itself is Linux based and requires Linux based tools. Of the supported Linux distributions, it is recommended to use SUSE Linux Enterprise Server 11 Service Pack 3. The driver injection script requires a specific version of genisoimage that supports EFI.
Recommended configuration setting for the host Linux system
For the purposes of file transfer, it is recommended that ssh be enabled on the host system.
A Note on User Rights
The user performing the driver injection must have the ability to mount and unmount the LRD, therefore root privileges are required. Root privileges may be granted through the use of su or sudo depending on the environment. If the Linux host is in a lab environment then performing all actions described as root is acceptable. For other environments, use sudo or su as prescribed by your system policies. Steps that require root permissions are noted.
Installing SUSE Linux
Install SUSE Linux Enterprise Server as documented. See https://www.suse.com/documentation/sles11/index.html for the guides if required. Take the defaults for the installation. The required software packages are not included in the default installation, but will be installed.
Installing the GCC compiler and Linux kernel source
To build the Linux RAM Disk it is necessary to the Linux kernel source and the gcc compiler. To install the required packages follow these steps for SUSE Linux Enterprise Server.
1. From the GNOME menu open the Install/Remove software application. (Or open YaST and open the Software Management application.)
2. From the view drop down select Patterns.
3. Select C/C++ Compiler and Tools located under Development.
3. From the view drop down select Search.
4. Search for Kernel.
5. Select kernel-default-devel, kernel-source and linux-kernel-headers. Note: If installing a different distribution, install the appropriate packages required to build a kernel from source.
6. Select Accept to install the required packages.
Creating the Build Environment
Recommended Directory Structure
The following directory structure is recommended for this task:
PlateSpin/ - The build environment base directory.
PlateSpin/ISO – Storage location of the LRD ISO file.
PlateSpin/Drivers – Storage location of the drivers.
PlateSpin/Tools – Storage location of files copied from the LRD ISO file.
PlateSpin/lib – Storage location of the extracted drivers.
PlateSpin/bin – Storage location for files copied from the LRD ISO.
PlateSpin/mnt – Temporary mount point used when copying files to the PlateSpin\bin directory.
Note: PlateSpin/ can be created in a location that doesn’t require root access. Root access is only needed to execute the rebuildiso.sh script and to mount the LRD ISO.
Creating the directory structure
The directory structure can be created in a single mkdir command as shown below:
mkdir PlateSpin/{,ISO,Drivers,lib,bin,mnt}
The resulting directory structure should look like this:
PlateSpin/
├── bin
├── Drivers
├── ISO
├── lib
├── mnt
Downloading the Required Files
Obtaining the Hardware Drivers
Download the required files from your hardware vendor. The current LRD uses SUSE Linux Enterprise Server SLES 11 SP3 as its base. The drivers downloaded should support SLES 11 SP3. Contact your vendor for assistance downloading if required.
Save the drivers in the PlateSpin/Drivers directory.
Downloading the Linux Ram Disk
This document assumes that the Linux Ram Disk has been downloaded from https://dl.netiq.com. In case another or new download of the site is required follow these steps:
1. Login at https://dl.netiq.com,
2. On the basic search tab, select PlateSpin Migrate and version as search parameters and submit the query,
3. Click on PlateSpin Migrate in the results.
4. Verify the product information returned in the results and click on, “proceed to download”.
5. Read the Export Laws and Regulations information.
6. Click “accept”
7. Click on the “download” button to the right of the Physical Target zip file and save it in the PlateSpin/ISO directory created in “Creating the Build Environment”.
Extracting the Downloaded Files
Extracting the Linux Ram Disk
Linux includes a utility to extract the contents of zip files. If the file was saved in another directory, use the cp or mv commands to copy or move the file to PlateSpin\ISO. Use the cd command to change to the PlateSpin\ISO directory and execute and extract the ISO from the zip file:
cd PlateSpin/ISO
unzip PhysicalTarget-12.1.zip
Note: This example assumes that the LRD is in the PhysicalTarget-12.1.zip file.
Extracting the Required Drivers
Both Red Hat Linux and SUSE Linux Enterprise Server package their driver files in RPM packages. The tools rpm2cpio and cpio may be used to extract the driver files. rpm2cpio converts the RPM file to a cpio file. The cpio file is then extracted using cpio. cpio will duplicate the directory structure required as if the RPM file was installed on the server. Normally this directory structure would be located in /lib/modules under a directory that corresponds with the kernel version. For the purposes of driver injection, the output of cpio should go into PlateSpin/lib.
For each of the RPM packages that were downloaded follow the following steps to extract the required files:
1. Change directories cd to the PlateSpin/ directory.
2. Execute the following command to convert each RPM file and extract the drivers:
rpm2cpio Drivers/some_rpm_file.rpm | cpio -idmv
3. Execute ls -r lib/ from the PlateSpin/ directory. lib/ should now contain the files and directories extracted by cpio.
Note: The driver files themselves are kernel modules and the file names have the suffix of .ko. There is no need to move the kernel modules from their location. The rebuildiso.sh script will locate the kernel modules.
Mounting the LRD ISO
Mounting the LRD ISO does require root privileges using sudo or su will be required for users other than root.
The LRD ISO should now be mounted to copy the required files from the tools/ directory. With root privileges from the PlateSpin/ directory execute the following command:
mount ISO/bootofx.x2p.iso mnt/
Copying the Injection Tools to PlateSpin/bin
The rebuildiso.sh script and required files should be copied from the tools directory of the mounted ISO file and placed into PlateSpin/bin. Execute the following from the PlateSpin/ directory:
cp -R mnt/tools/* bin/
Once the required files are copied to PlateSpin/bin, The ISO file may be unmounted using:
umount ISO/bootofx.x2p.iso mnt/
Setting Permissions on the rebuildiso.sh Script
Execute commands in this section with root privileges via su or sudo.
The rebuildiso.sh script requires execute permissions to run. From the PlateSpin/bin directory change the file permissions:
cd bin/
chmod u+x rebuildiso.sh
Injecting the drivers into the LRD ISO
Execution of the rebuildiso.sh script will create a new LRD ISO and inject the drivers during the build process. Running the rebuildiso.sh script with no parameters provides information on the required options. The required parameters are:
-i [ iso file ] - location and file name of the LRD ISO file
-m64 or -m32 – specifies the machine architecture
-d [driver directory] - location of the files extracted from the RPM(s).
From the PlateSpin/ directory execute the following command:
bin/rebuildiso.sh -i ISO/bootofx.x2p.iso -d Drivers/ -m64
Once the script is executed, the ISO file is mounted and the new modules are injected into the LRD. The original LRD is retained as bootofx.x2p.iso.bak and the newly created LRD is named bootofx.x2p.iso. The injection process is complete. The new bootofx.x2p.iso may be burned to media.
To add additional modules to the disk in the future, remove the old driver files and repeat the steps to extract the kernel module(s) from the RPM packages and delete the bootofx.x2p.iso.bak file. The drivers will be injected into bootofx.x2p.iso and new bootofx.x2p.iso.bak will be created.
Recommended Linux Distribution
Injecting the drivers into the LRD requires a Linux based system. The LRD itself is Linux based and requires Linux based tools. Of the supported Linux distributions, it is recommended to use SUSE Linux Enterprise Server 11 Service Pack 3. The driver injection script requires a specific version of genisoimage that supports EFI.
Recommended configuration setting for the host Linux system
For the purposes of file transfer, it is recommended that ssh be enabled on the host system.
A Note on User Rights
The user performing the driver injection must have the ability to mount and unmount the LRD, therefore root privileges are required. Root privileges may be granted through the use of su or sudo depending on the environment. If the Linux host is in a lab environment then performing all actions described as root is acceptable. For other environments, use sudo or su as prescribed by your system policies. Steps that require root permissions are noted.
Installing SUSE Linux
Install SUSE Linux Enterprise Server as documented. See https://www.suse.com/documentation/sles11/index.html for the guides if required. Take the defaults for the installation. The required software packages are not included in the default installation, but will be installed.
Installing the GCC compiler and Linux kernel source
To build the Linux RAM Disk it is necessary to the Linux kernel source and the gcc compiler. To install the required packages follow these steps for SUSE Linux Enterprise Server.
1. From the GNOME menu open the Install/Remove software application. (Or open YaST and open the Software Management application.)
2. From the view drop down select Patterns.
3. Select C/C++ Compiler and Tools located under Development.
3. From the view drop down select Search.
4. Search for Kernel.
5. Select kernel-default-devel, kernel-source and linux-kernel-headers. Note: If installing a different distribution, install the appropriate packages required to build a kernel from source.
6. Select Accept to install the required packages.
Creating the Build Environment
Recommended Directory Structure
The following directory structure is recommended for this task:
PlateSpin/ - The build environment base directory.
PlateSpin/ISO – Storage location of the LRD ISO file.
PlateSpin/Drivers – Storage location of the drivers.
PlateSpin/Tools – Storage location of files copied from the LRD ISO file.
PlateSpin/lib – Storage location of the extracted drivers.
PlateSpin/bin – Storage location for files copied from the LRD ISO.
PlateSpin/mnt – Temporary mount point used when copying files to the PlateSpin\bin directory.
Note: PlateSpin/ can be created in a location that doesn’t require root access. Root access is only needed to execute the rebuildiso.sh script and to mount the LRD ISO.
Creating the directory structure
The directory structure can be created in a single mkdir command as shown below:
mkdir PlateSpin/{,ISO,Drivers,lib,bin,mnt}
The resulting directory structure should look like this:
PlateSpin/
├── bin
├── Drivers
├── ISO
├── lib
├── mnt
Downloading the Required Files
Obtaining the Hardware Drivers
Download the required files from your hardware vendor. The current LRD uses SUSE Linux Enterprise Server SLES 11 SP3 as its base. The drivers downloaded should support SLES 11 SP3. Contact your vendor for assistance downloading if required.
Save the drivers in the PlateSpin/Drivers directory.
Downloading the Linux Ram Disk
This document assumes that the Linux Ram Disk has been downloaded from https://dl.netiq.com. In case another or new download of the site is required follow these steps:
1. Login at https://dl.netiq.com,
2. On the basic search tab, select PlateSpin Migrate and version as search parameters and submit the query,
3. Click on PlateSpin Migrate in the results.
4. Verify the product information returned in the results and click on, “proceed to download”.
5. Read the Export Laws and Regulations information.
6. Click “accept”
7. Click on the “download” button to the right of the Physical Target zip file and save it in the PlateSpin/ISO directory created in “Creating the Build Environment”.
Extracting the Downloaded Files
Extracting the Linux Ram Disk
Linux includes a utility to extract the contents of zip files. If the file was saved in another directory, use the cp or mv commands to copy or move the file to PlateSpin\ISO. Use the cd command to change to the PlateSpin\ISO directory and execute and extract the ISO from the zip file:
cd PlateSpin/ISO
unzip PhysicalTarget-12.1.zip
Note: This example assumes that the LRD is in the PhysicalTarget-12.1.zip file.
Extracting the Required Drivers
Both Red Hat Linux and SUSE Linux Enterprise Server package their driver files in RPM packages. The tools rpm2cpio and cpio may be used to extract the driver files. rpm2cpio converts the RPM file to a cpio file. The cpio file is then extracted using cpio. cpio will duplicate the directory structure required as if the RPM file was installed on the server. Normally this directory structure would be located in /lib/modules under a directory that corresponds with the kernel version. For the purposes of driver injection, the output of cpio should go into PlateSpin/lib.
For each of the RPM packages that were downloaded follow the following steps to extract the required files:
1. Change directories cd to the PlateSpin/ directory.
2. Execute the following command to convert each RPM file and extract the drivers:
rpm2cpio Drivers/some_rpm_file.rpm | cpio -idmv
3. Execute ls -r lib/ from the PlateSpin/ directory. lib/ should now contain the files and directories extracted by cpio.
Note: The driver files themselves are kernel modules and the file names have the suffix of .ko. There is no need to move the kernel modules from their location. The rebuildiso.sh script will locate the kernel modules.
Mounting the LRD ISO
Mounting the LRD ISO does require root privileges using sudo or su will be required for users other than root.
The LRD ISO should now be mounted to copy the required files from the tools/ directory. With root privileges from the PlateSpin/ directory execute the following command:
mount ISO/bootofx.x2p.iso mnt/
Copying the Injection Tools to PlateSpin/bin
The rebuildiso.sh script and required files should be copied from the tools directory of the mounted ISO file and placed into PlateSpin/bin. Execute the following from the PlateSpin/ directory:
cp -R mnt/tools/* bin/
Once the required files are copied to PlateSpin/bin, The ISO file may be unmounted using:
umount ISO/bootofx.x2p.iso mnt/
Setting Permissions on the rebuildiso.sh Script
Execute commands in this section with root privileges via su or sudo.
The rebuildiso.sh script requires execute permissions to run. From the PlateSpin/bin directory change the file permissions:
cd bin/
chmod u+x rebuildiso.sh
Injecting the drivers into the LRD ISO
Execution of the rebuildiso.sh script will create a new LRD ISO and inject the drivers during the build process. Running the rebuildiso.sh script with no parameters provides information on the required options. The required parameters are:
-i [ iso file ] - location and file name of the LRD ISO file
-m64 or -m32 – specifies the machine architecture
-d [driver directory] - location of the files extracted from the RPM(s).
From the PlateSpin/ directory execute the following command:
bin/rebuildiso.sh -i ISO/bootofx.x2p.iso -d Drivers/ -m64
Once the script is executed, the ISO file is mounted and the new modules are injected into the LRD. The original LRD is retained as bootofx.x2p.iso.bak and the newly created LRD is named bootofx.x2p.iso. The injection process is complete. The new bootofx.x2p.iso may be burned to media.
To add additional modules to the disk in the future, remove the old driver files and repeat the steps to extract the kernel module(s) from the RPM packages and delete the bootofx.x2p.iso.bak file. The drivers will be injected into bootofx.x2p.iso and new bootofx.x2p.iso.bak will be created.