100% found this document useful (1 vote)

296 views57 pages

Package Format Specification

Application packaging

Uploaded by

Padhu Veluru

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

296 views57 pages

Package Format Specification

Application packaging

Uploaded by

Padhu Veluru

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 57

Application Packaging Standard

- Package Format Specification

1.2
Copyright © 1999, 2008 Parallels, Inc

All rights reserved.

Table of Contents
1. Introduction .............................................................................................................. 2
2. Conventions ............................................................................................................. 4
3. Document Structure ................................................................................................... 4
4. Basic Package Format ................................................................................................ 4
4.1. File Format .................................................................................................... 4
4.2. Files ............................................................................................................. 4
4.3. Metadata File ................................................................................................. 5
4.4. Package contents listing ................................................................................... 5
5. Metadata Descriptor ................................................................................................... 5
5.1. Common Application Properties ....................................................................... 12
5.1.1. Application ID ................................................................................... 12
5.1.2. Package Name ................................................................................... 12
5.1.3. Package Version ................................................................................. 12
5.1.4. Homepage ......................................................................................... 12
5.1.5. Master package reference ..................................................................... 12
5.1.6. Software Vendor Information ................................................................ 13
5.1.7. Software Packager Information .............................................................. 13
5.1.8. Summary ........................................................................................... 13
5.1.9. Description ........................................................................................ 14
5.1.10. Icon ................................................................................................ 14
5.1.11. Screenshots ...................................................................................... 14
5.1.12. Changelog ....................................................................................... 14
5.1.13. Categories ........................................................................................ 14
5.1.14. Languages ....................................................................................... 15
5.1.15. Updates ........................................................................................... 15
5.1.16. Content Delivery Methods .................................................................. 16
5.1.17. Global Settings ................................................................................. 17
5.2. Services ....................................................................................................... 17
5.2.1. Service Summary ................................................................................ 18
5.2.2. License Agreement ............................................................................. 18
5.2.3. Information Links ............................................................................... 19
5.2.4. Entry Points ....................................................................................... 19
5.2.5. Service Settings .................................................................................. 21
5.2.6. Resources .......................................................................................... 26
5.2.7. Requirements ..................................................................................... 26
5.2.8. Service Provision ................................................................................ 28
5.3. Service Provision Methods .............................................................................. 28
5.3.1. URL Mapping .................................................................................... 28
5.3.2. Configuration Script ............................................................................ 31
5.3.3. Verification Script ............................................................................... 36
5.3.4. Resource Script .................................................................................. 36
5.3.5. Backup/Restore Script ......................................................................... 37
6. Package Contents Listing .......................................................................................... 38
7. Points of Extensibility .............................................................................................. 39

1
Application Packaging Standard
- Package Format Specification

7.1. Requirement Types ........................................................................................ 39

7.2. URL Handlers Types ..................................................................................... 40
7.3. Additional Files ............................................................................................ 40
7.4. Environment Variables ................................................................................... 40
7.5. Additional Scripts ......................................................................................... 40
7.6. Script Language ............................................................................................ 40
7.7. Application Provision Method ......................................................................... 40
7.8. Rules .......................................................................................................... 40
8. Common Aspects .................................................................................................... 40
8.1. PHP Aspect .................................................................................................. 40
8.1.1. Requirement Types ............................................................................. 41
8.1.2. URL Handlers .................................................................................... 42
8.1.3. Configuration Script Language .............................................................. 42
8.2. ASP.NET Aspect .......................................................................................... 43
8.2.1. Requirement Types ............................................................................. 43
8.2.2. URL Handler Type ............................................................................. 43
8.2.3. Configuration Script Language .............................................................. 43
8.3. Database Aspect ............................................................................................ 43
8.3.1. Environment Variables ........................................................................ 45
8.3.2. Database Server Types ......................................................................... 45
8.3.3. Upgrade ............................................................................................ 45
8.3.4. MySQL Specific Settings ..................................................................... 46
8.4. Apache Aspect .............................................................................................. 46
8.5. CGI Support ................................................................................................. 47
8.6. Hardware Resources ...................................................................................... 48
8.7. Operating Environment .................................................................................. 48
8.8. Mail ............................................................................................................ 49
8.8.1. Environment Variables ........................................................................ 51
8.8.2. Upgrade ............................................................................................ 51
8.9. Perl Aspect .................................................................................................. 51
8.9.1. Requirement Types ............................................................................. 52
8.9.2. URL Handlers .................................................................................... 53
8.9.3. Configuration Script Language .............................................................. 53
8.10. DNS Zone .................................................................................................. 53
8.11. DLL Content Processing Method .................................................................... 55
8.12. IIS Aspect .................................................................................................. 56
References ................................................................................................................. 56

1. Introduction
Application Packaging Standard defines the packages structure and rules of processing packages.
Package is a file that contains an application files and metadata required to create and manage instances
of the application.

Package is a ZIP file that contains the following:

main package metadata file APP-META.xml

additional metadata files, such as icons and screenshots, referenced from APP-META.xml
management scripts in the scripts/ directory. The scripts/configure script performs
application-specific tasks during the application installation, upgrade, patching, reconfiguration and
removal.
list of all package files APP-LIST.xml, every file have size in bytes and SHA256 digest value. This
list may be digitally signed by one or several packagers or authorities, or may not be signed at all.

Here is a structure of a typical package.

APP-META.xml # Metadata container. XML file.

APP-LIST.xml # List of files in package and signing data
scripts/
configure # This script will be invoked when application

2
Application Packaging Standard
- Package Format Specification

... # instance is managed

...
... # Additional files to be used by the 'configure'
... # reside in the same directory
images/
icon1.png # Icon and screenshots of the application
screenshot2.jpg
screenshot.jpg
...
htdocs/ # Application files
index.php
logo.png
...

The APP-META.xml file contains all the metadata required to manage the application. This includes
name, version, description and changelog of the application, resources required for the application
and its services to function properly and description of user-supplied configuration settings. Typical
structure of metadata:

<name>Broombla</name>
<version>1.0.11</version>
<release>4</release>
<homepage>http://broombla.com/</homepage>

<vendor>
<name>Broombla Corporation</name>
<homepage>http://broombla.com/</homepage>
<icon path="icons/corp_logo.gif"/>
</vendor>

<packager>
<name>Broombla Packaging</name>
<homepage>http://broombla.com/packages</homepage>
<icon path="icons/corp_logo.gif"/>
</packager>

<presentation>
<summary>...</summary>
<description>
...
</description>
<icon path="icons/logo.gif"/>
<screenshot path="img/screenshot1.gif">
<description>...</description>
</screenshot>
<changelog>
<version version="1.0.11" release="4">
<entry>Fixed bug in ...</entry>
</version>
</changelog>
<categories/>
<languages/>
</presentation>

...

<license must-accept="true">
...

3
Application Packaging Standard
- Package Format Specification

</license>

<php:version min="5.0"/>
<php:extension>mysql</php:extension>

<db:db xmlns:db="http://apstandard.com/ns/1/db">
<db:id>main</db:id>
<db:default-name>phpbb</db:default-name>
<db:server-type>mysql</db:server-type>
<db:server-min-version>3.22</db:server-min-version>
</db:db>

...
</requirements>

<url-mapping>

<mapping url="/" path="htdocs">
<php:handler/>
</mapping>
</url-mapping>

</provision>

</service>

</application>

2. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [RFC 2119]

3. Document Structure
This specification is divided into the following two parts:

basic package format

common aspects

The first part of the specification describes basic metadata required for application to instantiate and
operate, and points of extensibility.

The second part consists of several aspects. Aspect is a document describing the specific extension
to the basic format. The format is modular to accommodate new programming languages, operating
systems, software components, etc.

4. Basic Package Format

4.1. File Format

Package is a ZIP file [ZIP] with the .app.zip extension.

4.2. Files

Package MUST contain only regular files and directories.

There MUST NOT be two files or directories in one directory which file names differ only in case.

4
Application Packaging Standard
- Package Format Specification

Names of the files included in a package SHOULD contain only printable ASCII characters (except
for the TAB, NL, and CR characters (ASCII codes 32-127)). To ensure web application compatibility
with Microsoft Windows, names of the files included in a package MUST NOT contain the following
characters: <, >, :, ", /, \, |, *, ?.

Special Windows device names (con, con.*, nul, nul.*, lpt etc) MUST NOT be used in
packages. It is recommended to check for such files during package unpacking on Windows.

4.3. Metadata File

Each package MUST contain a well-formed XML file named APP-META.xml in the package root
directory. This file contains all the package metadata. File should be in UTF-8 encoding.

4.4. Package contents listing

Each package MUST contain a well-formed XML file named APP-LIST.xml in the package root
directory. This file contains list of all files in package, but APP-LIST.xml. File my be digitaly
signed by one or more signers. Contents of the file is described in package contents listing chapter.
File should be in UTF-8 encoding.

5. Metadata Descriptor
RELAX NG schema of metadata descriptor:

default namespace sa = "http://apstandard.com/ns/1"

namespace local = ""

grammar {

start = Application

Application = element application {

## Version of APS format used
attribute version { "1.2" },
## Packaging date
attribute packaged { xsd:dateTime }?,

## Unique application identifier

element id { xsd:anyURI },

element name { text },

element version { text },
element release { text },
element homepage { xsd:anyURI }?,

## Reference on master package for add-on package

element master-package {
element package {
attribute id { xsd:anyURI },
attribute match { text } ?
}+
}?,

element vendor {
element name { attribute xml:lang { text }?,
text }+,
element homepage { attribute xml:lang { text }?,
xsd:anyURI }*,
element icon { attribute path { text } }?
}?,

element packager {
element name { attribute xml:lang { text }?,
text }+,
element homepage { attribute xml:lang { text }?,
xsd:anyURI }*,
element icon { attribute path { text } }?,
element uri { xsd:anyURI }?
}?,

5
Application Packaging Standard
- Package Format Specification

element presentation {
element summary { attribute xml:lang { text }?,
text }*,
element description { attribute xml:lang { text }?,
text }*,
element icon { attribute path { text } }?,

element screenshot { attribute path { text },

element description {
attribute xml:lang { text }?,
text }+
}*,

element changelog {
element version { attribute version { text },
attribute release { text },
attribute date { xsd:dateTime }?,

element entry {
attribute xml:lang { text }?,
text }+
}*
}?,

element categories { element category { text }+ }?,

element languages { element language {

xsd:string { pattern = "[a-z]{2,3}" } }+ }?,

element extension { AnyElement* }?

}?,

element global-settings { ( Setting | SettingGroup )* }?,

element patch { attribute match { text },

attribute recommended { "true" }? } *,

element upgrade { attribute match { text },

attribute mode { "managed" | "backup" }? } *,

element content { ContentDeliveryMethod }?,

element provision { element verify-script { VerifyScript }? }?,

Service*
}

AnyElement = element * { attribute * { text }*,

( text | AnyElement)* }

ContentDeliveryMethod = DefinedByAspect

## Services
Service = element service {
attribute id { text },
attribute class { "account" |
"service" |
"ecommerce" |
text }?,
attribute singular { "true" }?,

element license { EULA }?,

element presentation { Presentation }?,

element settings { ( Setting | SettingGroup )* }?,

element resources { Resource * }?,

## Requirements specification [5.4.4]

element requirements {
element choice { element requirements { attribute id { text },

6
Application Packaging Standard
- Package Format Specification

Requirement+ }+
}*,
Requirement*
}?,

element provision {
element when-chosen { attribute requirements-id { text },
ProvisionMethod+
}*,
ProvisionMethod+
}?,

Service*
}

## End-user license agreement

EULA = ( attribute must-accept { xsd:boolean },
( element free { empty } |
element commercial { empty } )?,

element text { attribute xml:lang { text }?,

element name { text }?,
( element url { xsd:anyURI } |
element file { text } )
}+
)

## GUI-related settings
Presentation =
## Textual description of the service
element name { attribute xml:lang { text }?, text }*,
element summary { attribute xml:lang { text }?, text }*,
element icon { attribute path { text } }?,

element entry-points {
element entry { attribute class { "control-panel" |
"login" |
"frontpage" |
"check" |
text }?,
## URI templates are allowed
attribute dst { xsd:anyURI | text }?,
attribute method { "GET" |
"POST" |
text }?,

element label { attribute xml:lang { text }?,

text }+,
element description { attribute xml:lang { text }?,
text }*,
element icon { attribute path { text } }?,

## Optional parameters for using entry point

element variable { attribute name { text },
attribute class { "login" |
"password" |
"locale" |
text }?,
attribute value-of-setting

7
Application Packaging Standard
- Package Format Specification

{ text }?,
text
}*,

element extension { AnyElement* }?

}+
}?,

element extension { AnyElement* }?

## Settings
div {
SettingGroup = element group { attribute class { "authn" |
"presentation" |
"web" |
"vcard" |
"type" |
text }?,

## groups with name of @class "type" are used to

## express hCard subproperties
# Due to XML Schema restrictions, distinct definitions were joined
element name { attribute xml:lang { text }?,
attribute class { "type" }?,
text }*,

## Nested anonymous groups are allowed for the sake of

## microformats compliance
( SettingGroup | Setting )*
}

Setting = element setting { attribute id { text },

attribute class { text }?,
attribute uniq { "global" | "application" | "instanc
attribute uuid { xsd:anyURI | text }?,
attribute optional { "true" }?,
attribute visibility { "hidden" }?,
attribute protected { "true" }?,
attribute value-of-setting { text }?,
attribute generate { "sequence" | "uuid" | "random" | "p
( attribute installation-only { "true" } |
attribute track-old-value { "true" } )?,

element name { attribute xml:lang { text }?, text }*,

element description { attribute xml:lang { text }?, text }*,
element error-message { attribute xml:lang { text }?, text }*,

# Settings types
( ( attribute type { "boolean" },
attribute default-value { "true" | "false" }? )

| ( attribute type { "string" | "password" },

SettingTypeString,
attribute default-value { text }? )

| ( attribute type { "integer" },

SettingTypeInteger,
attribute default-value { xsd:integer }? )

| ( attribute type { "float" },

SettingTypeFloat,
attribute default-value { xsd:float }? )

| ( attribute type { "date" },

SettingTypeDate,
attribute default-value { xsd:date }? )

| ( attribute type { "time" },

SettingTypeTime,
attribute default-value { xsd:time }? )

| ( attribute type { "email" },

8
Application Packaging Standard
- Package Format Specification

attribute default-value { text }? )

| ( attribute type { "domain-name" },

attribute default-value { text }? )

| ( attribute type { "host-name" },

attribute default-value { text }? )

| ( attribute type { "enum" },

attribute default-value { text }?,
element choice { attribute id { text },
element name { attribute xml:lang { text }?,
text }*
}+ )
| ( attribute type { "list" },
attribute list-order { "id" | "name" | "custom" }?,
attribute min-items { xsd:nonNegativeInteger }?,
attribute max-items { xsd:nonNegativeInteger }?,
## Possible list elements defined below
( ( attribute element-type { "string" },
SettingTypeString,
element default-value { text }* )

| ( attribute element-type { "integer" },

SettingTypeInteger,
element default-value { xsd:integer }* )

| ( attribute element-type { "float" },

SettingTypeFloat,
element default-value { xsd:float }* )

| ( attribute element-type { "email" },

element default-value { text }* )

| ( attribute element-type { "domain-name" },

element default-value { text }* )

| ( attribute element-type { "host-name" },

element default-value { text }* )

| ( attribute element-type { "enum" },

element default-value { text }*,
element choice {
attribute id { text },
element name { attribute xml:lang { text }?, text }*
}+ )
)
)
)
}
}

SettingTypeString = attribute min-length { xsd:nonNegativeInteger }?,

attribute max-length { xsd:nonNegativeInteger }?,
( attribute regex { text } |
attribute charset { text } )?

SettingTypeInteger = attribute min { xsd:integer }?,

attribute max { xsd:integer }?

SettingTypeFloat = attribute min { xsd:float }?,

attribute max { xsd:float }?

SettingTypeTime = attribute min { xsd:time }?,

attribute max { xsd:time }?

SettingTypeDate = attribute min { xsd:date }?,

attribute max { xsd:date }?

Requirement = DefinedByAspect

## Placeholder for aspect-specific URL handlers

9
Application Packaging Standard
- Package Format Specification

UrlHandler = DefinedByAspect

## Aspect must use own namespace

DefinedByAspect = element * - ( sa:* | local:* ) {
attribute * { text }*,
( text | DefinedByAspect )*
}

## Provision specification
div {
ProvisionMethod = element url-mapping { UrlMapping } ? &
element configuration-script { ConfScript } ? &
element backup-script { BackupScript } ? &
element verify-script { VerifyScript } ? &
element resource-script { ResourceScript } ? &
DefinedByAspect*

## URL Mapping
UrlMapping = element default-prefix { xsd:string { minLength = "1" } }?,
element installed-size { xsd:nonNegativeInteger }?,
element site-root { empty }?,
element mapping { Mapping }*

Mapping = RegularMapping | VirtualMapping

RegularMapping =
attribute url { xsd:string { minLength = "1" } },
attribute path { xsd:string { minLength = "1" } }?,
attribute shared { "true" }?,
UrlHandler*,
element mapping { Mapping }*

VirtualMapping =
attribute url { xsd:string { minLength = "1" } },
(
attribute virtual { "virtual" } |
(
attribute virtual { "redirect" },
element href { xsd:anyURI }
)
),
element mapping { Mapping }*

## Generic script Script

BaseScript = attribute name { text },
attribute privileged { "true" }?,
( element script-language { text } |
element binary-executable { empty } )

## Configuration Script
ConfScript = BaseScript
& element status-control { empty }?
& element structured-output { empty }?

## Backup/Restore script
BackupScript = BaseScript &
element sufficient { empty }?

## Verify script
VerifyScript = BaseScript
& element structured-output { empty }?

## Resource script
ResourceScript = BaseScript &
## Hint to controller how often to poll for resource usage
## examples: 30m or 2h or 1d
attribute poll-interval { xsd:string { pattern = "(\d+m)|(\d+h)|(\d+d)?" } }?

## Resource specification

10
Application Packaging Standard
- Package Format Specification

div {
## Resource definition
Resource = element resource {
## Unique resource identifier
attribute id { text },

## Resource class represents basic idea what is measured by that resource

attribute class { "item" | "b" | "kb" | "mb" | "gb" | text },

## Limiting setting hints to controller what setting limits that resource

attribute limiting-setting { text }?,

## Resource name
element name { attribute xml:lang { text }?, text }+,

## Resource description
element description { attribute xml:lang { text }?, text }*
}
}
}

The APP-META.xml file MUST be valid according to the schema above. XML namespace of the
metadata will be changed when incompatible changes are introduced.

Package SHOULD declare the version of APS specification with which it complies with the help of
the version attribute.

<application xmlns="http://apstandard.com/ns/1" version="1.2">

</application>

The version of APS format specified herein is 1.2 . The numbering scheme for APS format versions
is major.minor . The major and minor numbers MUST be treated as separate integers and each
number MAY be incremented higher than a single digit. Thus, APS 1.2 would be a lower version
than APS 1.10 . Leading zeros (e.g., APS 1.01 ) MUST be ignored by APS controllers and MUST
NOT be specified.

Package SHOULD use the lowest possible version of APS specification that is sufficient for describing
the application's capabilities and requirements.

Package SHOULD declare packaging date with the help of the packaged attribute.

Metadata schema contains several places where arbitrary elements may be added: requirements may
be added to the requirements elements, provision methods may be added to the provision
element and URL handlers may be added to the mapping elements. The allowed types of
requirements, provision methods and URL handlers are described in aspects. Structure of this elements
are described in subsequent specification sections.

When a Controller encounters requirement which it does not know how to handle, the Controller
should consider this requirement as non-satisfiable. If such requirement is found outside of the
choice element, the package MUST NOT be installed. If such requirement is found inside the
choice element, then the branch in which it is contained MUST NOT be selected during installation.

If a Controller encounters unknown elements in the mapping section, the package installation must
be aborted.

11
Application Packaging Standard
- Package Format Specification

All user-visible strings in metadata descriptor are localizable. Localization is performed by using the
standard XML xml:lang attribute: every localizable string has optional attribute xml:lang :

...
<description>Some description</description>
<description xml:lang='de-DE'>...</description>
<description xml:lang='ja-JA'>...</description>
...

String without explicit xml:lang is always required.

5.1. Common Application Properties

The following properties are common for all applications:

5.1.1. Application ID

<id>http://www.phpbb.com/</id>

URI-formed unique application identifier. This string should be used as a application identifier - it
MUST NOT be changed in consequent versions of packages, otherwise package upgrade and patch
from older versions will be not feasible. This URI may or may not lead to any valid page.

5.1.2. Package Name

<name>phpbb</name>

Free-formed string specifies user-visible name of application in a package. Package name may be
changed during upgrade and should reflect packaged software name.

5.1.3. Package Version

Package version consists of two parts: application version and package release, the former corresponds
to the version of application packaged, and the later to the release of the package containing the same
version of application (packages may be released many times, e.g., for fixing bugs in packaging or
adding localizations).

Version format and the algorithm for determining the chronological relationship between different
package versions are specified by the Debian Policy: Version Format in Debian Policy [http://
www.us.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version].

Unlike the Debian version-release approach, application version and package release are separated to
ease parsing.

5.1.4. Homepage

<homepage>http://phpbb.com/</homepage>

URL of the application official site.

5.1.5. Master package reference

<master-package>
<package id="http://www.phpbb.com" match="version = 1.1"/>
</master-package>

If a package is an add-on package for another APS application this definition provides a reference to
master package by ID and version/release conditions. Optional condition is provided by match XPath

12
Application Packaging Standard
- Package Format Specification

expression. Virtual nodes version and release in the context of expression represent version and
release of master package.

Before installation controller MUST check availability of referrenced APS package in given context.
Add-on packages will get an access to global settings of master package with value-of-setting
attribute.

Add-on package services may inherit master package serviceses hierarchy by defining services
structure with same IDs. Add-on package may not change master package services, but may define sub-
services of master package services. In this case add-on packages man refer master package service
settings with value-of-setting.

Add-on package may request environment variables provided by master package requirements by
defining requirement with same ID as a requirement of master package in context of service.

Add-on package may request environment variables provided by master package URL mappings
by defining same URL mappings as in master package. Add-on package may define its own URL
mappings as usual.

5.1.6. Software Vendor Information

<vendor>
<name>Broombla Corporation</name>
<homepage>http://broombla.com</homepage>
<homepage xml:lang="ja-JA">http://broombla.com/ja</homepage>
<icon path="icons/broombla-corp-logo.gif"/>
</vendor>

Characteristics of software vendor whose application is packaged. Both the name and homepage
allow localization. The icon/@path attribute MUST contain a full path in archive to the icon file.
The icon SHOULD be a 64x64 pixel image in PNG format using alpha transparency. JPEG and GIF
formats MAY be used as well, but their use is discouraged.

5.1.7. Software Packager Information

<packager>
<name>Parallels</name>
<homepage>http://parallels.com</homepage>
<icon path="icons/parallels-package-logo.gif"/>
<uri>uuid:15d041e8-34c6-409a-b165-3290d2c9d599</uri>
</packager>

Characteristics of package manufacturer. Both the name and the homepage elements allow
localization. The icon/@path attribute MUST contain a full path in archive to the icon file. The
icon must be a 64x64 pixels image in JPEG, PNG or GIF format.

The uri element is an arbitrary URI unique for each packager (it is RECOMMENDED to use uuid:
URI scheme to minimize the possibility of clash). This URI is needed to distinguish packages with
the same name but created by different packagers. Note that consequent versions of the same package
MUST have the same URI, as otherwise package Controllers MAY refuse to update package from
one version to another.

Controllers SHOULD allow to upgrade and patch package from the version which does not specify
uri to the one which specifies in order to support smooth upgrade path for the packages which did
not use uri from the beginning.

5.1.8. Summary

<presentation>
<summary>
High powered, fully scalable, and highly customizable Open Source bulletin
board package.

13
Application Packaging Standard
- Package Format Specification

</summary>
<summary xml:lang="es-ES">...</summary>
...
</presentation>

Single-sentence summary of the package for end users.

5.1.9. Description

<description>
phpBB is a high powered, fully scalable, and highly customizable
Open Source bulletin board package. phpBB has a user-friendly
interface, simple and straightforward administration panel, and
helpful FAQ. phpBB is the ideal free community solution for all web
sites.
</description>
<description xml:lang="it-IT">...</description>

One-paragraph description of the package for end users.

5.1.10. Icon

<icon path="images/phpbb.png" />

Icon may be provided to be displayed in GUI for the application. The path attribute MUST contain
a full path in archive to the icon file. The icon SHOULD be a 64x64 pixel image in PNG format using
alpha transparency. JPEG and GIF formats MAY be used as well, but their use is discouraged.

5.1.11. Screenshots

<screenshot path="images/admin.png">
<description>Administrative interface</description>
<description xml:lang="he-IL">...</description>
</screenshot>
<screenshot path="images/main.png">
<description>Main page</description>
<description xml:lang="ja-JA">...</description>
</screenshot>

Several screenshots with descriptions may be provided. The path attribute MUST contain a full path
in archive to the screenshot file. It must be JPEG, PNG or GIF image.

5.1.12. Changelog

<changelog>
<version version="2.1.22" release="1">
<entry>New upstream version</entry>
<entry xml:lang="de-DE">...</entry>
</version>
<version version="2.1.21" release="5">
...
</version>
...
</changelog>

Changelog contains the human-readable list of changes between consecutive package versions. Order
of entries in changelog is not specified, Controller should sort them.

5.1.13. Categories

<categories>
<category>Collaboration/Portals</category>
<category>Web/Content management</category>
</categories>

14
Application Packaging Standard
- Package Format Specification

Package may include a set of categories. Category is a Unicode string without attached semantics.
The first category should be "primary category" in the sense the first category should be adequate for
sorting packages in the user interface.

A list of predefined categories is available at [APS Categories]. The specified categories names
SHOULD be used. Other categories names MAY be used, but handling them in Controller is
OPTIONAL.

5.1.14. Languages

Package may declare a set of languages for the presentation purposes. The first language is the "default
language" of the application. Languages are identifiers from ISO 639.

5.1.15. Updates

Application may declare versions of packages which can be updated to the current package. Two
update strategies are supported:

• Patch - version change without major changes in application settings and without any changes in
deployment logic. In particular, all allocated resources are left as is, and no changes in application
mapping scheme are allowed. Moderate changes in application settings are allowed, however
several classes of changes which may lead to ambiguity are prohibited. See details in the Settings
and Requirements sections.

Such restrictions allow unattended update of all application instances, thus making patches is a
preferable way to apply crucial changes, such as security fixes.

If a patch fixes problem that affects all software users, it SHOULD declare the recommended
element. Otherwise, it is assumed that patch fixes some specific problem, or implements additional
functionality and is intended to be installed only by those users who are experiencing the problem.

• Upgrade - version change which allows complex changes in application settings and deployment
logic. This operation may require user attendance.

A Package may specify which versions it can update with help of match attribute. This attribute
contains XPath expression that will be evaluated against metadata of the installed packages with the
same id (or name/packager pair for older packages) and lower version/release numbers. If specified
XPath expression results in non-empty nodeset on some examined application metadata - the package
is considered to be an update for the examined application.

The XPath expression must assume http://apstandard.com/ns/1 to be the default namespace.

Attribute mode defines how upgrade procedure will proceed. Following options are possible:

• No mode attribute provided. In that case upgrade script executed after replacing old set of
application files with files from new version of application.

• When mode attribute equals to managed both old and new application directories available during
upgrade script execution. Path to old application installation available in environment variables
OLDWEB_<id>_DIR and path to new application directories available in environment variables
WEB_<id>_DIR while upgrade script execution. On successful script finish old directories
SHOULD be removed.

• When mode attribute equals to backup upgrade happens in following steps:

15
Application Packaging Standard
- Package Format Specification

• old instance version backed up

• new instance version created

• restore procedure initiated on new instance

• upgrade script executed

Restore procedure SHOULD be able to restore data backed up by earlier versions. In case when
older version of application has no backup script defined and newer version of application support
upgrade mode backup from such old version backup script from target version of application
MUST be called for backup data.

If the update specification is absent, it is supposed that updates are not supported by the package at all.

For exact version comparison a Controller MUST be able to compare packages versions as specified
in Package Version section of specification with help of < > <= >= and = XPath operator. XPath
extensions function should be available to compare complex versions vercmp(a,b). Binary
"vercmp" returns -1, 0, or 1 depending on whether the left argument is version-wise less than, equal
to, or greater than the right argument using RPM version compare rules.

Example 1. Specification of exact updatable versions

Such specification means that package can patch the installed version 2.0.1 or 2.0.2 and upgrade
version 1.0.1.

Example 2. Specification of updatable version ranges

<patch match="/application/version > '2.0'" recommended="true" />
<upgrade match="/application/version > '1.0'" />

Such specification means the following:

• If the installed version is greater than 2.0, patch is possible. Patch contain crucial fixes, affecting
all application users.

• If the installed version is greater than 1.0 and less or equal to 2.0, upgrade is possible.

Example 3. Upgrade using managed mode

Upgrade in managed mode, no version restrictions.

Example 4. Compare versions with vercmp

Controller will select all versions greater then 2.1.0a.

5.1.16. Content Delivery Methods

16
Application Packaging Standard
- Package Format Specification

<dll:register path="win/some.dll"/>
</content>

Application may require a special processing of application's archive content prior to actual usage.
Allowed content processing options are defined in aspects. See DLL Content Processing Method for
more details.

5.1.17. Global Settings

<global-settings>
<setting id="host">
...
</setting>
</global-settings>

Package may have global settings that are visible and affect all instances of application services. Global
settings SHOULD be set prior to any service provision. Such settings are declared by the global-
settings element within the application description. When a global setting is changed, all instances
of the application services need to be reconfigured immediately. Global settings MUST NOT use the
value-of-setting attribute.

5.2. Services

Application is supposed to provide services to its users. Complex applications can provide several
services of different nature and logic. Distinct services are declared with the service elements:

<application>
<name>Personal Information Manager</name>
...
<service id="contacts">
...
</service>

</application>

Each service may feature its own settings, use its own resources and require a special provisioning
activity. Each service in the package MUST be uniquely identified by id attribute within application
package.

Services can be nested. Provision of child services is performed in the scope of already provisioned
parent service. Parent service is assumed to be an environment for child services. Entire host is an
environment for the root services.

<application>
<name>Webmail</name>
...
<service id="email">
...
<service id="mailbox">
...
</service>
<service id="addressbook">
...
</service>
</service>
</application>

Child services are allowed to reference settings values and resources of parent service. Package MUST
contain at least one root service.

17
Application Packaging Standard
- Package Format Specification

During updates package SHOULD NOT alter the services hierarchy in a way that may introduce
ambiguity in update of already provisioned services. In particular, new version of package SHOULD
NOT:

• remove services from hierarchy

• move services from one hierarchy level to another

• move services from one hierarchy branche to another

A Controller MUST refuse to update already provisioned service instance if its place in the service
hierarchy has been changed. Service instances may be updated individually if the provision method
allows this.

A service may define:

• end-user license agreement

• control elements to be added to user interface

• settings for the service instance

• required resources

• activities which must be performed upon service provisioning

In order to help Control Panel to display services information to customers service MAY provide hints
on its kind with help of class attribute. This specification declares the following classes of services:

account - a personal user account in parent service

service - discrete function of the application
ecommerce - E-commerce service
If a Controller encounters unknown value of this attribute it should treat the attribute as unspecified
and ignore it.

Singular service can be instantiated only once under unique parent. Such service should be marked with
singular equal to true. Controller will allow to create several instances of non-singular services.

5.2.1. Service Summary

Service SHOULD be described with a brief summary information.

Example 5. Service summary information

<service id="email">
<presentation>
<name>Email</name>
<name xml:lang="de"> ... </name>
<summary>Electronic mail address with mailbox</summary>
<icon path="images/email.gif"/>
...
</presentation>
...
</service>

5.2.2. License Agreement

<license must-accept="true">
<free/>
<text>
<name>GPLv2</name>
<file>licenses/gplv2.txt</file>
</text>
<text xml:lang="de-DE">

18
Application Packaging Standard
- Package Format Specification

<name>GPLv2</name>
<file>licenses/gplv2-de_DE.txt</file>
</text>
<license>

<license>
<text>
<name>Revised BSD</name>
<url>http://opensource.org/licenses/bsd-license</url>
</text>
</license>

A license declaration MAY include name of the license, whether the license must be accepted by a
user, and either a full path to the license file in the package or a URL of the full text of the license.
The file element MUST be a full path in the archive to the existing file. Application license may be
characterized as free or commercial by using appropriate free or commercial element.

5.2.3. Information Links

The packager may declare links to external web resources or to a document from package that a
control panel should show for the given service. Text to be shown for the link is specified as the link
element's value. A control panel SHOULD show only informational links relevant for current user's
locale.

If link points to a document from package, its href attribute must contain file URL path from the
package with empty host part, for example file:///doc/deployment.pdf. Otherwise href
attribute must contain URL of an external web resource.

The class attribute MAY be used to inform a control panel about the destination web resource
meaning. The following values of this attribute are predefined:

official - official description of application and its features

community - a portal or forum for application community
howto - howto articles or general application documentation
support - support service site
demo - online application demo
deployment-guide - deployment instruction for application package
user-guide - end-user's guide for application package
Controller MAY use this information when grouping the links or optionally displaying them.
Controller SHOULD ignore unknown values of the class attribute and treat it as unspecified.

5.2.4. Entry Points

Packager may declare entry points to be used for a given service. When a Controller provisions a
service with entry points, it MAY provide user with the choice of what entry points to show in control
panel interface and where.

19
Application Packaging Standard
- Package Format Specification

Example 7. Entry points

<entry-points>

<entry dst="/info">
<label>Information service</label>
</entry>

<entry dst="/guest">
<label>Guest view</label>
<label xml:lang="de-DE">...</label>
<description>View the gallery as user not logged in</description>
<icon path="images/icon-guest.png"/>
</entry>

<entry class="control-panel" dst="/admin" method="POST">

<label>Administrative interface</label>
<icon path="images/icon-admin.png"/>
<variable name="username" class="login">admin</variable>
<variable name="password" class="password"
value-of-setting="admin_password"/>
</entry>

<entry dst="/stats{-prefix|/category/|default-category}" method="GET">

<label>Statistics</label>
<icon path="images/icon-stats.png"/>
<variable name="default-category"
value-of-setting="category_to_show_by_default"/>
</entry>

<entry dst="{isp}/account/{account}" method="GET">

<label>My Account</label>
<icon path="images/icon-money.png"/>
<variable name="isp"
value-of-setting="isp_url">http://example.com</variable>
<variable name="account" class="login" value-of-setting="login_in_isp"/>
</entry>

</entry-points>

The dst attribute of an entry point may contain absolute or relative URI of the entry point. Templates
conforming to [URI Templates] are allowed. For relative URIs, absolute URL will be generated when
entry point is being displayed, pointing to the base URL of application + URI of entry point. GET
or POST HTTP request method MAY be declared to be used to access HTTP entry point. GET is
assumed by default.

When displaying an entry point, Controller SHOULD use the provided label, description and icon.
The icon/@path attribute MUST contain a full path in archive to the icon file. The icon SHOULD
be a 64x64 pixel image in PNG format using alpha transparency. JPEG and GIF formats MAY be
used as well, but their use is discouraged.

The entry/@class attribute MAY be used to inform Controller about the entry point designation.
The following values of this attribute are predefined:

control-panel - entry point leads to the service control panel

login - entry point leads to the login page
frontpage - entry point leads to the application's front page
check - entry point leads to page that displays application health information
Controller MAY use this information for displaying the entry point. Controller MUST ignore
unknown entry/@class and treat such entry point as being without explicit class specification.
Application MAY declare several entry points with the same class attribute.

Entry point MAY declare request variables to be specified when user clicks entry point in control
panel interface. Variables values may be taken from actual service settings using the value-of-
setting attribute or explicitly specified as the variable element value. If the specified setting
has empty value, the variable element value MUST be used. These variables are also used for URI

20
Application Packaging Standard
- Package Format Specification

Templates expansion. Variables with duplicate names are allowed and, if present, MUST be used for
arrays representation as defined in [URI Templates] 'prefix' operator (4.4.4), 'suffix' operator (4.4.5)
and 'list' operator.

If the POST request method is used, variables MUST be submitted using the application/x-
www-form-urlencoded encoding. In case of the GET method, variables must be submitted as
specified by URI template syntax. If URI template is not used, variables are submitted using the
application/x-www-form-urlencoded encoding.

The variable/@class attribute MAY be used to inform a Controller about the request variable
meaning. The following values of this attribute are predefined:

login - request variable contains login

password - request variable contains password
locale - request variable carries localization information. Value of this parameter must be as
described in the Settings for Service Appearance Customization section.

Controller MAY provide arbitrary values for such variables basing on its own considerations.
Controller MUST ignore unknown variable/@class and treat such variable as variable without
explicit class specification. Application MAY declare several variables with the same class attribute.
Controller SHOULD provide equal values for variables with the same class.

5.2.5. Service Settings

Applications often need additional parameters for successful installation and configuration. While
most of the questions asked during conventional application installation are related to various
resources and answers may be provided by Controller without user intervention, some settings need
to be entered by user. Controller MUST keep state of application settings values to pass them to the
configuration/update scripts.

Settings are declared in the settings elements in services description. Each setting element
represents a single setting to be asked from user.

To make user interface more convenient, the following information is supplied for each setting:

name - short textual label for the setting

description - description of the setting
default-value - default value for the setting
error-message - error message to be presented to user when the setting is not validated
type - data type of setting (string, number, enum, etc.)

Settings may be declared as "installation only". Settings of this type need to be set up during
service provisioning and should not be reconfigured later. This includes all settings which may be
configured from the application, as any reconfiguration in the control panel will effectively reset
user customizations done in application. Such settings are marked with the installation-only
attribute.

If a setting has the track-old-value attribute and value of the setting is changed, Controller
MUST provide old value together with new one when performing service instance reconfiguration.

If a setting has the optional attribute and value of the setting is not specified, Controller MUST
NOT apply type validation rules for setting's value and SHOULD use usual algorithm for calculating
of default value if applicable. If it is no optional attribute defined this setting is treated as mandatory
and Controller SHOULD NOT allow entering empty value for the setting unless it is allowed by
validation rules.

Regular settings are visible only to service that declares them. Settings with the same name/id are
allowed in different services.

Setting that should have a unique value within some scope should have an uniq attribute. This
attribute may have one of the following values:

21
Application Packaging Standard
- Package Format Specification

global - The setting value should be unique for all application instances provisioned in all global
contexts.
application he setting value should be unique for all application instances provisioned in the
global context.
owner - The setting value should be unique for all application instances of the customer.
service - The setting value should be unique for all service instances provisioned in the application
instance.
Once setting defined as unique Controller MUST arrange setting value unicity in requested scope.
And refuse non-unique user input or auto-configuration.

All settings identified by the same uuid attribute and have uniq attribute defined are validated for
unicity between each other by Controller.

Setting may be hidden from application owner by providing visibility attribute with value
hidden. If no this attribute specified setting threaded as visible.

Setting may be protected from editing by both application owner and provider by protected
attribute with value true. If no this attribute specified setthing is threaded as available for editing.

Setting SHOULD be filled by (pre)controller automattically in case when generate attribute set
to one of values:

sequence - sequintal number,

uuid - GUID identifier,
random - random number,
password - auto-generated password.
Controller MUST satisfy any other requirements while generation of value if any exist for the setting.

Child services may reference values of parent services settings using the value-of-setting
attribute. This attribute specifies ID of parent service setting whose value must be used for the given
setting. The appropriate parent setting is searched in ascending order. If a parent service does not
contain such setting, the next parent is examined upward. Thus, referencing through several levels of
nesting is allowed. Referenced setting MUST be declared in the package. When the referenced setting
value is changed, the affected service instances must be reconfigured. It is prohibited to reference to
settings which, in turn, references another settings.

When application is upgraded, it is prohibited to transform settings with the same id from being
installation-only and to replace setting value with reference to value of another setting (using the
value-of-setting attribute). This restriction is introduced to protect application instance settings
values.

For patches it is also prohibited to introduce new settings without default values, as this prevents
unattended patch installation.

Settings may be grouped by the group element. Group MAY have a name declared by the name
element. Groups without specified name are called anonymous . Group contains a list of settings and
MAY contain anonymous groups. Settings and groups are listed in the order suggested to be used in
interface.

5.2.5.1. Data Types

Settings are typed, Controller SHOULD use the type information to validate input. The following
types are defined:

Type Values Optional restrictions

boolean true , false
string, Unicode string min-length Minimum acceptable length in Unicode
password characters.
max-length Maximum acceptable length in Unicode
characters.

22
Application Packaging Standard
- Package Format Specification

Type Values Optional restrictions

regex Regular expression, subset of PCRE: .*+?
meta symbols, () grouping, [] character
classes (only individual characters, ranges
and class negation ^ ), {,N} , {M,} ,
{M,N} repetition suffixes.
integer A 64-bit signed min Minimum acceptable integer
integer number value (inclusive). The
least possible value is
-9223372036854775808.
max Maximum acceptable integer
value (inclusive). The
greates possible value is
9223372036854775807.
float A double- min Minimum acceptable real value
precision 64-bit (inclusive).
floating point
max Maximum acceptable real value
number with
(inclusive).
values from
value space m
× 2^e, where
m is an integer
whose absolute
value is less
than 2^53, and
e is an integer
between -1075
and 970.
email email address,
as defined in
[RFC 2822]
domain-name DNS domain
name, as
defined in
[RFC 1035]
Setting
attribute
class to
value
domain-
name will
instruct
controller to
substitue here
selector with
available
domains.
host-name Either DNS
domain name,
as defined in
[RFC 1035] or
IP address.
enum One of supplied
identifiers

23
Application Packaging Standard
- Package Format Specification

Type Values Optional restrictions

list List of values order If attribute provided - order
of some type of items is significant. Possible
attribute values: id - order
items by id, name - order
items by name, custom - let
customer order items himself.
min-items Minimal allowed number of
items in list (inclusive).
max-items Maximal allowed number of
items in list (inclusive).
element-type Type of elements. May
be string, integer,
float, email, domain-
name, host-name, enum.
Restrictions from appropriate
types also allowed here.
List of default values
MAY be provided in child
default-value elements.
For enum element-type
Child choice elements MAY
be provided.

5.2.5.2. Settings Semantics

There are settings which are often required by applications. To give implementers a way to create
better interfaces (predefined settings may be used by control panel to provide values without user
interaction), the class attribute of setting or settings group may be used to inform Controller about
the setting meaning.

The following values of the class attribute are predefined:

authn - settings related to user authentication

presentation - settings which carry presentation and UI information
web - web site-related settings
vcard - personal preferences of service user
Controller MUST ignore unknown class value and treat such element as being without explicit
semantics specification.

5.2.5.2.1. Authentication Settings

Settings group which declares class="authn" MAY use the following classes of settings:

login - login name of service user

password - password of service user

Example 8. Authentication Settings

<group class="authn">
<setting id="user_account_name" type="string" class="login">
<name>User login</name>
</setting>
<setting id="user_pwd" type="password" class="password">
<name>Password</name>
</setting>
</group>

24
Application Packaging Standard
- Package Format Specification

5.2.5.2.2. Settings for Service Appearance Customization

Settings group which declares class="presentation" MAY use the following classes of
settings:

locale - default locale of service

Values of the setting with class="locale" MUST be in format defined in [RFC 3066]. It is
REQUIRED to use two-part locale identifiers with [ISO 639] language name as the first part and [ISO
3166] country code as the second part. In other words, 'i-' or 'x-' locale names MUST NOT be used.

It is RECOMMENDED to use the enum type for the setting with class="locale" to declare all
languages supported by the application.

Example 9. Service Appearance Settings

<group class="presentation">
<setting id="user_locale" type="enum" default-value="en-GB" class="locale">
<name>Default locale</name>
<choice id="en-GB">
<name>English</name>
</choice>
<choice id="fr-FR">
<name>French</name>
</choice>
<choice id="de-DE">
<name>German</name>
</choice>
</setting>
</group>

5.2.5.2.3. Settings for Web Site Preferences

Settings group which uses class="web" MAY use the following classes for settings:

title - Web site title

description - Web site description

Example 10. Web Site Settings

<group class="web">
<setting id="site_title" type="string" class="title"
default-value="Homepage">
<name>Site Title</name>
</setting>

<setting id="site_description" type="string" class="description"

default-value="Personal Playground">
<name>Site Description</name>
</setting>
</group>

5.2.5.2.4. Personal Information Settings

Settings group which declares class="vcard" MAY use classes of settings defined in [HCARD-
PROFILE]

In order to create [HCARD]-compatible XML document, an anonymous nested settings groups MUST
be used for declaring hCard properties and the name elements with attribute class set to type value
MUST be used for declaring subproperties.

25
Application Packaging Standard
- Package Format Specification

Example 11. Usage of nested groups of settings

Controller MAY perform implied optimizations according to [HCARD].

The name element MUST NOT contain both the class and the xml:lang attributes. Only one
name element with declared class attribute is allowed within one settings group.

5.2.6. Resources

The Resources section of metadata describes what usage values are reported by application. This
information may be used by controller for application monitoring and resource accounting.

Example 12. Resources reported by application

<resources>
<resource id="users" class="item" limiting-setting="users">
<name>Number of users created in application</name>
<description>Number of active users created within application</description>
</resource>
<resource id="folders" class="item" limiting-setting="folders">
<name>Number of folders</name>
<description>Total number of active directory folders used by application</description>
</resource>
<resource id="traffic.download" class="kb">
<name>Download Traffic</download>
<description>Total number of kbytes downloaded by application</description>
</resource>
</resources>

Resource is identified by unique string in attribute id. Attribute class gives a hint to controller on
this resource units of measure and what to display to an end-user. Some class values are defined by
this specification: item, b, kb, mb, gb.

Application may give a hint to controller what settings limit this resource usage by limiting-
setting attribute. So, control panel will be able to display both current resource usage and its actual
limit to user.

Reporting of resource usage happens for all resources together with resource-script execution.

5.2.7. Requirements

The Requirements section in metadata describes what conditions should be met to provision a service.
Requirements usually request particular resource to be allocated, or specific configuration to be
performed.

26
Application Packaging Standard
- Package Format Specification

Example 13. Requirements of Web Application

<requirements
xmlns:php="http://apstandard.com/ns/1/php"
xmlns:db="http://apstandard.com/ns/1/db">
<php:version min="5.0.2"/>
<choice>
<requirements id="mysql">
<php:extension>mysql</php:extension>
<db:db>
<db:id>main</db:id>
<db:default-name>wiki</db:default-name>
<db:can-use-tables-prefix>true</db:can-use-tables-prefix>
<db:server-type>mysql</db:server-type>
<db:server-min-version>4.0</db:server-min-version>
</db:db>
</requirements>
<requirements id="postgresql">
<php:extension>postgresql</php:extension>
<db:db>
<db:id>main</db:id>
<db:default-name>wiki</db:default-name>
<db:can-use-tables-prefix>false</db:can-use-tables-prefix>
<db:server-type>postgresql</db:server-type>
<db:server-min-version>7.4</db:server-min-version>
</db:db>
</requirements>
</choice>
</requirements>

Requirements belong to the "requirement types". Requirement types are defined in aspects. Each
requirement type has an associated unique XML QName (element name + namespace) and an element
schema (preferably in RELAX NG). Every requirement should be described as an XML element
according to its schema.

Every requirement type has associated rules (in natural language) of how to satisfy the requirement
during the instantiation as the part of the requirement type definition in aspect.

Individual requirements form a complex requirement which needs to be satisfied by Controller. This
is performed by logical 'AND' of requirements (when they are just placed in the requirements
section side-by-side), and logical 'OR' of requirements when they are placed in the choice sub-
element inside the requirements element. Controller has to ensure the logical truth of a complex
requirement (this means not all individual requirements need to be satisfied).

Only one level of choices is allowed to simplify building the GUI.

For each choice element, the CHOICE_<id> environment variable must be passed to the configure
script, with the value of the id attribute of the selected requirements element.

Every resource allocated for application instance as a result of satisfying requirements MUST be
preserved during upgrade. Exact semantics of preservation is left to the requirement specification.

No changes in application instance resources are allowed during patches. Therefore, Controller MUST
preserve all resources allocated for previous version of service and MUST NOT analyze requirements
of new version.

5.2.7.1. Requirements Propagation

Information about requirement being satisfied in parent service must be available to child services.
That is, the set of environment variables passed to the configuration script of child service must
also contain appropriate variables with information about satisfied requirements of parent service.
Requirements of child service override value of propagated variables.

27
Application Packaging Standard
- Package Format Specification

5.2.8. Service Provision

Application service may be provisioned in a variety of ways depending on available environment or

application nature. Provision methods are declared with the provision element.

Application may support different provision methods depending on which requirements were satisfied
by Controller. This is performed by using the when-chosen element. It references selected
requirements branch by specifying requirements-id attribute's value.

Controller MUST choose appropriate provision method according to the satisfied requirements
branch. When there is no when-chosen element referencing the chosen requirements branch, or
no requirements branches are defined, the default provision method specified without the when-
chosen element MUST be used. If it is absent, provision process MUST be aborted.

Example 14. Different Provision Activities

<when-chosen requirements-id="arch-x86_64">
<mapping url="/" path="cgi/x86_64"/>
</when-chosen>

<mapping url="/" path="cgi/i386"/>

</provision>

The snippet above demands creation of URL mapping pointing to the cgi/x86_64/ directory when
the service is provisioned in x86_64 environment, and into cgi/i386/ for other architectures.

When application is updated, the following two types of provisioned services are distinguished:

• those which require individual update procedure

• those which will be updated automatically during update of the parent service

This division depends on provision methods being used for the service. If at least one of used provision
methods requires individual update, the update procedure MUST be performed for all the service's
provision methods. If no provision methods require individual update, Controller MUST NOT perform
update procedures for the service.

5.3. Service Provision Methods

This specification defines the following provision methods: URL Mapping and Configuration Script .

5.3.1. URL Mapping

Web applications are designed to handle incoming requests. URL mapping describes how to map the
requested URLs to the particular handlers or files.

28
Application Packaging Standard
- Package Format Specification

Example 15. URL Mapping of Web Application

<url-mapping>
<default-prefix>forum</default-prefix>
<installed-size>5242880</installed-size>

<mapping url="/" path="htdocs"

xmlns:php="http://apstandard.com/ns/1/php"
xmlns:mod-python="http://apstandard.com/ns/1/mod-python">
<php:handler>
<php:extension>php</php:extension>
<php:extension>pinc</php:extension>
</php:handler>

<mapping url="upload">
<php:handler><php:disabled/></php:handler> 
<php:permissions writable="true"/>
</mapping>
<mapping url="stat" virtual="virtual">
<php:handler><php:disabled/></php:handler>
<mod-python:handler>com.example.StatHandler</mod-python:handler>
</mapping>
</mapping>
</url-mapping>

The example mapping describes three contexts: URLs starting from the /, URLs starting from the /
upload and URLs starting from the /stat. The two first are mapped to the file system, the third one
is virtual (the mod_python aspect is not defined in this specification, so this is placed here just for
illustrative purposes).

The default-prefix element defines a segment of URL path component which should precede
the service instance root by default. Controller is allowed to change it. Controller MUST normalize
leading and trailing slashes of default prefix when forming the final URL.

The site-root element defines requrement of URL mapping to be on root of web site. Controller
MUST place that URL mapping as root mapping of site. This element MUST appear only in top level
of URL mapping root service.

Package may include a declaration of approximate size of a single URL mapping instance, to
help Controllers estimate the disk space resources needed for service provisioning. For this, the
installed-size element should be specified with the declared size of URL mapping instance
size in bytes.

Mappings may be nested, and there MUST NOT be two mappings with such URLs that the first URL
is the prefix of the second URL. In other words, the construction

is prohibited, and MUST be rewritten as

All url s in mappings are relative to the parent URL mapping. Absolute URLs are PROHIBITED in
the url attributes except the root mapping where url value MUST be '/'.

The path attribute of mapping is always path from the root of archive to the directory inside the
archive, it must not have the / character at the start.

29
Application Packaging Standard
- Package Format Specification

If mapping has an explicit path attribute, then the mapping is associated with the directory specified
by this attribute. The association means that any URL which is in the scope of the given mapping
(URLs in scopes of inner mappings are not in the scope of outer mapping) and is not handled by the
handlers declared in the mapping needs to be served as the file from the directory specified.

If a mapping has neither an explicit path attribute nor a virtual attribute, then the directory
associated with the given mapping is calculated from the directory associated with the parent mapping
appending the relative URL that the given mapping has. E.g., for the following declarations

<mapping url="/" path="htdocs">

mapping '/' is associated with the htdocs/ directory, mapping '/foo/bar' is associated with the
htdocs/foo/bar directory, mapping '/foo/bar/baz' is associated with the htdocs/foo/bar/
baz directory, and mapping '/foo/bar/quux' is associated with the htdocs/foo/bar/somedir
directory.

If mapping has an explicit virtual attribute equal to virtual, then the mapping is not associated
with any directory, and requests to the URLs in the scope of this mapping must return 'Not found'
error, if not handled by handlers declared in the given mapping.

If mapping has an explicit virtual attribute equal to redirect, then the controller SHOULD
configure HTTP redirect to URL denoted by href mapping child.

If mapping has an explicit shared attribute equal to true, then the controller SHOULD share
contents of directory referred by this mapping between all instances of the version of application.

If an outer mapping does not have an associated directory, then the inner mappings without explicit
path element do not have an associated directory too.

If the whole application mapping is not virtual (meaning that there is at least one mapping without the
virtual attribute), the root mapping MUST have the path attribute.

Controller MUST use mapping information for deployment and upgrade of application instance files.
Files deployment MUST be driven by URL mapping rules.

Aspects declare types of URL handlers, rules of how to process them. Rules regulating propagation
of specific URL handlers to inner mappings are also declared in aspects.

The handler defined latter overrides the former. In the following example, all *.php files will be
processed by CGI handler.

5.3.1.1. Mapping Information Propagation

Information about parent service URL mappings made must be available to child services. A Controller
MUST provide details of parent's URL mapping in form of appropriate environment variables supplied
for configuration script of child service. The set of environment variables is the same as was supplied
for parent's service configuration script. Information propagates until child service declares it's own
URL mapping.

30
Application Packaging Standard
- Package Format Specification

5.3.1.2. Update
URL Mapping provision method requires individual update of provisioned services. During update,
application files will be overwritten. Any scheme of files overwriting during upgrade is permitted,
given that it satisfies the following statements:

• Every file existing in both old and new packages gets replaced by new version.

• All files existing in old package, but not in new, are deleted.

• All files existing in new package are installed, overwriting any files present on file system.

• No other file is touched - all files created by users are kept intact.

Thus, files expected to be modified during application work need to be created manually by the
configuration scripts upon service provision.

During patch, no changes in mapping structure are allowed. Controller MUST leave mapping as it
was for previous version of application. Mapping files MUST be replaced by new versions. File
overwriting semantics is the same as for upgrade.

5.3.2. Configuration Script

A service may be provisioned with the help of configuration script. This script will be invoked during
application service provisioning, cancelling, updating and reconfiguration. Availability of the script
is declared by the configuration-script element. Different configuration scripts for different
services are allowed.

<configuration-script name="configure">
<script-language>php</script-language>
</configuration-script>

Configuration scripts MUST reside in the scripts directory in the package root directory. Name of
configuration script is specified with the name attribute.

Configuration script MUST declare programming language it is written in using the script-
language element. Controller will use appropriate interpreter to run the configuration script. Valid
interpreters are defined in aspects specification . This specification defines a set of php , perl ,
jscript and vbscript interpreters. Binary executable configuration scripts are allowed. In this case,
the binary-executable element must be used.

Controller MUST run configuration script within environment where the application is being installed.
Configuration script which requires high privileges in order to run MUST use the privileged
attribute. Controller MUST run such script with superuser privileges. Controller MUST NOT run in
privileged mode configuration script which does not declare this attribute.

During the configuration script execution, the working directory MUST be set to the actual location
of the script. All content of the scripts directory MUST also reside in the script current working
directory.

If any script invocation fails (script returns a non-zero exit code), it MUST be treated as fatal error
and Controller MUST refuse to continue operation. Stdout and stderr I/O streams of the script should
be captured to log error or treat output values, see configuration script output.

5.3.2.1. Configuration Script Actions

Configuration script is invoked during a service is provisioning, reconfiguration, upgrading or
cancelling.

5.3.2.1.1. Service Provisioning

Configuration script is invoked when a service is provisioned. By the moment of invocation, all
resources declared by the service MUST be already allocated and instance files unpacked and placed
to the file system. The script is invoked with the following arguments:

31
Application Packaging Standard
- Package Format Specification

install

5.3.2.1.2. Upgrading Application

Configuration script provision method does not require individual update.

When a service instance is upgraded, the script of new application version is invoked with the
following arguments:

upgrade <old version> <old release>

where <old version> is the old version, and <old release> is the old release of the application
being upgraded.

By the moment of invocation, all resources needed by the new version of application MUST be already
allocated.

5.3.2.1.3. Changing Settings

Configuration script is invoked when already provisioned service is being configured (this does not
include provisioning and canceling). The script is invoked with the following arguments:

configure

5.3.2.1.4. Canceling Service

Configuration script is invoked during a service cancelation before all allocated resources are freed
and instance files removed. The script is invoked with the following arguments:

remove

5.3.2.1.5. Enabling/Disabling Service

Configuration script MAY be able to manipulate service status by enabling and disabling service. A
service which status is disabled MUST NOT serve its users or operate on behalf of service owner.
Configuration script MUST declare ability to manipulate service status with the status-control
element.

<configuration-script name="reseller">
<script-language>php</script-language>
<status-control/>
</configuration-script>

In this case, Controller MUST invoke the script with the following arguments:

enable
disable

to make the appropriate service status changes. Configuration script MUST return success if service
is already has a requested status.

5.3.2.2. Environment Variables

All information about application, resources and settings is passed to configuration script through
environment variables.

If environment variables in operating system contain bytes (opposed to Unicode codepoints), then
UTF-8 encoding is used. All the IDN DNS names passed through environment MUST be passed in
Unicode, not in Punycode encoding (in xn--blahblah form).

32
Application Packaging Standard
- Package Format Specification

Several predefined environment variables are always passed to script, and any aspect may declare
additional environment variables.

Identifier of service being configured should be passed to configuration script with SERVICE_ID
environment variable.

SERVICE_ID=gallery

5.3.2.2.1. URL Mapping Variables

Services which utilize URL Mapping provision method demand the following environment variables
to be passed to configuration script.

Full URL specifying where the service is available, represented by the four environment variables
corresponding to the URL parts as defined in [RFC 1738]:

BASE_URL_SCHEME - URL scheme. Allowed values: http , https

BASE_URL_HOST - URL host.
BASE_URL_PORT - URL port (may be omitted if default port for protocol is used: 80 for http, 443
for https).
BASE_URL_PATH - URL path including trailing slash.
For example:

BASE_URL_SCHEME=http
BASE_URL_HOST=example.com
BASE_URL_PORT not defined
BASE_URL_PATH=phpBB/

Note that leading slash is not included in BASE_URL_PATH.

Also, for each mapping, except for those which do not map to file system, the WEB_<id>_DIR
environment variable must be passed with the absolute path to the directory to which the mapping
maps, where id is the full URL path of the mapping, with all '/' characters converted to '_'.

I.e., for the following URL mapping declaration:

<mapping url="/" path="htdocs">

instantiated by the URL http://domain.name/example, the configuration script may be

provided with the following environment variables:

WEB___DIR=/var/www/vhosts/domain.name/public_html/example/htdocs
WEB__foo_bar_DIR=/var/www/vhosts/domain.name/public_html/example/htdocs/foo/bar
WEB__foo_bar_baz_DIR=\
/var/www/vhosts/domain.name/public_html/example/htdocs/foo/bar/baz
WEB__foo_bar_quux_DIR=/var/www/vhosts/domain.name/public_html/example/somedir

5.3.2.2.2. Settings

For each setting declared in a service, corresponding environment variable SETTINGS_<id>

MUST be passed on to the installation script, where <id> is a value of the id attribute
in the setting description. If setting have list type for ever list value environment variable
SETTINGS_<id>_<seq> MUST be passed to configuration script instead. Where seq represents
number of appropriate list element, starting from 1.

For each setting with the track-old-value attribute, corresponding environment variable
OLDSETTINGS_<id> MUST be passed on to the configuration script, holding the previous value
of the setting.

33
Application Packaging Standard
- Package Format Specification

During the service provisioning, all the declared service settings and package global settings MUST
be passed to the configuration script. No old values should be passed.

During the service reconfiguration, cancelation and service status change, all the declared service
settings and package global settings, except marked as installation-only, MUST be passed to the
configuration script.

During the service instance upgrade and patching, all settings of the new version of service which exist
in old version MUST be set to corresponding values from the old instance. If a settings validator does
not allow a value from the old instance, such setting MUST be set to the default value. All settings from
new package which do not correspond to the settings from old package MUST get the default values.

For the boolean, string, float, and integer property value data type elements, the
corresponding environment variables must contain values entered by user.

For the enum setting, the environment variable must contain the identifier of one of the values
(defined by the id attribute of the enum/choice element) selected by the user (e.g., if you have
choice with id interface_color containing options with IDs black and blue, then variable
SETTINGS_interface_color with value black or blue will be exported).

5.3.2.2.3. Aspect-Defined Environment Variables

Aspects also may define environment variables to be passed to configuration scripts: there might
be variables passed when the aspect is used by the package and variables which are passed when a
particular requirement is satisfied during configuration. Consult the aspect specifications for the list
of environment variables that each aspect defines. See Points of extensibility - Environment variables.

5.3.2.3. Configuration script output

When structured-output element is not provided in configuration-script contents
script output and error streams SHOULD be captured by controller for further analysis in case of errors.

When structured-output element is provided in configuration-script contents script

output stream should be captured independently of error stream. And script output MUST be treated in
accordance with configure-output schema below. Error streams SHOULD be captured by controller
for further analysis in case of critical errors. Rest of this chapter is dedicated to this case.

RELAX NG schema of configuration script output:

default namespace = "http://apstandard.com/ns/1/configure-output"

grammar {
start = Output

Output = element output {

## Errors definition
element errors {
Error*
}?,

## Values and properties for settings

element settings {
element setting {
attribute id { text }?,
Setting+
}*
}?
}

## Single error definition

Error = element error {
## Error code
attribute id { text },

## Error related to setting value

34
Application Packaging Standard
- Package Format Specification

attribute setting-id { text }?,

## Message to be shown to end-user

element message {
attribute xml:lang { text }?,
xsd:string
}*,

## Technical error description to be writtent to CP logs

element system { xsd:string }?
}

Setting = Value | Choice

## New setting value

Value = element value {
## Value of setting value
xsd:string
}

## Entries for enum elements choices

Choice = element choice {
attribute id { text },
element name {
attribute xml:lang { text }?,
text
}+
}

Configure script structured output MAY contain errors, errors bind to specific settings and new setting
values.

In case of any errors occurrence configure script SHOULD return error messages specified in
structured output. Error MAY be bound to some service settings. In this case control panel SHOULD
give a hint to user what setting cause an error.

Errors that SHOULD NOT be shown to end user SHOULD NOT have message element.

No errors in structured output and non-zero error code of script execution is treated as fatal error. Error
output SHOULD be logged by Controller in that case.

In case of non-default locale message SHOULD have xml:lang attribute. Configuration script
SHOULD use some appropriate setting to get knowledge about current locale. System erros always
SHOULD be in default locale.

Example of configure script output with errors bind to settings

<output xmlns="http://apstandard.com/ns/1/configure-output">
<errors>
<error id="1093" setting-id="login">
<message>Login name 'jsmith' already exists.</message>
<system>login 'jsmith' is duplications with record id=12384</system>
</error>
<error id="1123" setting-id="password">
<message>Password matches dictionary word</message>
<system>login 'jsmith' password strength too low rate=0.02</system>
</error>
</errors>
</output>

Configuration script MAY return new values for some settings. In this case Controller SHOULD
store returned settings. Element value SHOULD be used to pass returned value. Setting that are not
returned in structured output SHOULD NOT be altered.

In case of configuration error controller MAY treat returned settings as hint to be provided for user
as new setting value in edit form.

35
Application Packaging Standard
- Package Format Specification

If returned setting does not match setting type or/and restrictions controller SHOULD raise fatal error.

Example of configure script output with new settings values

5.3.3. Verification Script

Verification script is very similar to configuration script by semantic but designed for check service
settings for consistency. It SHOULD never change state of application or application instances.
Verification script presented by verify-script element node.

Calling conventions are the same as with configuration script. It supports following actions install,
configure, upgrade.

Verification script can be defined and called in both global context and context of service instance. In
case of global context no resources allocated and no environment variables related to service instance
or resources provided. Call of verification script in global context required for verification of global
settings. Also verification script MAY be called for settings verification before service provisioning.

Usage of element structured-output is allowed here. And should be processed by controller in

same way as processed while execution of configuration script. In additional to possibility to verify
settings values there is also a possibility to return list of choices for enum setting type. In that case
controller SHOULD cache returned list choices and suggest it for settings editing in appropriate
context until new list returned. List may be returned while both successful and not successful script
execution.

Controller MAY execute this script while user press special control for verification (for example
"Verify" button on settings edit screen). Or on just usual install/configure/upgrade operation. It should
be safe to call this script in synchronous mode. To make results of execution visible for user just on
submit.

5.3.4. Resource Script

Resource script reports current resource usage to controller. Script is periodically called by controller.
Resource script presented by resource-script element node.

Resource script follows same calling conventions as configuration script. With only exception that
output stream of the script should be always XML matching schema below.

Application may give a hint to controller how often it should poll application for resource usage value
with poll-interval attribute. It MAY be specified either as number of minutes, like 5m or as
number of hours like 2h or as number of days, like 1d. Controller MAY disregard poll-interval
attribute and decide how often call resource script.

Some resources usage requires time period it was measured over to be reported (i.e. traffic).
Application may report time in seconds as period attribute.

If some resource was not reported in output controller MUST assume that resource is not used.

RELAX NG schema of resource script output:

default namespace = "http://apstandard.com/ns/1/resource-output"

36
Application Packaging Standard
- Package Format Specification

grammar {
start = Resources

Resources = element resources {

## Resource definition
element resource {
## Resource identificator
attribute id { text },

## Resource usage value

attribute value { xsd:unsignedLong },

## Period for that value calculation

attribute period { xsd:unsignedLong }?
} *
}

Example 16. Example of resource usage output

5.3.5. Backup/Restore Script

Operations like backup, restoration or migration may be done with the help of backup script. This
script will be invoked during application backup and restoration. Availability of the script is declared
by the backup-script element. Different configuration scripts for different services are allowed.

<backup-script name="backup.php">
<script-language>php</script-language>
</backup-script>

Backup/Restore script follows same calling conventions as configuration script.

5.3.5.1. Backup/Restore Script Actions

Backup/Restore script is invoked on service backing up, or restoring. Migration operation is treated
as sequential execution of backup and restore operations.

5.3.5.1.1. Service Backup

Backup script is invoked when a service is backing up. By the moment of invocation, all resources
declared by the service MUST be already allocated and instance files unpacked and placed to the file
system. The script is invoked with the following arguments:

backup

On this operation script should backup all sensitive application data to file specified in BACKUP_FILE
variable. Controller should provide appropriate location for backup file and ensure that there is enough
diskspace for file creation.

In case of sufficient element is provided Controller expects that all involved resources are backed
up by backup script. In other words, all resources like database, mailboxes, etc should be serialized
into backup file by backup script.

37
Application Packaging Standard
- Package Format Specification

In case of sufficient element is not provided Controller will backup all involved resources. In
other words, all resources like database, mailboxes, etc are backed up by means of Controller.

Child services should be backed up by this operation. Controller, in turn will preserve set and
configuration of child services.

5.3.5.1.2. Service Restore

Restore script is invoked when a service is restoring. By the moment of invocation, all resources
declared by the service MUST be already allocated and instance files unpacked and placed to the file
system. The script is invoked with the following arguments:

restore

On this operation application should restore all sensitive application data from file specified in
BACKUP_FILE variable.

In case of sufficient element is provided Controller creates all involved resources like database,
mailboxes, etc, but does not fill them with application data.

In case of sufficient element is not provided Controller restores all involved resources. In other
words, all resources like database, mailboxes, etc are created and filled with original data by means
of Controller.

Child services should be restored by this operation, both set of services and content of services.
Controller will arrange restore of service instances and related resources. Restore script responsible
for child service data restoring.

On restore settings of all involved instances SHOULD be set to same values as they was on backup.
Usual rules for settings should be applied. No additional scripts are called except restore script. Global
settings SHOULD not be changed by restore operation.

5.3.5.2. Environment Variables

All information about application, resources and settings is passed to backup script through
environment variables.

Same rules and set of variables are used for backup script as for configuration script .

5.3.5.2.1. Backup file location

Full path to backup file location passed to script in BACKUP_FILE variable. This file should be
writable for backup operation and should be readable for restore operation.

Backup script should operate with file using simple sequential read and write operations.

6. Package Contents Listing

RELAX NG schema of package contents listing:

default namespace sa = "http://apstandard.com/ns/1"

namespace dsig = "http://www.w3.org/2000/09/xmldsig#"

start = PackageList

## Signed application files listing

PackageList = element sa:files {

## Package contents here

element file {
attribute name { text },
attribute size { xsd:nonNegativeInteger },

38
Application Packaging Standard
- Package Format Specification

attribute sha256 { xsd:string { pattern = "[0-9a-f]{64}" } }?

}+,

## List signature(s)
element dsig:Signature {
element dsig:SignedInfo {
element dsig:CanonicalizationMethod {
attribute Algorithm { xsd:anyURI }
},
element dsig:SignatureMethod {
attribute Algorithm { xsd:anyURI }
},
element dsig:Reference {
attribute URI { xsd:anyURI },

element dsig:Transforms {
element dsig:Transform {
attribute Algorithm { xsd:anyURI }
}+
},
element dsig:DigestMethod {
attribute Algorithm { xsd:anyURI }
},
element dsig:DigestValue { text }
}
},
element dsig:SignatureValue { text },
element dsig:KeyInfo {
element dsig:X509Data {
element dsig:X509Certificate { text }
}
}
}*
}

The APP-LIST.xml file MUST be valid according to the schema above. XML namespace of the
package listing will be changed when incompatible changes are introduced.

Signature(s) of package listing file should match [XMLDSIG] specification if present. Enveloped
Signature Transform should be used as transform algorithm.

Usually packager should sign APS package with package certificate. As well as APS certification
authority SHOULD also sign package on successful certification.

7. Points of Extensibility
Aspects are additional specifications that declare how to describe specific needs of applications in
packages, and how Controllers must process the descriptions.

Aspects may extend basic specification in the following ways:

Aspect may declare requirement type.

Aspect may declare URL handler type.
Aspect may declare additional files to be packaged.
Aspect may declare additional environment variables to be passed to configuration script and rules of
how to construct their values by Controller.
Aspect may declare additional languages to be used to run configuration scripts.
Aspect may declare maintenance scripts in addition to the usual configure script in the scripts
directory.
Aspect may declare application provision method.
Aspect MUST declare rules of how Controllers should process additional data supplied in a package.

7.1. Requirement Types

Each aspect may declare several requirement types. Every requirement type describes how to declare
specific requirement of the application.

39
Application Packaging Standard
- Package Format Specification

Every requirement type consists of XML element schema which describes the structure of element
representing requirement, and rules of how to process the requirement.

7.2. URL Handlers Types

Each aspect may declare several URL handlers types. Every URL handler type declares how to
desecribe rules on how to handle URLs which are specific to the declaring aspect in the scope of a
particular mapping.

Every URL handler type consists of XML element schema which describes the structure of element
representing URL handler, and rules of how to process the URL handler. Especially, this should
include the rules of inheriting URL handlers from the outer mappings in inner mappings.

7.3. Additional Files

Aspect may declare that additional files need to be packaged. Aspect MUST NOT declare additional
files in the scripts directory, it is reserved for processing configuration scripts.

7.4. Environment Variables

Aspect may declare additional environment variables to be passed to configuration scripts. Such
variables will be passed to all invocations of configuration script. It is RECOMMENDED to prefix
such variables with the upper-cased name of aspect top-level XML element.

7.5. Additional Scripts

Aspect may declare additional scripts to be run during the package lifetime.

Aspect must provide rules of when to run additional scripts, which arguments and environment
variables need to be passed to the scripts.

7.6. Script Language

Aspect may declare additional language to be used to run a script. In this case, aspect MUST declare
the name of this language to be used in basic metadata, and the rules of how to run the script.

As there is no established registry of programming language names, it is RECOMMENDED to use

lowercased name from the Wikipedia list of programming languages [Langs]

7.7. Application Provision Method

To widen a range of supported applications, it is possible to introduce new application provision

methods in aspects.

7.8. Rules

An aspect must declare the rules of how to process metadata supplied in a package when the package
uses this particular aspect: how to process metadata and files, how to generate values for environment
variables.

8. Common Aspects
This specification defines a number of "common aspects": a set of aspects which are expected to be
implemented in Controllers. However, if an aspect is inapplicable to a particular Controller, it may
be omitted.

8.1. PHP Aspect

This aspect is to be used by web applications written in PHP. This aspect uses the http://
apstandard.com/ns/1/php XML namespace.

RELAX NG schema of PHP aspect

40
Application Packaging Standard
- Package Format Specification

namespace php="http://apstandard.com/ns/1/php"

## URL Handlers
div {
UrlHandler |= element php:handler {
( element php:disabled { empty }
| element php:extension { text }* )?
}
UrlHandler |= element php:permissions {
attribute writable { "true" }?,
attribute readable { "false" }?
}
}

## Requirements
div {
Requirement |= element php:version {
attribute min { text }?,
attribute max-not-including { text }?
}
Requirement |= element php:extension { text }
Requirement |= element php:function { text }

Requirement |= element php:allow-url-fopen { xsd:boolean }

Requirement |= element php:file-uploads { xsd:boolean }
Requirement |= element php:magic-quotes-gpc { xsd:boolean }
Requirement |= element php:register-globals { xsd:boolean }
Requirement |= element php:safe-mode { xsd:boolean }
Requirement |= element php:short-open-tag { xsd:boolean }

Requirement |= element php:memory-limit { xsd:integer }

Requirement |= element php:max-execution-time { xsd:integer }
Requirement |= element php:post-max-size { xsd:integer }
}

8.1.1. Requirement Types

PHP aspect declares the following requirement types: PHP version requirement type, PHP extension
requirement type, PHP function requirement type, and a set of PHP settings requirement types.

Example 17. PHP Version Requirement

<php:version min="4.1" max-not-including="5.0"/>

Requirement of this type is satisfied if the version of PHP enabled on a site is in [min, max-not-
including) interval taken from the requirement. Both limits are optional.

The PHP_VERSION environment variable MUST be passed on to the configuration script with the
version of PHP (as a string value) installed on the Web site where the package is to be installed.

Example 18. PHP Extension Requirement

<php:extension>curl</php:extension>
<php:extension>Zend Optimizer</php:extension>
<php:extension>ionCube Loader</php:extension>

Requirement of this type is satisfied if the specified PHP extension is enabled for the web application.

The names of PHP extensions are specified in the zend_module_entry structure of extension code and
may be obtained by the get_loaded_extensions PHP function.

Example 19. PHP Function Requirement

<php:function>system</php:function>

41
Application Packaging Standard
- Package Format Specification

Requirement of this type is satisfied when the specified PHP function is enabled in PHP.

Example 20. PHP Settings Requirements

<php:allow-url-fopen>true</php:allow-url-fopen>

If a web application needs one of allow_url_fopen, file_uploads, safe_mode,

short_open_tag, register_globals or magic_quotes_gpc settings to be true or false,
the appropriate requirement must be used. Requirements of those types are satisfied when the
corresponding PHP setting has the specified value.

Example 21. PHP Limits Requirements

<php:memory-limit>16777216</php:memory-limit>

If a web application needs a particular value of memory_limit, max_execution_time or

post_max_size settings, it should use these requirement types (defining values in bytes and
seconds).

Requirements of those types are satisfied when the corresponding PHP setting has the value specified
in the requirement or larger.

8.1.2. URL Handlers

Example 22. PHP URL Handler

<php:handler>
<php:extension>php</php:extension>
<php:extension>pinc</php:extension>
</php:handler>

<php:handler><php:disabled/></php:handler>

Handlers of this type require that files with the specified extensions (if no extensions are specified, a
single php extension is assumed) are handled by the PHP interpreter.

Inner mappings inherit handlers from the outer mappings, so the presence of php:disabled
disables PHP in the given mapping.

Example 23. PHP Permission Handler

<php:permissions writable="true">

<php:permissions readable="false">

The situation when a directory and files in the directory to which the given mapping maps should be
writable by PHP interpreter is specified by using the writable attribute with the "true" value. The
"false" value is default, so no explicit attribute for this is required.

The situation when files in the directory should be protected from reading by PHP interpreter is
specified by the readable attribute with the "false" value. The "true" value is default, so no explicit
attribute for this is required.

Inner mappings do not inherit permission handlers from the outer mappings.

8.1.3. Configuration Script Language

This aspect defines the php identifier to be used by configuration scripts. When a configuration script
uses the php language, it MUST be run by stand-alone PHP interpreter. All the requirements described
in the application metadata apply to the interpreter running configuration scripts.

42
Application Packaging Standard
- Package Format Specification

8.2. ASP.NET Aspect

This aspect should be used by web applications which use ASP.NET. This aspect uses the http://
apstandard.com/ns/1/aspnet XML namespace.

RELAX NG schema of ASP.NET aspect:

namespace aspnet = "http://apstandard.com/ns/1/aspnet"

## URL Handlers
div {
UrlHandler |= element aspnet:permissions {
attribute writable { "true" }?
}
UrlHandler |= element aspnet:handler {
( element aspnet:disabled { empty }
| element aspnet:extension { text }* )?
}
}

## Requirements
div {
Requirement |= element aspnet:version { "1.0" | "1.1" | "2.0" | "3.0" | "3.5" | "4.0" | text }
}

8.2.1. Requirement Types

This aspect declares a single requirement type: ASP.NET version requirement. Requirement of this
type is satisfied when the application is installed in virtual directory with the specified version of
ASP.NET enabled.

8.2.2. URL Handler Type

Example 24. ASP.NET URL Handler

<aspnet:handler/>
<aspnet:handler>
<aspnet:disabled/>
</aspnet:handler>

Handler of this type requires that files with the specified extensions (if no extensions are specified,
the default set of ASP.NET extensions is assumed) are handled by ASP.NET.

Inner mappings inherit handlers from the outer mappings, so the presence of aspnet:disabled
disables ASP.NET in the given mapping.

Example 25. ASP.NET Permission Handler

<aspnet:permissions writable="true">

The situation when files in the directory to which the given mapping maps should be writable by the
ASP.NET interpreter is specified by using the writable attribute with the "true" value. The "false"
value is default, so no explicit attribute for this is required.

8.2.3. Configuration Script Language

This aspect defines jscript and vbscript identifiers to be used by configuration scripts (written
in JScript and VBscript correspondingly).

8.3. Database Aspect

This aspect should be used by web applications which need a database to operate. This
aspect uses the http://apstandard.com/ns/1/db namespace. Requirements specific for
database management systems use their own namespaces. This specification defines the http://
apstandard.com/ns/1/db/mysql namespace for requirements specific for MySQL.

43
Application Packaging Standard
- Package Format Specification

RELAX NG schema of database requirement type:

namespace db = "http://apstandard.com/ns/1/db"
namespace mysql = "http://apstandard.com/ns/1/db/mysql"

## Requirements
div {
Requirement |= element db:db {
element db:id { text },
element db:default-name { text }?,
element db:can-use-tables-prefix { xsd:boolean },
element db:server-type { text },
element db:server-min-version { text },

element db:features { DbFeature+ }?

}

DbFeature |= element mysql:privilege {

attribute disabled { "true" }?,
text
}
}

Example 26. Database Requirements

<requirements>
<db:db xmlns:db="http://apstandard.com/ns/1/db">
<db:id>storage</db:id>
<db:default-name>broombla</db:default-name>
<db:can-use-tables-prefix>true</db:can-use-tables-prefix>
<db:server-type>mysql</db:server-type>
<db:server-min-version>4.1.0</db:server-min-version>

<db:features xmlns:mysql="http://apstandard.com/ns/1/db/mysql">
<mysql:privilege>Create_tmp_table_priv</mysql:privilege>
</db:features>
</db:db>
</requirements>

This aspect declares database requirement type. This requirement type should be used when a service
needs a database. The following elements comprise the database requirement type:

id Identifier of the database. This identifier will

be used in environment variables passed to
configuration scripts.
default-name Optional. Proposed name of a database. It is not
guaranteed that the allocated database will use this
name.
can-use-tables-prefix This element must have the true value only if
a service is able to cope with sharing a database
with another services by using prefixed tables.
Otherwise, its value should be false .
server-type This element must be one of the database server
identifiers described below.
server-min-version This element describes the minimum acceptable
version of database server software.
features This element describes peculiarities of required
database and database user that are specific for
database management system.

Requirement of this type is satisfied when the following is true:

44
Application Packaging Standard
- Package Format Specification

New database is allocated for the application.

If can-use-tables-prefix is true , then, instead, an existing database is used, a unique prefix
is chosen so that no tables in this database have this prefix and all other applications using this database
get prefixes.
Allocated database satisfies the server-type and server-min-version constraints.
User is created, or exists already, having a full access to the database.
If the allocated database uses database management system for which specific requirements are
imposed in the features section, they must also be satisfied.

Controller MUST deallocate database when service is canceled. When can-use-table-prefix

is true and existing database was used, Controller MUST remove relevant tables from database.

Database requirements with the same id value are allowed only in different branches of a single
choice grouping. It is illegal to declare database requirements with the same id in different choice
s or in a choice and outside it at the same time.

8.3.1. Environment Variables

When a requirement is satisfied, the following environment variables must be passed to configuration
scripts:

• DB_<identifier>_TYPE . The database server type (contents of the server-type element).

• DB_<identifier>_NAME . The name of allocated (or reused) database.

• DB_<identifier>_LOGIN . The database user login name. This is the full database access user.

• DB_<identifier>_PASSWORD . The database user password. This is the full database access
user.

• DB_<identifier>_HOST . The database server host name or IP address.

• DB_<identifier>_PORT . The port number for connecting to the database server. If the port
number is default for the selected DB server, this variable may be omitted.

• DB_<identifier>_VERSION . The version of the database server

• DB_<identifier>_PREFIX . The prefix of tables in database. MUST NOT exist if the

application owns a whole database. SHOULD NOT exist if a Controller does not support sharing
databases between different applications. Application MUST NOT create or alter tables without
this prefix if it is supplied.

Environment variables DB_<identifier>_HOST and DB_<identifier>_PORT MUST NOT

be specified if an application is to use local transport (UNIX sockets or named pipes) to connect to
database.

8.3.2. Database Server Types

The server-type element describes the name of database server. Currently defined names are:

mysql - MySQL
postgresql - PostgreSQL
microsoft:sqlserver - Microsoft SQL Server

Another names SHOULD be taken from the JDBC drivers registry [JDBCDRIVERS] . Official
database server driver SHOULD be used if more than one drivers are available. JDBC driver name
(and a sub-name if the name specifies the company, as with 'microsoft:sqlserver') is used.

8.3.3. Upgrade

If both old and new version of package require a database with the same id , then this database and its
content need to be preserved. Controller MUST refuse to upgrade database to another database type.

45
Application Packaging Standard
- Package Format Specification

All databases which are declared in old or new packages MUST be accessible during upgrade script
invocation. Thus, application MAY perform database upgrades by issuing new database id in the
package release which requires cross-database upgrade.

8.3.4. MySQL Specific Settings

This specification defines requirements type for privileges of MySQL user on database being allocated.

Example 27. Privileges for MySQL Database

<db:features xmlns:mysql="http://apstandard.com/ns/1/db/mysql">
<mysql:privilege>Create_tmp_table_priv</mysql:privilege>
<mysql:privilege disabled="true">Lock_tables_priv</mysql:privilege>
</db:features>
</db:db>
</requirements>

The names of MySQL privileges are specified in the db table of the mysql database. Controversial
permissions MUST NOT be specified.

8.4. Apache Aspect

This aspect is to be used by web applications which use Apache-specific features. This aspect uses the
http://apstandard.com/ns/1/apache XML namespace.

RELAX NG schema of Apache aspect:

namespace apache = "http://apstandard.com/ns/1/apache"

## Requirements
div {
Requirement |= element apache:htaccess { empty }
Requirement |= element apache:required-module { text }
}

This aspect declares two requirement types: Apache module requirement type and Apache
.htaccess requirement type. Those requirements should be used only if a web application works
exclusively with Apache due to some Apache-specific features.

Example 28. Apache Module Requirement

<requirements>
<apache:required-module xmlns:apache="http://apstandard.com/ns/1/apache">
mod_python
</apache:required-module>
</requirements>

Requirement of this type is satisfied when the specified Apache module is enabled for the application.

Example 29. Apache .htaccess Requirement

46
Application Packaging Standard
- Package Format Specification

Requirement of this type is satisfied when the .htaccess processing is enabled for the application.

8.5. CGI Support

This aspect allows declaring CGI scripts in a package. This aspect uses the http://
apstandard.com/ns/1/cgi XML namespace. Explicit handlers notation uses the http://
apstandard.com/ns/1/cgi/handlers namespace.

RELAX NG schema of CGI URL handler type:

namespace cgi = "http://apstandard.com/ns/1/cgi"

namespace h = "http://apstandard.com/ns/1/cgi/handlers"

## URL Handlers
div {
UrlHandler |= element cgi:handler {
( element cgi:disabled { empty }
| element cgi:extension { handlerType?, text }*
| element cgi:all-files { handlerType? }
)
}

UrlHandler |= element cgi:permissions {

attribute writable { "true" }?,
attribute readable { "false" }?
}

handlerType = attribute h:handler-type {

"executable" | "perl" | "php" | "python" | "ssi"
}
}

Example 30. CGI URL Handlers

<cgi:handler
xmlns:cgi="http://apstandard.com/ns/1/cgi"
xmlns:h="http://apstandard.com/ns/1/cgi/handlers">
<cgi:extension h:handler-type="perl">pl</cgi:extension>
<cgi:extension h:handler-type="perl">cgi</cgi:extension>
</cgi:handler>

<cgi:handler xmlns:cgi="http://apstandard.com/ns/1/cgi">
<cgi:all-files/>
</cgi:handler>

A handler of this type requires that files with the specified extensions (if no extensions are specified,
a single cgi extension is assumed) are handled by running them as CGI scripts. If the all-files
option is declared, then all files under the current mapping are to be handled as CGI scripts.

Inner mappings inherit handlers from the outer mappings, so the presence of cgi:disabled
disables handling of CGI in the given mapping.

Some web servers need additional information about programs to run CGIs. This information is
optionally supplied in the h:handler attribute. Possible values of this attribute consist of several
predefined strings, each denoting CGI handler of a particular type, namely:

• executable - CGI itself is an executable program and is to be executed per se

• perl - CGI is to be executed by Perl interpreter.

• php - CGI is to be executed by PHP CGI interpreter.

• python - CGI is to be executed by Python interpreter.

• ssi - CGI is to be executed by SSI preprocessor.

47
Application Packaging Standard
- Package Format Specification

Web servers which do not need an additional information about CGI handlers should ignore the
h:handler attributes.

Example 31. CGI permission handler

<cgi:permissions writable="true">

<cgi:permissions readable="false">

The situation when a directory and files in the directory to which the given mapping maps should be
writable by running CGI script is specified by using the writable attribute with the "true" value.
The "false" value is default, so no explicit attribute for this is required.

The situation when files in the directory should be protected from reading by running CGI script is
specified by the readable attribute with the "false" value. The "true" value is default, so no explicit
attribute for this is required.

Inner mappings do not inherit permission handlers from the outer mappings.

8.6. Hardware Resources

RELAX NG schema of Hardware Resources aspect:

namespace hw = "http://apstandard.com/ns/1/hardware"

## Requirements
div {

Requirement |= element hw:hardware {

element hw:minimal { CPU?, RAM? }?,
element hw:recommended { CPU?, RAM? }?
}

CPU = element hw:cpu { xsd:nonNegativeInteger }

RAM = element hw:ram { xsd:nonNegativeInteger }
}

This aspect allows declaration of hardware requirements for application services. This aspect uses the
http://apstandard.com/ns/1/hardware XML namespace.

Example 32. Specifying the Minimum and Recommended Hardware

Characteristics
<requirements>
<hw:hardware xmlns:hw="http://apstandard.com/ns/1/hardware">
<hw:minimal>
<hw:cpu>200</hw:cpu>
<hw:ram>50</hw:ram>
</hw:minimal>
<hw:recommended>
<hw:cpu>600</hw:cpu>
<hw:ram>100</hw:ram>
</hw:recommended>
</hw:hardware>
</requirements>

This aspect declares the following requirement types: the minimum and recommended amount of CPU
and RAM resources required for service to work. Requirements of this type are satisfied if Controller
is aware that necessary amount of resources is available. Required CPU resources are specified in
megaherz, RAM resources are specified in megabytes.

8.7. Operating Environment

RELAX NG schema of Operating Environment aspect:

48
Application Packaging Standard
- Package Format Specification

namespace env = "http://apstandard.com/ns/1/environment"

## Requirements
div {
Requirement |= element env:environment {
( element env:x86 { empty } |
element env:x86_64 { empty } )?,

( element env:windows { empty | text } |

element env:linux { empty | text } |
element env:freebsd { empty | text } |
element env:macos { empty | text } )?
}
}

This aspect allows declaring operating environment requirements for platform-dependent applications.
This aspect uses the http://apstandard.com/ns/1/environment XML namespace.

Example 33. Specifying Required OS and Architecture

This aspect declares the following requirement types: operating system, and operating system
architecture. Requirements of this type are satisfied if the appropriate operating system and OS
architecture are used for services instances. Requirements of this type are allowed only within top-
level service.

Controller MAY honor exact operating system name, specified as a content of operating system class
element.

8.8. Mail

RELAX NG schema of Mail aspect:

namespace mail = "http://apstandard.com/ns/1/mail"

Access = element mail:access {

element mail:imap { empty }?,
element mail:imap-ssl { empty }?,
element mail:imap-tls { empty }?,
element mail:pop3 { empty }?,
element mail:pop3-apop { empty }?,
element mail:pop3-tls { empty }?
}

Outgoing = element mail:outgoing {

element mail:smtp { empty }?,
element mail:smtp-ssl { empty }?,
element mail:smtp-tls { empty }?
}
Requirement |= element mail:mailbox {
element mail:id { text },

Access,
Outgoing?
}

Requirement |= Outgoing

This aspect is to be used by applications implementing Mail User Agents, requiring access to results
of mail delivery or sending mail. This aspect uses the http://apstandard.com/ns/1/mail
XML namespace.

49
Application Packaging Standard
- Package Format Specification

Example 34. Requirements for mailbox access

Example 35. Requirement for sending emails

The following elements comprise the 'mailbox' requirement type:

id Identifier of mailbox. This identifier will be used

in environment variables passed to configuration
scripts
access A list of protocols that must be used for accessing
mailbox
imap IMAP version 4 revision 1 protocol as defined by
RFC 3501
imap-ssl IMAP version 4 revision 1 tunneled over SSL
imap-tls IMAP version 4 revision 1 with Transport Layer
Security enabled
pop3 POP3 protocol as defined by RFC 1939
pop3-apop POP3 protocol with APOP extension
pop3-tls POP3 protocol access with TLS enabled
outgoing Requirement for access to outgoing mail server
smtp Requirement for access to outgoing mail server
over SMTP protocol as defined by RFC 5321
smtp-ssl Requirement for access to outgoing mail server
over SMTP with SSL tunnelling
smtp-tls Requirement for access to outgoing mail server
over SMTP protocol with TLS enabled

Requirement of this type is satisfied when the following is true:

New mailbox is created accessible over the specified protocols or existing mailbox is configured to
be accessible over the specified protocols.
User authorized to accessing the mailbox is created or exists already.
If 'outgoing' element is used - the same user is authenticated by outgoing mail server.
Mail delivery for at least one email address is configured to the mailbox.
Outgoing mail server is accessible over the protocols specified within 'outgoing' element.

50
Application Packaging Standard
- Package Format Specification

Controller MAY deallocate mailbox when service is cancelled.

The 'outgoing' requirement type demands access to outgoing mail server over SMTP protocol as
defined by RFC 5321. Requirement of this type is satisfied when:

There is a new or existing user, that is authenticated by outgoing mail server.

Outgoing mail server supports the specified protocol(s)

8.8.1. Environment Variables

When a requirement is satisfied, the following environment variables must be passed to configuration
scripts for 'mailbox' requirement:

• MAIL_<id>_IMAP_HOST - FQDN or IP address of IMAP and IMAP with TLS server

• MAIL_<id>_IMAP_PORT - port number of the IMAP and IMAP with TLS server

• MAIL_<id>_IMAP_PORT_SSL - port number of the IMAP over SSL server

• MAIL_<id>_IMAP_MAILBOX - default mailbox name

• MAIL_<id>_POP3_HOST - FQDN or IP address of POP3, APOP and POP3 with TLS server

• MAIL_<id>_POP3_PORT - port number of POP3, APOP and POP3 with TLS server

• MAIL_<id>_USER - login of user, authorized to access the mailbox and outgoing mail server (if
required)

• MAIL_<id>_PASSWORD - password of the user

• MAIL_<id>_EMAIL - primary email address, delivering into the specified mailbox

• MAIL_<id>_ALIAS_<identifier> - aliases of the email address. 'identifier' must has

different value for different aliases

• MAIL_<id>_SMTP_HOST - FQDN or IP address of SMTP or SMTP with TLS server

• MAIL_<id>_SMTP_PORT - port number of the SMTP and SMTP with TLS server

• MAIL_<id>_SMTP_PORT_SSL - port number of the SMTP over SSL server

When a requirement is satisfied, the following environment variables must be passed to configuration
scripts for 'outgoing' requirement:

• MAIL_SMTP_HOST - FQDN or IP address of SMTP or SMTP with TLS server

• MAIL_SMTP_PORT - port number of the SMTP and SMTP with TLS server

• MAIL_SMTP_PORT_SSL - port number of the SMTP over SSL server

• MAIL_SMTP_USER - login of user to be used to authenticate in SMTP server

• MAIL_SMTP_PASSWORD - password of the user

8.8.2. Upgrade

If both old and new versions of application require mailbox then the mailbox, its content and user
access credentials MUST be preserved. If new version of application requires different set of mailbox
access protocols, then mailbox MUST be accessible over new set of protocols during upgrade.

8.9. Perl Aspect

This aspect is to be used by web applications written in Perl. This aspect uses the http://
apstandard.com/ns/1/perl XML namespace.

51
Application Packaging Standard
- Package Format Specification

RELAX NG schema of Perl aspect

namespace perl="http://apstandard.com/ns/1/perl"

## URL Handlers
div {
UrlHandler |= element perl:handler {
( element perl:disabled { empty }
| element perl:extension { text }* )?
}
}

## Requirements
div {
## Require perl
Requirement |= element perl:version {
## Perl version match XPath expression
attribute match { text }?
}

## Require availability of perl modules in include path

Requirement |= element perl:module {

## perl module name

attribute name { text },

## module version match XPath expression

attribute match { text }?
}

Requirement |= (

## Require mod_perl handler

element perl:mod_perl {
## mod_perl version match XPath express
attribute match { text }?
} |

## Require active_perl handler

element perl:active_perl {
## mod_perl version match XPath express
attribute match { text }?
}

)?
}

8.9.1. Requirement Types

Perl aspect declares the following requirement types: perl version and perl module.

Example 36. Perl Version Requirement

<perl:version match="version >= 5.0"/>

Requirement of this type is satisfied if the version of Perl enabled on a site matches XPath expression
in requirement. It processed against virtual XML document with only node version.

The PERL_VERSION environment variable MUST be passed to the configuration script with the
version of Perl (as a string value) installed on the Web site where the package is to be installed.

Example 37. Perl Modules Requirement

<perl:module name ="CGI"/>
<perl:module name="DBI" match="version > 1.21"/>

Requirement of this type is satisfied if the specified Perl extension is enabled for the web application.

52
Application Packaging Standard
- Package Format Specification

Defined here perl modules should be available with perl 'use' instruction.

If application requires specific method of integration with web server it may specify it with mod_perl
or active_perl tags.

Example 38. Perl specific handler requirement

<perl:mod_perl match="version = 1.30"/>

<perl:active_perl/>

8.9.2. URL Handlers

Example 39. Perl URL Handler

<perl:handler>
<perl:extension>pl</perl:extension>
<perl:extension>perl</perl:extension>
</perl:handler>

<perl:handler><perl:disabled/></perl:handler>

Handlers of this type require that files with the specified extensions (if no extensions are specified, a
single pl extension is assumed) are handled by the perl interpreter.

Inner mappings inherit handlers from the outer mappings, so the presence of perl:disabled
disables Perl in the given mapping.

8.9.3. Configuration Script Language

This aspect defines the perl identifier to be used by configuration scripts. When a configuration
script uses the perl language, it MUST be run by stand-alone perl interpreter. All the requirements
described in the application metadata apply to the interpreter running configuration scripts.

8.10. DNS Zone

RELAX NG schema of DNS aspect

namespace dns = "http://apstandard.com/ns/1/dns"

## Requirements
div {

Requirement |= element dns:record {

element dns:id { text }?,
( NS | MX | CNAME | A | TXT | SRV )
}

NS = element dns:ns { Src, Dst, Subst }

MX = element dns:mx { Src, Priority, Dst, Subst }
CNAME = element dns:cname { Src, Dst, Subst }
A = element dns:a { Src, Ip, Subst }
TXT = element dns:txt { Src, Text, Subst }
SRV = element dns:srv { Service, Protocol, Src, Priority, Weight, Port, Dst, Subst }

Src = element dns:src { ( External | Prefix | Current | Wildcard ) }

Dst = element dns:dst { ( External | Prefix | Current | Wildcard ) }

Subst = element dns:substitute { empty } ?

53
Application Packaging Standard
- Package Format Specification

Int = xsd:nonNegativeInteger

Ip = element dns:ip { attribute value-of-setting { text }?, text }

Text = element dns:text { attribute value-of-setting { text }?, text }
Priority = element dns:priority { attribute value-of-setting { text }?, Int }
Weight = element dns:weight { attribute value-of-setting { text }?, Int }
Port = element dns:port { attribute value-of-setting { text }?, Int }

## http://www.iana.org/assignments/port-numbers
Service = element dns:service { text }
## http://www.iana.org/assignments/service-names
Protocol = element dns:protocol { "tcp" | "udp" | text }

External = element dns:external { attribute value-of-setting { text }?, text }

Prefix = element dns:prefix { attribute value-of-setting { text }?, text }
Current = element dns:current { empty }
Wildcard = element dns:wildcard { empty }
}

This aspect is to be used by services, that need a special DNS zone resource records in order to work.
This aspect uses the http://apstandard.com/ns/1/dns XML namespace.

Example 40. DNS resource record requirements for mail redirects

<requirements>
<dns:record xmlns:dns="http://apstandard.com/ns/1/dns">
<dns:mx>
<dns:src>
<dns:current/>
</dns:src>
<dns:dst>
<dns:external>mailserver.example.com.</dns:external>
</dns:dst>
<dns:priority>10</dns:priority>
</dns:mx>
</dns:record>
<dns:record xmlns:dns="http://apstandard.com/ns/1/dns">
<dns:id>MainMX</dns:id>
<dns:mx>
<dns:src>
<dns:current/>
</dns:src>
<dns:dst>
<dns:external>reserve.example.com.</dns:external>
</dns:dst>
<dns:priority>20</dns:priority>
<dns:substitute/>
</dns:mx>
</dns:record>
</requirements>

This aspect declares resource record requirements type. This requirements demand existence of
specified records in DNS zone of an environment, where service is supposed to run. A Controller
MUST perform appropriate DNS zone configuration. If the demanded resource records cannot be
created - requirement MUST be treated as unsatisfied and service provision SHOULD be aborted.

Requirement MAY be identified with id element.

Requirements of this type MAY be changed during package upgrade. In this case old resource records
MUST be removed and new records created.

Arbitrary DNS resource record contains source and destination elements. Their values may
be specified as:

• Fully qualified domain name, using external element.

• Domain name prefix, using prefix element.

54
Application Packaging Standard
- Package Format Specification

• Current domain name, using current element.

• All domain name prefixes, using wildcard element. This element may appear only in source
part of Resource Record.

external , prefix and several elements specific for MX , A , TXT and SRV records may take
their values from actual service settings, using value-of-setting attribute. If both @value-
of-setting and element's text values are specified - the latter is assumed to be a default value.
If setting value is changed - resource record MUST be reconfigured appropriately. If setting value is
incompatible with resource record type (for example ip element's value is specified as not IP address)
resulting resource record MUST NOT be created.

Records MAY have a substitute keyword in definition. This means that DNS record
should replace existing DNS record with new value. When such requirement is satisfied, the
following environment variable must be passed to configuration scripts for 'dns:record' requirement:
DNS_<id>_SUBSTITUTE. It should contain original value of DNS record been replaced. Keyword
id refer here to requirement identifier.

Example 41. Specifying default value for DNS Resource Record

<requirements>
<dns:record xmlns:dns="http://apstandard.com/ns/1/dns">
<dns:cname>
<dns:source>
<dns:wildcard/>
</dns:source>
<dns:destination>
<dns:external value-of-setting="park_to">parked.example.com.</dns:external>
</dns:destination>
</dns:cname>
</dns:record>
</requirements>

8.11. DLL Content Processing Method

RELAX NG schema of DLL aspect

namespace dll = "http://apstandard.com/ns/1/dll"

## Content delivery method

div {

## Register dinamic load library from APS package

ContentDeliveryMethod |= element dll:register {
attribute path { text }
}+
}

This processing method instructs Controller to install specified DLL into available environment,
following the usual dynamic library registration procedure. Many applications distributed in form of
compiled dynamic libraries (*.dll, *.so). Upon provision such libraries must be registered in the system
library cache.

Targeted environment MUST be compatible with provided library. Since above libraries shared
between application instances Controller MUST handle upgrade of instances in such way to do not
brake them.

Example 42. Install additional DLL example

55
Application Packaging Standard
- Package Format Specification

8.12. IIS Aspect

This aspect is to be used by web applications which use IIS-specific features. This aspect uses the
http://apstandard.com/ns/1/iis XML namespace.

RELAX NG schema of IIS aspect:

namespace iis = "http://apstandard.com/ns/1/iis"

## Requirements
div {
Requirement |= element iis:version {
attribute match { text }?
}

Requirement |= element iis:pool {

attribute mode { "classic" | "integrated" }
}
}

This aspect declares two requirement types: IIS version requirement type and IIS pool requirement
type. Those requirements should be used only if a web application works exclusively with IIS.

Example 43. IIS Version Requirement

Requirement of this type is satisfied when the IIS version above 7 and pool mode on hosting set to
integrated.

Pool mode may be classic or integrated.

References
Satellite Specifications
[APS Categories] APS Application Categories [http://apsstandard.com/r/doc/aps--application-categories.pdf].
List of predefined APS categories.

XML Technologies
[XMLNS] Namespaces in XML (Second Edition) [http://www.w3.org/TR/REC-xml-names/]. W3C
Recommendation 16 Aug 2006.

[XMLLANG] Extensible Markup Language (XML) 1.0 (Fourth Edition). 2.12 Language Identification [http://
www.w3.org/TR/REC-xml/#sec-lang-tag]. W3C Recommendation 16 August 2006.

[XMLDSIG] XML Signature Syntax and Processing (Second Edition) [http://www.w3.org/TR/xmldsig-core/].

W3C Recommendation 10 June 2008

[RNG] RELAX NG specification [http://www.oasis-open.org/committees/relax-ng/spec.html]. OASIS Committee

Specification 3 December 2001

[RNC] RELAX NG compact syntax specification [http://relaxng.org/compact.html]. OASIS Committee

Specification 21 November 2002

56
Application Packaging Standard
- Package Format Specification

Other
[HCARD] hCard specification [http://microformats.org/wiki/hcard]

[HCARD-PROFILE] hCard Profile [http://www.w3.org/2006/03/hcard] W3C experimental XMDP profile for

the hCard specification.

[JDBCDRIVERS] JDBC drivers registry [http://developers.sun.com/product/jdbc/drivers]

[ZIP] ZIP specification [http://www.info-zip.org/pub/infozip/doc/zip]

[Langs] Wikipedia list of programming languages [http://en.wikipedia.org/wiki/

Alphabetical_list_of_programming_languages]

[RFC 2119] RFC 2119, BCP 14: Key words for use in RFCs to Indicate Requirement Levels [http://www.ietf.org/
rfc/rfc2119.txt]

[RFC 3920] Extensible Messaging and Presence Protocol (XMPP): Core [http://www.ietf.org/rfc/rfc3920.txt]

[RFC 2872] Application and Sub Application Identity Policy Element for Use with RSVP [http://www.ietf.org/
rfc/rfc2872.txt]

[RFC 2822] RFC 2822: Internet Message Format [http://www.ietf.org/rfc/rfc2822.txt]

[RFC 1035] RFC 1035: DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION [http://www.ietf.org/
rfc/rfc1035.txt]

[RFC 3066] RFC 3066: Tags for the Identification of Languages [http://www.ietf.org/rfc/rfc3066.txt]

[RFC 1738] RFC 1738: Uniform Resource Locators (URL) [http://www.ietf.org/rfc/rfc1738.txt]

[ISO 639] ISO 639: Codes for the Representation of Names of Languages [http://www.loc.gov/standards/iso639-2/
]

[ISO 3166] ISO 3166 Code Lists [http://www.iso.org/iso/country_codes.htm]

[URI Templates] URI Templates [http://bitworking.org/projects/URI-Templates/]

3D XML User Guide 4.3
No ratings yet
3D XML User Guide 4.3
88 pages
XML - Prelim To FInal Exam
No ratings yet
XML - Prelim To FInal Exam
130 pages
Shipping Policies: Sherry - Lehmann S
No ratings yet
Shipping Policies: Sherry - Lehmann S
7 pages
Sample Business Plan Outline (Start-Up) : Resources: Trade Associations, FCPL BRC, Internet
100% (1)
Sample Business Plan Outline (Start-Up) : Resources: Trade Associations, FCPL BRC, Internet
4 pages
cdf3 Faq
No ratings yet
cdf3 Faq
7 pages
Bank Format-1-1
No ratings yet
Bank Format-1-1
1 page
New FB Sites
No ratings yet
New FB Sites
2 pages
Walcott Format
100% (1)
Walcott Format
3 pages
Contract FMT
No ratings yet
Contract FMT
1 page
Agent Delivery
No ratings yet
Agent Delivery
6 pages
FML MLT FMT (1) - 100136
No ratings yet
FML MLT FMT (1) - 100136
6 pages
222222
No ratings yet
222222
2 pages
Embassy FMT
No ratings yet
Embassy FMT
3 pages
Chat Message
No ratings yet
Chat Message
5 pages
New Gold Format
No ratings yet
New Gold Format
3 pages
Trust Rent
No ratings yet
Trust Rent
6 pages
Package Delivery FMT
100% (1)
Package Delivery FMT
3 pages
Arrived From Meeting
No ratings yet
Arrived From Meeting
2 pages
Hello, Thank yo-WPS Office
No ratings yet
Hello, Thank yo-WPS Office
5 pages
All Billing Format PDF Laughter PDF Scribd Digital Technology
0% (1)
All Billing Format PDF Laughter PDF Scribd Digital Technology
13 pages
Delivery ? ?
No ratings yet
Delivery ? ?
1 page
Delivery Format PDF Finance & Money Management
No ratings yet
Delivery Format PDF Finance & Money Management
1 page
Arived From Meeting
No ratings yet
Arived From Meeting
2 pages
@badboy Jago
No ratings yet
@badboy Jago
1 page
Billing For Sailors
No ratings yet
Billing For Sailors
2 pages
Dating FMT
No ratings yet
Dating FMT
16 pages
Celeb 2
No ratings yet
Celeb 2
5 pages
Custom Billing
No ratings yet
Custom Billing
1 page
Follow Up Format
No ratings yet
Follow Up Format
1 page
Consignment Stock Processing
100% (1)
Consignment Stock Processing
8 pages
Doctor Format
No ratings yet
Doctor Format
1 page
Box 44
100% (2)
Box 44
45 pages
Woman To Man
No ratings yet
Woman To Man
8 pages
Text
No ratings yet
Text
9 pages
Billing
No ratings yet
Billing
58 pages
Cancer Format
No ratings yet
Cancer Format
2 pages
Key World-1
100% (1)
Key World-1
8 pages
How To Create A Meet and Greet Webs
No ratings yet
How To Create A Meet and Greet Webs
2 pages
Main Work-1-1
100% (1)
Main Work-1-1
93 pages
Registration Format
No ratings yet
Registration Format
3 pages
Random Billing
No ratings yet
Random Billing
3 pages
Delivery
No ratings yet
Delivery
2 pages
Format For Ay
No ratings yet
Format For Ay
2 pages
Format 2
No ratings yet
Format 2
15 pages
Billing Formatt
No ratings yet
Billing Formatt
2 pages
Emergency Leave Format
100% (1)
Emergency Leave Format
1 page
Celeb FMT
No ratings yet
Celeb FMT
5 pages
Trust FMT
No ratings yet
Trust FMT
9 pages
Celebrity FMT 3
No ratings yet
Celebrity FMT 3
3 pages
Fedex Terms
No ratings yet
Fedex Terms
13 pages
1st Consigmnet
No ratings yet
1st Consigmnet
3 pages
FedEx Shipment 774163563706 Your Package Is Now Out For Delivery Today
No ratings yet
FedEx Shipment 774163563706 Your Package Is Now Out For Delivery Today
4 pages
Celebrate 2
No ratings yet
Celebrate 2
5 pages
FMT Courier Company Service-1 PDF Courier D
No ratings yet
FMT Courier Company Service-1 PDF Courier D
1 page
Philippines - Visa Application
No ratings yet
Philippines - Visa Application
1 page
Trust, Oat, Confession, Love Messages
No ratings yet
Trust, Oat, Confession, Love Messages
6 pages
Immigration Bill ?
100% (1)
Immigration Bill ?
1 page
Text
No ratings yet
Text
2 pages
Universal Parcel Tracking - Global Package Tracking
No ratings yet
Universal Parcel Tracking - Global Package Tracking
1 page
A.s.dreyer@starmail - Co.za: Email
No ratings yet
A.s.dreyer@starmail - Co.za: Email
1 page
Doctor Jay
100% (1)
Doctor Jay
6 pages
My Online Dating Experience: I Believe in My Success and Yours Too
From Everand
My Online Dating Experience: I Believe in My Success and Yours Too
George D. Liu
No ratings yet
State of Love & Trust
From Everand
State of Love & Trust
Grace Ombry
5/5 (1)
Web Services in ASP
No ratings yet
Web Services in ASP
29 pages
Troubleshooting Guide
100% (3)
Troubleshooting Guide
318 pages
CRS XML Schema 2.0
No ratings yet
CRS XML Schema 2.0
66 pages
GSDML GettingStarted en PDF
No ratings yet
GSDML GettingStarted en PDF
49 pages
2022 04 01 - State Transition Validation Rules - v2.6 Final
No ratings yet
2022 04 01 - State Transition Validation Rules - v2.6 Final
162 pages
Post User
No ratings yet
Post User
21 pages
Oracle FLEXCUBE Direct Banking Parameter Sheet
No ratings yet
Oracle FLEXCUBE Direct Banking Parameter Sheet
200 pages
Bods 4.2
No ratings yet
Bods 4.2
136 pages
3GPP TS 28.623: Technical Specification
No ratings yet
3GPP TS 28.623: Technical Specification
115 pages
Microsoft Enterprise Library 5.0 Migration Guide
No ratings yet
Microsoft Enterprise Library 5.0 Migration Guide
11 pages
Web Services: XML Documents Contain The Information Being Exchanged Between Two Parties. It Is
No ratings yet
Web Services: XML Documents Contain The Information Being Exchanged Between Two Parties. It Is
65 pages
An ISA95 Overview: Workflow and System Modeling For 21st Century Manufacturing Flexibility
No ratings yet
An ISA95 Overview: Workflow and System Modeling For 21st Century Manufacturing Flexibility
51 pages
TP N°1 - XML-2024
No ratings yet
TP N°1 - XML-2024
4 pages
Fiscalization Service - Technical PDF
No ratings yet
Fiscalization Service - Technical PDF
107 pages
Air SDK 33.0.1.228 - Readme File PDF
No ratings yet
Air SDK 33.0.1.228 - Readme File PDF
13 pages
Jenkins Logs
No ratings yet
Jenkins Logs
13 pages
XML Schema
No ratings yet
XML Schema
29 pages
Schema WSDL
No ratings yet
Schema WSDL
45 pages
Systems Engineering Management Plan
No ratings yet
Systems Engineering Management Plan
27 pages
VSDK Prog Guide
No ratings yet
VSDK Prog Guide
246 pages
Activiti 5.9 User Guide
No ratings yet
Activiti 5.9 User Guide
211 pages
Jade Web Services Integration Gateway (WSIG) Guide: Usage Restricted According TO License Agreement
No ratings yet
Jade Web Services Integration Gateway (WSIG) Guide: Usage Restricted According TO License Agreement
19 pages
ACS 5.3 Software Developer's Guide
No ratings yet
ACS 5.3 Software Developer's Guide
108 pages
DocData Integration Manual Order API 1.3 - v1.0 - EN
No ratings yet
DocData Integration Manual Order API 1.3 - v1.0 - EN
36 pages
Chapter 11: XML: Data Integration
No ratings yet
Chapter 11: XML: Data Integration
73 pages
Lab Report
No ratings yet
Lab Report
57 pages
Spring Web Service, Spring JMS, Eclipse & Maven Tutorials
No ratings yet
Spring Web Service, Spring JMS, Eclipse & Maven Tutorials
42 pages

Package Format Specification

Uploaded by

Package Format Specification

Uploaded by

Application Packaging Standard

- Package Format Specification

All rights reserved.

7.1. Requirement Types ........................................................................................ 39

Package is a ZIP file that contains the following:

main package metadata file APP-META.xml

Here is a structure of a typical package.

APP-META.xml # Metadata container. XML file.

... # instance is managed

basic package format

4. Basic Package Format

Package is a ZIP file [ZIP] with the .app.zip extension.

Package MUST contain only regular files and directories.

4.3. Metadata File

4.4. Package contents listing

default namespace sa = "http://apstandard.com/ns/1"

Application = element application {

## Unique application identifier

element name { text },

## Reference on master package for add-on package

element screenshot { attribute path { text },

element categories { element category { text }+ }?,

element languages { element language {

element extension { AnyElement* }?

element global-settings { ( Setting | SettingGroup )* }?,

element patch { attribute match { text },

element upgrade { attribute match { text },

element content { ContentDeliveryMethod }?,

element provision { element verify-script { VerifyScript }? }?,

AnyElement = element * { attribute * { text }*,

element license { EULA }?,

element presentation { Presentation }?,

element resources { Resource * }?,

## Requirements specification [5.4.4]

## End-user license agreement

element text { attribute xml:lang { text }?,

## Informational link specification [5.2.2]

element label { attribute xml:lang { text }?,

## Optional parameters for using entry point

element extension { AnyElement* }?

element extension { AnyElement* }?

## groups with name of @class "type" are used to

## Nested anonymous groups are allowed for the sake of

Setting = element setting { attribute id { text },

element name { attribute xml:lang { text }?, text }*,

| ( attribute type { "string" | "password" },

| ( attribute type { "integer" },

| ( attribute type { "float" },

| ( attribute type { "date" },

| ( attribute type { "time" },

| ( attribute type { "email" },

attribute default-value { text }? )

| ( attribute type { "domain-name" },

| ( attribute type { "host-name" },

| ( attribute type { "enum" },

| ( attribute element-type { "integer" },

| ( attribute element-type { "float" },

| ( attribute element-type { "email" },

| ( attribute element-type { "domain-name" },

| ( attribute element-type { "host-name" },

| ( attribute element-type { "enum" },

SettingTypeString = attribute min-length { xsd:nonNegativeInteger }?,

SettingTypeInteger = attribute min { xsd:integer }?,

SettingTypeFloat = attribute min { xsd:float }?,

SettingTypeTime = attribute min { xsd:time }?,

SettingTypeDate = attribute min { xsd:date }?,

## Placeholder for aspect-specific URL handlers

## Aspect must use own namespace

Mapping = RegularMapping | VirtualMapping

## Generic script Script