Appliance Kit User Manual

Overview

APK is a package of tools and runtime for creating AppLogic appliances out of OS installations. It contains scripts and utilities that help implement the appliance boundary, as well as a set of tools to assist appliance developers in preparing appliances.

Description

APK includes:

• user manual (this document):
  • appliance boundary definition (what makes a VM an AppLogic appliance)
  • appliance cookbook (how to build and customize appliances)

• installation guide (separate documents, one per supported target OS)
  • Installation Guide for RedHat and CentOS Linux Distributions
  • Installation guide for Ubuntu Linux Distributions
  • Installation guide for Open Solaris and Solaris 10 Distributions
  • Installation guide for Windows 2003 Server (all varieties)

• binary archive (one per supported target), including an install script. The binary archives can be found within the AppLogic release folder on the ALDO server.

• The APK installation supports:
  • creating appliances from physical server installs or from VMware/Xen images,
  • upgrading old-style (volfix) AppLogic appliances to APK
    • please see the following topic for how to upgrade your old-style appliances to use APK: VolfixDHCPConversion
  • upgrading new-style (APK) appliances to a newer version of APK

APK can be installed either on a boot volume image mounted into a subdirectory, or on a live appliance. The following software is installed by APK:

• All platforms:
  • initialization script - sets up the network as necessary for the OS to operate as an appliance and starts the AppLogic-specific services (VMA and CCA).
  • Virtual Machine Agent (VMA), including a command to send events to the controller
  • Counter Collection Agent (CCA). CCA is started only if the appliance has a configured 'mon' terminal and the terminal is connected.
• for Linux, a pre-compiled para-virtualized kernel is also provided as a separate archive.

See the following section for how to download the APK from within your appliances.

Appliance Boundary

This chapter explains in detail what is an AppLogic appliance.

Overview / General

An AppLogic virtual appliance (or simply, appliance, in the text below) is an instance of an OS installation or another self-contained executable entity that can run as an i386 (or x86_64) virtual machine and has the following characteristics:

• the executable code is contained on one or more volume images, formatted either as a PC x86 bootable hard disk or as single disk partitions;
• configures itself (network, properties, etc) using the dhcp-based protocol described below;
• upon startup, reports success/failure to the AppLogic grid, using a utility provided for this purpose by 3tera;
• if used as part of an AppLogic application, communicates with other appliances using peer-to-peer IPv4 connections - the AppLogic equivalent of a direct link between two Ethernet ports;
• all configurable settings of the appliance are in the form of properties - that is, named parameters, each one with a defined type chosen from the types supported by AppLogic and optionally a defined range of valid values. The property types currently supported by AppLogic are: string, integer, IP address.

(Note: AppLogic also supports a 'legacy' appliance, which is not configured over the network and requires its volumes to be modified off line prior to start. This type of appliance isn't covered by the present document).

Exterior Boundary

This section defines how the appliance looks to the "outside world" - that is, to the grid controller and to other appliances on the grid. The "exterior boundary" is implemented mostly by APK, the appliance designer does not need to do much beyond installing APK in order to make the OS behave like an AppLogic appliance.

Boot File Locations (PVM appliances only)

A para-virtualized (PVM) appliance is one that has been configured with a virtualization-aware OS kernel, and uses the XEN hypervisor APIs for access to all hardware (console, memory, disk, network).

A para-virtualized appliance must have its initial executable image in the form of a statically-linked ELF file, optionally compressed with gzip. The initial executable is usually the OS kernel. The appliance may also use one or more additional binaries loaded into memory at boot time (e.g., an initial ramdisk).

The locations of the initial executable and any other optional binaries must be defined in a file stored on the appliance's boot volume, and named either /boot/grub/grub.conf or /boot/grub/menu.lst. The file format is that of the GRUB configuration file (e.g., see man 8 grub). The files referred to in the grub configuration file are relative to the boot disk's file system and must be on the boot disk image itself. Note that the GRUB binary itself need not be present - it is not used to boot a para-virtualized appliance.

Booting para-virtualized appliances is limited to the same file system formats as the ones supported by GRUB (i.e., ext2/3, fat, ufs, reiserfs, minix, xfs, jfs).

Network Configuration

An appliance uses its last network interface (the one appearing last in a network device discovery scan) as the service interface, used to configure itself and to communicate with the AppLogic grid. This interface is referred to in AppLogic documentation as the 'default' interface.

Upon startup, an appliance configures itself as follows:

• set up the default interface and request DHCP configuration for it
• the DHCP response will contain the network parameters for the interface, plus a file name (in the filename DHCP option).
• retrieve the following files using HTTP requests to port 8080 sent to the address of the server that responded to the DHCP request ($filename is the name received in the DHCP response):
  $filename.net
  $filename.desc
  $filename.ext
• use the data contained in the retrieved files to configure itself and begin normal operation. Note that except for the DHCP-configured default interface and the local loopback interface, the appliance's network is set up entirely according to data provided in the $filename.net configuration file (and not using any OS-specific network configuration data stored on the appliance itself).

The format of the configuration files that the appliance receives from the AppLogic grid is described in the Appendix. Note that in most cases the appliance designer need not be concerned with the format of these files, as the APK initialization scripts take care to interpret them and configure the appliance accordingly. For appliances that have configurable properties, APK provides their values in various easy to use 'cooked' formats which can be read by the appliance-specific code. Also, in many cases it is possible to instruct APK to modify appliance-specific configuration files on startup and insert the values of the appliance's properties into them at the right places. See the Interior Boundary section further below.

VM Agent and Boot Completion Report

After it has configured its network, the appliance starts the VM Agent (a binary executable provided by APK), which opens a service connection to the AppLogic infrastructure, using a 3tera proprietary binary protocol.

When the boot is completed, the appliance uses the service connection to report success or failure. APK provides the necessary tools to the appliance designer to add customized code to check if the appliance started OK and report status to the grid. If failure is reported, or if the appliance fails to contact the grid altogether, the appliance start is considered un-successful and the virtual machine (and possibly the entire application in which this appliance participates) is shut down.

Interior Boundary

This section describes the AppLogic-specific services that APK provides for use within the appliance OS itself.

An appliance is not required to use any of these services. Only the "exterior" boundary (implemented by APK and described above) is what defines an appliance as far as AppLogic is concerned. The "interior boundary" services are provided to help adapt an existing generic service (e.g., firewall, a mail server, or Web server program) for use as a self-contained virtual appliance running in AppLogic.

Boot Status Check/Report

By default, when the appliance boot process completes, the APK initialization code sends a "boot completed" notification using the service connection established by the VM Agent.

This is used by the grid as a signal that the appliance started successfully.

The appliance can be equipped with an optional "boot check" script, which is run on completion of the OS startup and can check (in some appliance-specific way) whether the appliance is initialized correctly and is ready to operate. For example, if the appliance is an HTTP server, the script might attempt to make a request to the HTTP port on the local host to verify that the HTTP daemon is operational.

The boot check script is a shell script named applogic_appliance (stored in an OS-specific location - see the install guides), ran as a shell "include file" (e.g., with the "." command for a Posix shell). It is expected to return a success / failure status and optionally print an error message to the standard error stream (stderr).

Log Messages

Code on the appliance may report info, warning or error messages to be posted in the grid system log.

APK provides the 'vme' command for this purpose. It should be invoked with the following command line syntax.

   vme id=log msg='text'

Note that if the message text contains spaces or other meta-characters, it has to be quoted appropriately.

Network Access - Terminals

Communication between appliances in AppLogic is over peer-to-peer IP connections. The endpoints of these connections are referred to as terminals. This is somewhat different from the "usual" setup of a multi-device network application, where most devices may be connected to a common bus (e.g., an Ethernet switch) and each appliance may connect (or mis-connect) to any other appliance on the same bus.

In contrast, AppLogic uses a separate "virtual wire" for each connection (equivalent to a port-to-port Ethernet cable between two network devices) and ensures that traffic goes only along those wires. This is made possible by the fact that the AppLogic virtual appliances are not limited by a fixed number of physical connection ports and can therefore dedicate a separate "virtual terminal" for each connection.

There are two logical types of terminals:

• input terminal : a terminal on which the appliance provides a specific service (i.e, acts as a server).
• output terminal : a terminal that an appliance uses to request a service from another appliance (i.e, acts as a client).

An input terminal can have any number of output terminals connected to it. An output terminal can be connected to a single input terminal. Either kind of terminal may remain unconnected. An application designer may specify that an output terminal is "mandatory", i.e., the appliance requires the service provided on it and will not work without it being connected.

APK automatically configures the network settings for the virtual network interfaces used as terminals. It makes the terminals visible to the appliance code by name (providing the name resolution and the necessary IP routes), as follows:

• a connected output's name resolves to the address of the appliance that is connected on the other side, that is, the address to which the terminal name resolves can be used directly to request a connection. For example, if the appliance has an output terminal named 'web', connectible to an http server, one might do the equivalent of a command like this:
  wget http://web/some-page.html
• an input terminal's name resolves to the IP address of the terminal itself, thus allowing one to use the name when configuring a server, e.g., if the appliance has an input terminal named 'in' that is supposed to respond to HTTP requests, one might add this directive to the Apache configuration file:
  Listen in:80

An output terminal that is not connected will have its name resolve to an invalid IP address: 0.255.255.255. An appliance that is designed to have optional outputs (which may be left unconnected) should recognize this, or be prepared to handle gracefully the "invalid address" error on an attempt to connect.

Network Access - Gateway Terminal

A gateway terminal is a special case of an output terminal (as described above). An appliance can have at most one gateway terminal. It is configured as regular output terminal in that the name resolves to the remote peer. In addition:

• the default route is set to be via the peer address to which the terminal is connected, so that connections to any address other than those belonging to regular terminals or those used by the 'default' interface (the AppLogic internal service network) are routed via the gateway output.
• the DNS nameserver is set to the gateway terminal's peer address

Thus, an appliance with a gateway terminal can operate like a device connected to a "regular" LAN, intranet or WAN, within the limits of whatever name resolution and routing is provided by the "gateway" appliance connected to the terminal. (AppLogic provides ready-made appliances that act as gateways, including one that provides un-restricted outgoing access to the Internet).

Properties

AppLogic provides configuration for appliances in the form of properties (named configuration strings). An appliance receives its configured properties on startup in the configuration files retrieved from the DHCP server (see the Exterior Boundary section above).

APK is responsible to retrieve the configuration files and it provides the appliance properties in several formats. Any or all of these formats can be used by the appliance-specific code to read its configuration data. In addition, APK can be instructed (during installation) to use the received property values to update one or more files on the appliance (see the next sub-section - Automatic Configuration File Update).

APK provides the property values in the following formats. The file names for each format are provided in parentheses. The location of the files in the appliance file system is OS-specific (see the install guide for each OS).

• raw (appliance.conf) : a text file, containing one property value per line. Each line starts with the property name, followed by a single space character and the property value extending to the end of the line. The values are provided verbatim, with no meta-character quoting of any kind. The "raw" format is suitable for reading with the Posix shell's 'read' command, or with read() or scanf() from binary code.
• Posix shell (appliance.sh) : a text file, suitable for being included by a Bourne or Posix compatible shell script, with the "." command. Each property is defined as an exported shell variable, prefixed with the underscore character (to avoid name conflicts with common shell variables).
• C shell (appliance.csh) : a text file, suitable for being included by a a C-shell script. Each property is defined as an exported shell variable, prefixed with the underscore character.

Automatic Configuration File Update

In many cases, the appliance properties correspond directly to strings that need to be inserted into an appliance-specific configuration file. In such cases, rather than writing code to read one of the APK-provided property files (described above) and generate the appropriate configuration files on each boot, it is possible to instruct APK to apply the property values directly to the configuration file(s). This can be done in all cases where the following conditions are met:

• the appliance has a writable disk volume (i.e., this method is not suitable for an appliance whose volumes are all read-only)
• the property value needs to be simply inserted into the configuration file
• the configuration file is a text file
• the configuration file format allows for adding comments to it, and the program(s) using it either do not modify the file, or re-write it keeping the comments intact.

To set up APK to do automatic config file updates on boot:

• the configuration file(s) are "instrumented" with special comments that specify exactly where the property values are to be inserted. The instrumentation syntax is can be found here: http://doc.3tera.net/AppLogic2/AdvADLPropertyMarkup.html
• The list of files to be updated is configured in the APK_CONFIG_FILES setting in the applogic_init config file.

Appliance Cookbook

This chapter has step-by-step recipes for creating several kinds of appliances and is intended to serve as a tutorial and as a source of examples to be emulated when building new appliances.

The following recipes are included:

• building a "blank" appliance template (basic OS installation, with no specific functionality) from scratch. This is primarily useful for creating a few non-specialized templates which can later be re-used and configured for a specific purpose. Since a few such ready-made basic templates are provided in the AppLogic system catalog, this recipe is intended mostly for use when porting APK to a new OS type for which there is no ready appliance in the catalog.
• Creating a "virtual private server" (VPS) appliance - a virtual machine that is not intended to interact with other appliances and be part of a multi-tier application, but rather serve as the equivalent of a private hosted server, with a single Internet-accessible network interface.
• Building a fast-boot mini-appliance, based entirely on a read-only volume. This use case is suitable for creating various "filter" type virtual devices that do not store persistently any data, like WAN routers, firewalls, load balancers, etc. This recipe is specific to the Linux OS, which is generally well-suited to operate in an embedded environment with a read-only boot volume.

Blank Appliance

OS Install

The first step of this recipe is to prepare a vanilla OS installation. This can be done outside of AppLogic, if desired, however in the example given here the iso2class utility command available in AppLogic will be used to have the OS installed directly into a virtual machine.

Prepare the install media for the new OS: either have it available via http or ftp (e.g., could be a Linux distro directly from one of the public mirrors that hosts the ISO image), or copy the ISO image to the grid using sftp. In the latter case, store it in the /_impex directory on the grid controller.

Enter this command (modified as needed) at the AppLogic shell prompt:

util iso2class app_name=my_new_os install_size=1G console_type=graphic iso_volume1=url-or-filename mem=512M

Use 'help util iso2class' to see all the options for the command, e.g., if more than one install media image is needed or if login is required to access the image on the web.

The iso2class utility command will create and start a new application, containing a single virtual appliance, which will boot from the given install media image. Once the application starts, open a graphical VNC console to it from the Applications tab in the AppLogic user interface. Even though the console is an emulated VGA with graphical capabilities, it is advisable to choose text-based install, if the OS provides one, especially if know that the GUI install is overly dependent on mouse usage. The mouse doesn't work very well over VNC.

Do the OS install according to taste, taking care not to install more than could fit on the small volumes that were prepared for it. Keep the following in mind:

• ( Important, verify this after the OS install!) SSH server must be installed and set up to start on boot. It should have public key authentication enabled and root logins allowed. A version of the SSH server that is compatible with the OpenSSH format of authentication keys is necessary. See the appropriate APK install guide for any OS-specific notes regarding SSH setup. Note that to keep your OS safe, APK will automatically disable password-based SSH logins for root (applies to OpenSSH server only, if you have a different kind, it is recommended to disable password-based logins by ssh manually).
• do not set up more than one partition.
• use of swap partitions is not recommended for appliances, but if desired, leave that step for later (when the image is ready and proven to run under AppLogic). Do not set up swap partitions during install.
• the virtual appliance will start with two network adapters. Always leave the second one to be configured automatically by DHCP. If Internet access is needed, use the first of the network adapters and set it up with the bare minimum configuration necessary. If there is no need to access the Internet during installation, just leave the OS installer to configure the network automatically via DHCP. Note that any manual network setup done during install will not be kept beyond the install phase - once the image is ready, its network will be configured by APK.
• do not install graphical tools / GUI, if at all possible. This will be a headless appliance, not a desktop

Once the install is done, let the installer shut down the VM and reset it. It should reboot and start up with at least one of the network interfaces up and configured. Note that the graphical console window may need to be closed and re-started.

Once the new OS is up and running, APK can be installed. Use the OS-provided tools to find out the IP address of the DHCP server that configured the second network interface; it should be in the form 10.x.255.254. This will be the IP address of the grid controller, from which APK can be downloaded into your new OS and installed.

Use the OS-provided browser (at worst, you should have lynx), or if even that is not available, use wget. The list of download-able files provided with AppLogic can be found by opening this url from the newly-installed OS (use the IP address found above): http://10.x.255.254:8080/download/.

Refer to the OS-specific APK installation guide to see which file(s) should be downloaded and installed. Follow any other instructions there on how to configure the OS for use as a virtual appliance and how to set up APK.

When the setup is completed, shut down the OS and follow the prompts of the iso2class command - it will be waiting for confirmation that the OS install is done and then prompt for some additional information to complete the process.

IMPORTANT note for Linux installs with the iso2class utility command:

the Linux versions of APK support only the para-virtual kernel. However iso2class creates an HVM class. If APK is installed during the OS setup while 'iso2class' is still running, the application will fail to restart.

In addition, the boot volume of the application will be configured as a complete disk image, with a master boot record (MBR). While the volume is valid for booting the OS, the AppLogic volume management commands cannot operate on it at the file level - commands like resize, fsck and others will not work.

These problems are present in the 2.4 series of AppLogic versions, up to and including 2.4.5.

To get the new OS running under AppLogic, it must be converted to PV mode, as follows:

• open the application in the editor and change it to 'Paravirtualized' mode (Modify Boundary -> General -> Options).
• also, set the boot device name to be "/dev/hda" (TBD; BUG: currently, the editor controls do not allow choosing /dev/hda as the device name; use the ADL Class Descriptor item in the Appliance menu to edit the descriptor manually; find the line 'volume os_install' and change the value of dev to read 'dev = /dev/hda').
• the new application can now be started and should work normally

To make the application's boot volume manageable with the AppLogic vol management commands, it should be converted to a plain partition image, without a master boot record. Use the following steps to do this: * use the editor to create a blank data volume in the new appliance (after is is successfully made to work in PV mode, as described above), make it large enough to hold the OS. This is also an opportunity to adjust the size chosen in the initial install, if needed. * edit the appliance boundary and add a new placeholder volume, with a device name /dev/hdb1, set the mount path to /mnt. * attach the new blank volume to the new placeholder configure the placeholder volume (Appliance -> User Volumes) * start the application and log into the appliance. Copy the entire OS boot volume to the new blank volume, e.g.:
cd / ; find . -xdev | cpio -p /mnt * stop the application * from the AppLogic shell: remove the boot volume and put the newly-created blank volume in its place:
vol destroy myapp:iso2class.os_install
vol rename myapp:blankvol iso2class.os_install * in the editor: open the "modify boundary" dialog again, remove the placeholder volume and change the boot volume's device name to /dev/hda1.

Creating a VPS Template

This recipe builds on the "Blank Appliance" one, and adds the following customizations, appropriate for using the appliance as a general purpose virtual server:

• an internet-accessible network interface
• secondary SSH login with its own configuration file and access key setup, independent of the automatic setup performed by APK for the benefit of the 'ssh' command of the AppLogic shell.
• configuration properties to facilitate the use of the VPS appliance class for easy provisioning (I.e., simple/automated making of copies of the VPS to rent out to clients).

The first step is to create the OS image for the future VPS template. The "Blank Appliance" recipe described above can be used, or one can start from an existing blank appliance class. Here is what needs to be set up differently:

• larger disk volume, with more software pre-installed
• the appliance class will not become a catalog class, instead the entire application containing the VPS component is saved as a template.
• the root password is set to empty before saving the application as a template - this is used as an indication to the startup script to initialize the password (see the next section for more on root password configuration).
• the 'external' interface is enabled in the component descriptor (Edit Class -> Interfaces, External interface).

VPS Server Configuration

The following standard properties should be defined for any VPS server appliance and exported to the application boundary, so that they can be configured with the 'app configure' command or the 'app provision' command:

(VPS templates provided with AppLogic also have these properties, which allow creating an initial user account: user, user_pw)

The appliance should be outfitted with a startup script that runs immediately after the APK startup script (applogic_init) and before the ssh server starts (important to keep the initial password setup safe). This script is responsible for applying the VPS configuration properties in an OS-specific manner, as outlined in the above table.

Setting up two SSH server instances

In this step we set up a secondary SSH sever, so that the VPS is accessible both to the client that rents it, and to the provider of the VPS (as well as to maintainers of the AppLogic grid itself), while each SSH instance maintains its own configuration and changes to it do not interfere with the operation of the other instance. The "primary" SSH instance, as configured by the OS install is left for use by the VPS user(s) and is configurable by them. The secondary instance is dedicated to access from the grid, for the VPS provider / maintainter.

Note that the actual setup may vary with OS type and SSH server version. The examples here assume the OS is unix-style and the server is OpenSSH.

The two instances of the SSH server can be configured with different security settings, to match specific needs of the VPS user.

1. Copy the configuration of sshd into a new sub-directory, e.g.:
   mkdir /etc/ssh_grid
   cp /etc/ssh/sshd_config /etc/ssh_grid
2. Edit the original configuration file (/etc/ssh/sshd_config) and:
   • remove all ListenAddress directives, if any
   • add the following lines to the configuration file (with no empty lines between them):
     # $$propN: 1111:primary_ip
     ListenAddress 1111
3. Edit the copied configuration file (/etc/ssh_grid/sshd_config) and make the following changes:
   • disable reverse DNS lookups:
     UseDNS no (or LookupClientHostnames no on some SSH implementations)
   • disable password logins:
     PasswordAuthentication no
   • allow root login (with key only):
     PermitRootLogin without-password
   • set a custom key file name, which works only for root:
     AuthorizedKeysFile /root/.ssh/alt_authorized_keys
   • disable GSSAPI authentication (cannot be used from the AppLogic controller):
     GSSAPIAuthentication no
   • Remove all 'ListenAddress' options
4. Create a new auto-start script for the second ssh server, with the following commands in it:
   # get service IP address
   f=/var/run/applogic/appliance.desc
   p=instance:`udlparse elst $f instance`/interface:default
   addr=`udlparse get $f $p/ip`
   
   # start ssh daemon
   sshd -f /etc/ssh_grid/sshd_config -o ListenAddress=$addr

Final Steps

The following settings need to be added to the applogic_init configuration file (usually /etc/sysconfig/applogic_init - see the APK install guide for exact location).

NOTE: modify the file paths to match the settings in the sshd config file for the secondary SSH instance, as configured above.

   # apply configuration to these files:
   APK_CONFIG_FILES="/etc/ssh/sshd_config"
   # make AppLogic configure this file as the grid ssh access key
   APK_AUTH_KEY_PATH=/root/.ssh/alt_authorized_keys

Building a mini-appliance

This section describes how to build a fast-booting mini-appliance, based entirely on a read-only volume. A small footprint appliance like this can be the basis of a NAT gateway, load balancer and anything else that does not need to keep persistent state.

(coming soon)

Appendix

AppLogic Configuration File Formats

Appliance Instance Descriptor

The instance descriptor file contains all of the data from the appliance class description (as may be seen in the editor, in the "View/Edit Class" dialog), modified by any attributes and property value settings applied to the instance (refer to the AppLogic application editor documentation for details on how configuration is defined and propagated in applications).

Note that in all but the most advanced appliances, there is no need to access data in the appliance descriptor directly, as the application-specific configuration values are provided in processed formats, as described in the Appliance Boundary chapter.

The instance descriptor is a structured text file, with the following format:

instance main. instance-path : .class= catalog . classname

   {

   . clsattr = value

   ....

   resource cpu: min= num , max= num , dflt= num

   resource mem: min= num , max= num , dflt= num

   resource bw: min= num , max= num , dflt= num

   (input|output) trmname : protocol= filter , dev=eth num

      {

      hwaddr=' macaddr '

      }

   ...

   interface default: dev=eth num

      {

      hwaddr=' macaddr '

      ip= ipaddr

      }

   volume boot: dev= devfile [, class, type=(instantiable|shared)] [(mandatory|ro|shared|class), ... ] [, mount= dir ] [, disconnected] [, static]

   volume volname : dev=....

   ...

   property prpname : value= prpval , attr = val , ...

   property ...

   ...

   }

Here are the sections into which the file is divided and what they contain:

Heading

Includes the appliance's location inside the application (instance-path), reflecting the hierarchy of assemblies in which it is contained and the class from which it was created (catalog . classname). If the appliance is a singleton defined in an application, the catalog name is empty.

Class Attributes

This section contains various class attributes, with names starting with a dot. Their values are either the class default, or a value explicitly set for the appliance instance. Except where noted, each attribute corresponds to a setting in the Attributes dialog in the editor. The following attributes are available:

    .hostname= string (not user-settable, generated from the instance name)

    .migrateable= (0|1)

    .locked= (0|1)

    .start_order= num

    .boot_tout= num

    .shutdown_tout= num

    .field_opt= num (this is the FE code value from the Edit Class dialog for the appliance class, not affected by any setting that might be provided in the Attributes dialog)

    .inst_field_opt= num (this is the FE code value from the Attributes dialog).

    .restart_mode (container|self)=

Resource Configuration

This section contains only the resource limits (as set in the application). The actual resources allocated are not visible in the instance descriptor.

Terminals

This section has one entry for each appliance terminal. It may be empty, if the appliance has no terminals. For each terminal, the following data is provided:

terminal type (input or output)

terminal name (trmname)

protocol filter name (filter)

device number (dev=ethnum). Note that this does not necessarily correspond to a valid device name (the device names are OS-dependent).

device MAC address (macaddr)

device IP address (ipaddr) - present only if the terminal is connected

Default Interface

This defines the configuration of the appliance's service interface (used to configure the appliance initially, and to report status to the grid controller). Includes the following data:

device MAC address (macaddr)

device IP address (ipaddr) - present only if the terminal is connected

Volumes

This section has one entry for each volume and has at least one entry (the boot volume of the appliance). The following is defined for each volume:

Device special file (or another OS-specific identifier of the device that this volume appears as in the appliance): devfile If the volume contains a mountable file system, this name can be used in the mount command and may refer to a device other than the the physical device (e.g, it may be a 'partition device' name). Otherwise, this name refers to to the actual device.

If the volume belongs to the appliance class, it has the class attribute, and the type attribute is set to one of: ( instantiable|shared|blank ).

The volume may have one or more optional attributes: (mandatory|ro|shared|class)

Volumes that are mounted, or those that have a mount point defined for them in the appliance class (even if mount for them failed) have the mount= attribute, with the name of the actual or requested mount point, as follows:

• Volumes for which the user specified a mount point in the appliance class are mounted by APK; they will have the mount point defined in the class reflected in the instance descriptor (whether APK succeeds in mounting them or not).

• Volumes that do not have a mount point specified in the class, but are mounted in the appliance by other means (e.g., the boot volumes are mounted by the OS), will have the actual mount point in the mount= attribute, and also the static attribute will be set.

Optional placeholder volumes defined in the appliance, but not assigned an actual data volume will have the disconnected attribute.

Properties

One property entry is present for each property defined for the appliance class. For each property, the following is provided:

prpval – effective value of the property for the instance. This is either the class default, or an explicitly configured value.

attr=val – various property attributes, copied from the appliance class description (including the property type, range of valid values, etc.).

Network Configuration File

The .net file for an appliance contains the configuration of the appliance's network, in text form that is designed to be easy to interpret in a shell script and be converted to configuration commands to the appliance's network subsystem. Some of the configuration statements in the .net file are compatible directly with the command-line format of the 'ip' utility used on all modern Linux distros. The file format is line-based and each line consists of a directive name, followed by parameters.

Dynamic Configuration Data

This is a text file, which must contain a line in the form 'srv_ip=ipaddress'. Other data items may be added to this file in the future. Only the APK init scripts interpret this file, it is not intended to carry data that is useful to the appliance-specific programs.

-- BeckyH - 25 Apr 2008