iso2class Reference

Overview

The iso2class utility makes it easy to create new OS distros for AppLogic appliances. The iso2class utility is used to create a singleton class using an OS installed from an iso image. iso2class creates and starts an application which is used to install an operating system from an iso image onto a volume. This application is generated from a template and contains a singleton named iso2class. The boot volume of the singleton is an iso image. A second volume on the singleton is the target for the OS install. The end result is a singleton with a single volume which contains the installed OS. This singleton can be moved into a catalog and be used as the basis for creating new appliance classes.

Please see the Appliance OS Support Limitations topic for important information about the OSes that are supported in AppLogic.

iso2class has only been tested with very few OSes and originally was not made for general OS usage. 3tera is working to make iso2class more generic to work with a wide variety of OSes.

iso2class requires that the servers in the grid contain either Intel VT or AMD-V for hardware virtualization support (HVM). If HVM is not available on the grid, iso2class cannot be used.

Invocation

iso2class is invoked from the AppLogic command line shell using util iso2class. Help is displayed using help util iso2class. The following option=value arguments are required:

The following option=value pairs are optional:

Examples:

The following is used to install Ubuntu from a downloadable iso image:

util iso2class app_name=ubuntu_install install_size=3G console_type=graphic iso_volume1=http://mirrors.cat.pdx.edu/ubuntu-releases/hardy/ubuntu-8.04.1-desktop-i386.iso virt_options=acpi=1

The following command is used to install Windows Server 2003 from two existing global volumes named win2003-disk-1-iso and win2003-disk-2-iso

util iso2class app_name=win03_install install_size=3G console_type=graphic iso_volume1=_GLOBAL:win2003-disk-1-iso iso_volume2=_GLOBAL:win2003-disk-2-iso virt_options=acpi=1

The following command is used to install Open Solaris 2008.11:

util iso2class app_name=osol200811_install install_size=4G iso_volume1=_GLOBAL:os200811.iso console_type=graphic

The following command is used to install Solaris 10:

util iso2class app_name=sol10_install install_size=6G iso_volume1=_GLOBAL:sol10.iso console_type=graphic

ISOs used for OS installations in AppLogic

Creating new appliances in AppLogic for specific OSes requires the use of ISO images (cd-rom/DVD). The ISO is used to install the OS inside of an AppLogic appliance using the iso2class AppLogic utility. The ISO may be stored on the grid's impex volume, or a global volume or it may come from a remote website (via HTTP).

3tera has tested various ISOs downloaded from the web: Microsoft's website (trial versions of Windows 2003 Server), Ubuntu/Debian/CentOS 5. In addition, 3tera has tested Microsoft's SPLA Windows CD-ROMs (32-bit R2 Standard/Enterprise/Datacenter/Web editions). In order to use the SPLA Windows CD-ROMs to create Windows appliances, the ISO images must be created from the CD-ROMs so that they can be used with iso2class. Follow the instructions below to create an ISO from a CD-ROM for any OS distribution that you may want to use for your AppLogic appliances:

1. Attach a CD-ROM drive to one of your Linux-based servers (if needed) and insert the CD-ROM into the CD-ROM drive.
2. If the CD-ROM is mounted (check using the mount command), unmount the CD-ROM: umount /mnt/cdrom
   • Assumption: the CD-ROM device is referred to as /dev/cdrom on your Linux server
3. Run the following command: dd if=/dev/cdrom of=my-image.iso
   • This command makes a block-level copy of the CD-ROM into the specified ISO image file. The resulting ISO image file is an exact copy of the CD-ROM.
4. my-image.iso is now the ISO image you can use with iso2class to create your own Windows appliances. Typically this image is copied onto the grid's impex volume and imported as a global volume (vol import _GLOBAL:win03iso my-image.iso).
5. When using the iso2class utility, _GLOBAL:win03iso would be the ISO image to use for the OS installation.

3tera has only tested OS installations using the ISOs mentioned above. If the ISO images are generated in any other way (i.e., a 3rd party ISO ripping tool/application), the resulting ISOs may not work with AppLogic.

Graphical Console Access

The graphical console used during OS installations requires the latest version of Java in your IE/FF browser. 3tera has tested with Java version 6 update 7 on IE/FF. If the latest version of Java is not used, the graphical console may not work correctly (it will hang while trying to load). Before reporting graphical console errors to 3tera, be sure to check that you are using the latest Java version (if you need to upgrade java in your browser, be sure to re-open your browser afterwards in order for the graphical console to work correctly).

Operation

iso2class is an interactive utility which progresses through the following steps:

1. iso2class creates and starts the named application. This application includes a singleton containing a boot volume (the iso image) and a target volume for the OS install.
2. The user performs the OS install by accessing the console of the singleton iso2class within the application. To access the console, either:
   • Select the application within the application list in the AppLogic GUI. Next, click the icon for Login (text) or Login (graphic).
   • Or, open the application in the AppLogic editor. Select the singleton iso2class. Use the pull-down Appliance menu to select Login (text) or Login (graphic).
3. Only iso_volume1 is available during the install. If iso_volume2 or iso_volume3 or iso_volume4 was specified on the command line, the singleton is restarted, using the target volume of the OS install as the boot volume, and including the additional iso_volumes.
4. If installing a Windows OS, the user should install the Windows Server msi. For complete instructions on creating Windows appliances for AppLogic, see RefWindowsInstall.
5. Upon user confirmation of a completed installation, iso2class stops the application and requires user input to indicate how the finished appliance should be managed by AppLogic:
   • fully managed - the appliance has the appropriate APK installed. For Windows, the APK is included in the Windows Server msi.
   • unmanaged - the appliance has no APK installed (it uses field engineering code 4, does not send events to the AppLogic controller, does not auto-configure its interfaces, and does not obtain properties from its boundary configuration).
6. iso2class modifies the singleton as follows:
   • The target volume of the OS install os_install is made the boot volume of the singleton.
   • The external interface is disabled.
   • in, out, net and mon terminals are added.
   • The appropriate field engineering code is set.
7. The application is started.

The resulting singleton uses HVM virtualization (hardware emulation).

Important Operating System Specific Considerations

Windows

It may be required to access the external network during OS installation to: activate Windows, install security updates, install service packs, install tools or other software which you want to be present on any appliance derived from the iso2class singleton. The external interface (Local Area Connection) can be configured using either of these methods, given by example for Windows Server 2003:

1. Use the console to access Control Panel => Network Connections => Local Area Connection => Properties => Internet Protocol (TCP/IP) => Properties. Click on Use the following IP address and enter usable values for your grid (IP Address, netmask, gateway, DNS server).
2. Open a command shell and:
   • netsh interface ip set address name="Local Area Connection" static [ip-address] [netmask] [gateway] 1
   • netsh interface ip set dns name="Local Area Connection" static [dns-ip]

Windows msi files are included with AppLogic which transform a clean install of Windows 2003 SP2 into a managed appliance. To copy an msi file to the iso2class singleton:

• In a Windows command shell execute ipconfig /all and note the IP address of the DHCP server for the last enumerated connection (this always corresponds to the default interface). Note: the list may be displayed out of order.
• Using Internet Explorer, open the URL http://IP-address:8080/download/ to obtain a directory listing which includes the msi files.
• Right-click on one of the msi files and select Save Target As to download the file to the desktop.

When using iso2class to install Windows, you must specify the virt_options=acpi=1 command line option.

The Windows MSIs automatically install the APK in your Windows appliance.

Please see the Windows Installation Reference for detailed instructions on creating Windows appliances on your grid.

Linux

The following OS specific notes have been garnered from practical experience:

• SUSE Linux Enterprise Server (SLES) 11 does not recognize the cd-rom device during installation with iso2class. To work around this, configure the installer to use /dev/hdc for the source device of the installation.
• Ubuntu varients may automatically setup the default route on the internal interface. If this occurs, set the default route to the external interface with:
  • route del default
  • route add default gw IP eth0 where IP is the IP address of the gateway on the external interface

Do not install one of the AppLogic Linux based APK's during the iso2class OS installation. The iso2class singleton is HVM while the Linux APK's are intended to be used with PV appliances. If you wish to convert the HVM Linux singleton to a managed PV appliance, perform the initial OS installation to a single ext3 partition (do not use LVM which is the default on CentOS and Fedora).

After installing a Linux OS with iso2class, you can use the hvm2pv utility to convert the HVM appliance to a fully managed PV appliance which includes a Linux APK. See the hvm2pv documentation for details.

If you intend to convert an HVM Linux appliance to PV, pay particular attention to the section of the hvm2pv documentation titled Preparing for hvm2pv conversion.

Once an HVM Linux appliance is properly prepared as outlined in the hvm2pv documentation, it is possible to perform the conversion manually. There are two basic steps in the conversion process. First, strip the MBR from the resulting volume:

• Create a new application including a branched LUX5 (or LUX64 if your OS is 64-bit) with two placeholder volumes, src and dst
• Copy the boot volume of the iso2class singleton to the src volume of the new application.
• Create an ext3 dst volume of the same size or larger.
• Edit the ADL class descriptor of the singleton and change the device of the src volume from dev = /dev/hda3 to dev = /dev/hdc and click OK to save the change.
• Start the application and ssh into the singleton.
• Mount the src volume, e.g.: mkdir /src ; mount /dev/hdc1 /src
• Mount the dst volume, e.g.: mkdir /dst ; mount /dev/hda4 /dst
• Copy the installed OS: cd /src ; /usr/bin/find . -depth -mount -print | /bin/cpio -pdmu /dst

Second, install one of the Linux APK's on the file system mounted on /dst:

• Determine the IP address of the DHCP server for the internal interface of the branched LUX appliance: ifconfig -a and note the broadcast subnet of the last enumerated network interface, e.g. 10.47.255.255. The IP address for the DHCP server is identical except for the last number which is 254, e.g. 10.47.255.254.
• wget http://IP-address:8080/download/ to obtain a file index.html which lists all of the files downloadable from the controller, including the various APK's.
• Use wget again to download the appropriate APK and domu package.
• Follow the relevant APK installation document for your OS:
  • Appliance Kit User Manual
  • APK Installation for RedHat and CentOS Distributions
  • APK Installation for Ubuntu Distributions
• Use the resulting dst volume as the boot volume of a singleton.

Solaris 10

Install Solaris 10 using console=graphic. After the install is complete, logging in to either of the graphical desktops may fail; however, the text-based login from the graphic console succeeds. This is a problem with Solaris (not a bug in AppLogic).

OpenSolaris

An OpenSolaris 2008.11 appliance can be created with iso2class. Note that the resulting appliance uses hardware virtualization (HVM) and a ZFS pool as the boot volume. AppLogic does not support resizing a bootable ZFS volume using the Solaris filer.

If you would like to use paravirtualized OpenSolaris appliances, please use those distributed with AppLogic (they cannot be created using iso2class). These appliances use UFS boot volumes and the paravirtualized kernels.

Appliance access to files on the grid controller

Please see Accessing Files on the Grid Controller from within an Appliance for a list of files that are available to appliances through their default interface as described in the sections above as well as how to download them.

Notes

1. If an OS reboot is performed while a text or graphic console is open, that console becomes non-operational. Simply close the console window and open the console again to obtain the console of the newly booted image.
2. During the OS installation, when applicable, it is convenient to change the screen resolution to at least 800x600. Windows OS's will recommend changing the resolution after the first login.

-- StephenQ - 25 Aug 2008