Component Descriptor Syntax

Below are two examples of the component descriptor structure; the first example is the current standard form, the second example shows the old format of the boot information specification. The old format is fully supported for compatibility with existing catalog appliances.

component name
   {
   volume sname : dev= pathname [, mount= pathname][, ro] [, high_bw]

   resource cpu : min= val , max= val
   resource mem : min= val , max= val , abs= val
   resource bw  : min= val , max= val

   (input|output)  sname : protocol= name [, mandatory ][, alias = dnsname ]
   interface  sname

   property  sname  : type=(string|integer|ip_addr) [, filter= regexp ] \
                    [,min= val ,max= val ] [, (mandatory| dflt= val) ]
   property  sname  : type=(string|integer) [, values= v1|v2|v3... ] \
                    [, (mandatory| dflt= val ) ]
   .config_mode=(dhcp|volfix)
   virtualization: mode=(paravirt|hvm)
      {
      path = filename
      initrd = filename
      options = " string "
      console = " string "
      device_schema = " string "
      }

   visual
      {
      ...
      }
   }

component name
   {
   volume sname : dev= pathname, [, ro] [, high_bw]

   resource cpu : min= val , max= val
   resource mem : min= val , max= val , abs= val
   resource bw  : min= val , max= val

   (input|output)  sname : protocol= name = [, mandatory][, alias = dnsname =]
   interface  sname

   property  sname  : type=(string|integer|ip_addr) [, filter= regexp ] \
                    [,min= val ,max= val ] [, (mandatory| dflt= val) ]
   property  sname  : type=(string|integer) [, values= v1|v2|v3... ] \
                    [, (mandatory| dflt= val ) ]
   cfgfiles
      [
      vol= sname , path= filename
      vol= sname , path= filename
      ...
      ]

   kernel: path= filename  [, initrd = filename ] [, options = " string" ]

   visual
      {
      ...
      }
   }

The component entity has the following attributes defined:

All component attributes are optional and need not be present in the descriptor.

All of the attributes are also valid properties of the component, which can be overridden in an assembly that contains the component. Note that the attribute names are prefixed with a dot, to avoid name conflicts with regular properties (see the 'property' entity below).

The table below is a summary of the valid sub-entities in a component, followed by sections that explain each sub-entity in detail.

volume

A 'volume' entity that has no 'class' attribute also defines a configurable property on the boundary of the component, which can be set the same way as other properties of the component - see the property entity below. The mandatory attribute for such volumes works the same way as the mandatory attribute for properties. A 'volume' property should be set to the logical name of one of the application's volumes (as found in the application's package descriptor). Note that this means volumes and properties share namespace and one cannot define a volume and a property of the same name.

resource

The 'resource' entities are mandatory , all must be specified in a component's description and all must have the 'min' and the 'max' value specified. The 'abs' value may be omitted and is assumed to be equal to 'min' by default.

input, output

interface

    interface external
    interface default

The 'interface external' entry enables the device named 'eth0' to be used as the external network interface of the component (accessible from outside the application). If enabled, eth0 is not used for terminals and its IP configuration is not set up automatically. Instead, it is expected that properties are defined to configure the network adapter.

The 'interface default' entry enables configuring an unused network interface for unrestricted use, with an automatically assigned IP address on the same subnet as the ones used for terminal connections. The assigned IP address is made available to the AppLogic controller as the IP address of the component; this can be used for maintenance logins.

property

• all properties are available for access by shell scripts and executables as environment variables defined in a shell file that is stored automatically on the component's boot volume and can be included by any script;
• also, any files named in a 'cfgfiles' entity (see below) are searched for special markup identifying a portion of the file as corresponding to a property value - all matching instances are automatically updated to reflect the property value as configured in the component's descriptor or as overridden by any assembly in which the component participates. There are several variants of "markup", which allow making it appear as comments to the software that uses the file, so it is completely transparent to the component's code. See the Property Markup Syntax section later in this document.

Note that since a volume can appear as a configurable property on the boundary, volumes and properties share namespace and one cannot define both a volume and a property of the same name.

The property entity has the following attributes:

cfgfiles

vol - names the volume on which the file is located (this should match one of the component's volumes, as defined by the volume entities). A value for this attribute must be specified for each cfgfiles array element.

path - this is the file name of the configuration file, relative to the volume on which it is located. Note that this may be different from the path where the application "sees" that file - depending on how the particular volume is mounted by the component. A value for this attribute must be specified for each cfgfiles array element.

quoting - defines the method for quoting meta-characters in the configuration file. A "meta-character" is any character that has a special meaning in the config file and must be quoted (or "escaped") in some manner in order to appear as a data character and not in its special-function role. The 'quoting' attribute can be set to one of the following strings:

NOTE: the cfgfiles sub-entity is useful only when .config_mode is set to volfix. In the dhcp mode, the component's boot volume will not be modified and it is expected to configure itself dynamically over the network.

virtualization

This entity contains the boot information needed to start the component in the virtual environment for which it is designed. The virtualization entity supersedes the kernel/os_info definitions and should be used instead of them. The presence of this entity also indicates a 'new-style' component descriptor and turns off the compatibility mode, which includes forced .config_mode=volfix.

The following attributes are defined for the virtualization entity:

kernel, os_info

obsolete, use virtualization instead. The presence of a kernel or os_info sub-entity in the descriptor indicates an old descriptor and the volfix configuration mode is forced automatically.

This entity contains OS-specific boot information, its contents depend on the value of the .os_type attribute of the component. The keywords kernel and os_info are equivalent, kernel is retained for backward compatibility.

When .os_type=linux , the following attributes are defined for the os_info entity:

path= filename - the name of the kernel image file, relative to the boot volume's root directory.

initrd= filename - the name of the ramdisk filesystem image to use during boot. The kernel image file and the ramdisk image file are typically produced as a result of building the Linux kernel.

options= "string" - other arguments to pass to the bootloader's 'kernel' command line.

When .os_type=legacy, the following attributes are defined:

options=" name=value name=value ... "

The legacy OS type is used for all hardware-assisted virtual machines. The name=value pairs are not interpreted, they are passed on to the HVM emulator directly. Examples of parameters supported by the qemu emulator (used in XEN) include: acpi=(0!1), apic=(0!1), pae=(0!1), etc.

-- VladM - 25 May 2006