IOx application package

Anatomy of an application package

An IOx application package shall consist of :

  • ONE package descriptor file named as "package.yaml" and should be present in the root of the package

  • zero or one application configuration file named as "package_config.ini". If present, should be in the root of the package.

  • zero or one application manifest named as "package.mf". If present, should be in the root of the package.

  • zero or one certificate containing signing information named as "package.cert". If present, should be in the root of the package.

  • ONE tar.gz envelope containing application or service artifacts with the name "artifacts.tar.gz". These artifacts may be binaries, application code, application libraries, virtual disks, rootfs etc., More details about this in the below sections.

Package format

An IOx application package should be packaged in any ONE of the following file formats: "tar" or "tar.gz"

Package descriptor file

The contents of this file captures application/service metadata, requirements etc., in a YAML format. It should be named as package.yaml. The specifications of this file is covered in a separate document.

Package configuration file

In order to bootstrap applications or services present in the package, IOx framework supports externalizing this content into a separate .ini file and provides mechanisms to edit and update the contents of this file during the provisioning of the application.This file contains sections with key, value pairs adhering to ini file format. The name of the file if present should be package_config.ini. The administration tools will provide mechanisms to modify this file with right values during installation process so that the application can be bootstrapped with the right values.

Application artifacts

All app artifacts will be maintained in its own tarball. This will offer a cleaner separation of application artifacts. This inner envelope will always be a tar.gz and shall be named as artifacts.tar.gz. This will typically be generated by tooling (ioxclient, SDK etc.,).

Here is a comparison of an application developer's view of his workspace vs the final IOx package created.

  • Application workspace
|-- main.py
|-- myresources
|   |-- 1
|   |   |-- 1.txt
|   |   `-- 2
|   |       |-- 2.txt
|   |       `-- 3
|   `-- 2sym -> 1/2/2.txt
|-- package_config.ini
|-- package.yaml
|-- requirements.txt
  • Generate a package
ioxclient package .

This will result in an IOx application package (package.tar.gz)

  • Note how the package.yaml and package_config.ini are moved into the outer envelope. The rest of the application artifacts are in artifacts.tar.gz
$ tar tzvf package.tar.gz
-rw-rw-r-- 1000/1000    187852 2015-08-18 16:11 artifacts.tar.gz
-rw------- 1000/1000       193 2015-08-18 16:11 package.mf
-rwxrwxrwx 1000/1000         0 2015-08-18 16:11 package.yaml
-rw-rw-r-- 1000/1000        27 2015-08-18 16:11 package_config.ini
  • The app artifacts are under artifacts.tar.gz
$ tar tzvf artifacts.tar.gz
-rw-rw-r-- 1000/1000         0 2015-08-18 16:11 main.py
-rwxrwxrwx 1000/1000        19 2015-08-18 16:11 myresources/1/1.txt
-rw-rw-r-- 1000/1000        50 2015-08-18 16:11 myresources/1/2/2.txt
lrwxrwxrwx 1000/1000         0 2015-08-18 16:11 myresources/2sym -> 1/2/2.txt
-rw-rw-r-- 1000/1000        19 2015-08-18 16:11 requirements.txt

Package Certificate

In case of signed application package, IOx application will have a file named package.cert. This file contains signature of the package.mf file and also includes the public key. Public key is used to establish the trust-chain on the device. The package.cert format is the same as specified in the OVA/OVF specification. Here is the sample format of package.cert file contents.

SHA1(package.mf)= <signature of the hash of package.mf>
-----BEGIN CERTIFICATE-----
<developer certificate in PEM format>
-----END CERTIFICATE-----

Package Manifest

IOx application package may have a manifest file containing the SHA1 or SHA256 digests of individual files in the package. The manifest file should be named as package.mf. If the manifest file is present, a consumer of this package (CAF, Fog Director etc.,) should verify the digests in the manifest file in the package by computing the actual SHA1 or SHA256 digests and comparing them with the digests listed in the manifest file.

The syntax definition of this file in ABNF format is as below:

manifest_file = *( file_digest )
file_digest = algorithm "(" file_name ")" "=" sp digest nl
algorithm = "SHA1" | "SHA256"
digest = *( hex-digit )
hex-digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "a" | "b" | "c" | "d" | "e" | "f"
sp = %x20
nl = %x0A

Note that the format of the manifest file is roughly based on OVF specifications Version 2.1.0. This file will typically be generated by the SDK tools provided to the application developer.