Creating Appliances › Distribution Installations › Appliance Kit Installation For RedHat and CentOS Linux Distributions

Appliance Kit Installation For RedHat and CentOS Linux Distributions

Files

• apk-ver-linux-rh.tar.gz - the appliance kit
• domu-linux-lver.tar.gz - para-virtualized kernel and modules library

Compatibility

The apk-*-linux-rh versions are compatible with the following OS distros:

• Fedora Core (3 and later)
• Red Hat EL 4 and 5
• CentOS 4.x and CentOS 5.x.

To install APK you need either

• An old CA 3Tera AppLogic appliance image (with or without APK installed)
• A vanilla installation of the OS distro

The image must be with the ext3 file system, if the APK-provided kernel and initrd files will be used.

Prepare the image

Important! The Linux versions of APK support only PVM virtual machine setup, using the CA 3Tera AppLogic-provided build of the Linux kernel. The install script will erase any GRUB configuration file found on the target image, making it un-bootable in HVM mode. Saving the GRUB file (and not erasing the default OS kernel as documented below) may allow using APK on an HVM Linux domain, but this is not supported and is not guaranteed to work. In particular, clean appliance shutdown will not work in HVM mode, and neither will the automatic mounting of volumes according to the mount paths specified in the CA 3Tera AppLogic class descriptor.

The following steps may vary, depending on how the OS was originally installed. They are not performed by the APK setup script, and are left to the discretion of the administrator, because some of them are invasive and may be destructive, if accidentally done on a live system (rather than on the image being prepared) - therefore running them in an automated script may be inadvisable. Skip any steps that are not appropriate.

To prepare the image

1. Verify that the disk image is an ext3 file system.

   If the OS was installed as ext2, perform the following command to convert the image into ext3.

   tune2fs -j
   

   To use ext2 (or any filesystem other than ext3), the initrd file shipped with APK needs to be re-built.

2. Perform the following command to remove the network configuration files:

   rm /etc/sysconfig/network-scripts/ifcfg-eth* 
   

3. Edit the etc/fstab file and change the name of the root device to /dev/hda1.

   The installer will also check and print a warning if it finds the root device is specified by label or by UUID.

4. Perform the following command to delete the kernel package (skip this step if you are building an image to run in hardware-emulation mode).

   rpm --root path/to/image -e --nodeps kernel
   

   or, if doing this in a 'vol manage' shell:

   chroot  path/to/image rpm -e --nodeps kernel 
   

5. uninstall any OS services that will not be used

Note: After it is cleaned up, the volume may be shrunk to produce a smaller boot volume image for the appliance, however verify that at least 10-15MB of free space is left, to have space for installing the Xen DomU kernel and APK, and to have some headroom for log files, temporary files, and so on.

Install APK

The installation instructions given here assume that the APK installation is being done on an OS image that is not actually running, but has been prepared ahead of time, either by installing a clean OS, shutting it down and taking the boot disk image, or an existing CA 3Tera AppLogic appliance is being upgraded with a new version of APK.

Live install (on a running OS) is also possible, and can be used with the iso2class utility provided in CA 3Tera AppLogic Service Pack 2.4.5 and later. Note however that iso2class will create an HVM appliance for you, and APK does not work in HVM mode; the appliance has to be changed to Paravirtualized mode after APK is installed. To install on a live system, follow the steps below, but use / as the current directory for all operations. This is best done in a Xen virtual machine (for example, using 'iso2class'), doing this on a bare-metal system will result in an unbootable machine.

To install APK

1. Have the OS image mounted in your file system.

   If the image is already installed as a volume on an CA 3Tera AppLogic grid, it can be accessed using the vol manage command.

2. Copy the APK files to the /tmp directory on the image itself or to a temporary directory on the host where the image is mounted. If the image is already on a grid, copy the files to the image itself using the Web interface. (If not doing this on a grid: Note that the following operations must be done as user root)

Important: APK needs the dhclient package for its operation. It is not installed by default on CentOS5. Install the dhclient package on your image before installing APK.

The dhclient RPM can be installed on a non-live OS image (for example, mounted in the 'vol manage' shell), using chroot. The RPM should be available on any of the CentOS mirror sites (for example, http://mirror.stanford.edu/yum/pub/centos/5.1/os/i386/CentOS/dhclient-3.0.5-7.el5.i386.rpm)

To install the dhclient package

1. Un-pack the DomU kernel and the APK binary archive into the root directory of the image. The following is an example of the commands to perform::

   cd /mnt/vol 
   tar -zxf tmp/domu-linux-2.6.18.8.386.tar.gz # ** see note below! 
   tar -zxf tmp/apk-2.0.14-rh.tar.gz 
   

   The setup script will be unpacked into the ./tmp directory.

   Important! Use the correct domu-linux archive for your distro architecture. Installing a 32-bit kernel will not work on a 64-bit distro.

2. Run the following setup script:

   tmp/apk-install 
   

   The setup script (and the tar files, if they were copied to the image itself) can be removed now by performing the following command:

   rm tmp/apk-install tmp/domu-linux-*.tar.gz tmp/apk-*.tar.gz 
   

   Note: The APK-supplied init scripts no longer support appliance-specific scripts installed in "/appliance". If it is present, the install script will stop and prompt for user input. If no appliance-specific customization was done in this directory (that is, its contents are the same or similar to what is found on LUX), it is safe to delete it. All of the standard functionality that used to be installed there is now provided by APK. Otherwise, click save to /tmp and proceed with the installation.

3. Un-mount the image and import it to your CA 3Tera AppLogic grid (or close the vol manage shell, if the image was already on your grid and was edited using vol manage).
4. If the image was that of an existing appliance, perform the following:
   1. Edit the class (using the GUI editor) and remove the kernel and initrd file names.
   2. Set the configuration mode to dhcp.

Appliance Init Configuration

If the file /etc/sysconfig/applogic_init is present, the APK init script reads it as a shell include script (with the "." command). The following parameters can be defined in /etc/sysconfig/applogic_init:

 Important! The /etc/sysconfig/applogic_init file is executed before any configuration data is retrieved or applied, therefore the script cannot rely on the presence of any of the appliance's configuration files. Do not use this file for executing initialization code, only for the configuration variables defined above.

Example /etc/sysconfig/applogic_init:

APK_CONFIG_FILES=/etc/httpd/conf.d/myconfig.conf 
APK_AUTH_KEY_PATH=/root/.ssh/alternate_keys 

Appliance Post-start Check

If the file /etc/sysconfig/applogic_appliance is present, the APK late init script reads it as a shell include script (with the "." command), after all services on the appliance have been started. The return status from the script indicates whether the appliance is to be considered started OK or failed. If the script prints a message to stderr and returns an error, the last line from this message will be used as the error message sent to the controller.

Example post-start check file, for a web server appliance - verifies that the server is up and responds to HTTP GET to the home page:

if ! wget -q -O /dev/null http://localhost/ ; then
echo "start failed - Web server is not responding" >&2
return 1
fi
return 0

Important! Some appliances in the system catalog use a customized script located in /appliance to initialize services. This is no longer supported. This directory is deleted when APK is installed, to keep the root directory structure clean and compliant with the Filesystem Hierarchy Standard. One could move the code from such scripts to /etc/sysconfig/applogic_appliance , to emulate the old behavior but this is not the intention of the post-start check file and is not recommended. Instead, an installed service should have its own init script and in general should be able to operate entirely outside of CA 3Tera AppLogic.