Spotter-VM/doc/toolchain/lxc-pack.md

4.4 KiB

Packaging LXC containers

Overview

The lxc-pack utility creates a .tar.xz archives based on package metadata and manages the packages.json repository metadata file. If a filename is passed as command line parameter to lxc-pack, the metadata are loaded from the file. In case a directory path is given, the metadata are loaded from a file called pkg from the directory. All metadata files are in JSON format.

The product of lxcbuild command described in LXC building documentation can be used in its entirety, ie. both filesystem layer and configuration, or only as dependency, in which case the container configuration is omitted and only the filesystem layer is used. Apart from that, the package can contain installation, upgrade and uninstallation script and data, all of which are optional. Accepted names are

  • install.sh file and install directory for post-install scripts.
  • upgrade.sh file and upgrade directory for post-upgrade scripts.
  • uninstall.sh file and uninstall directory for post-uninstall scripts.

lxc-pack reads the metadata file, creates a tarball with the contents of a given directory under /var/lib/lxc, adds the install/upgrade/uninstall scripts and compresses the tarball into .tar.xz archive. Then it calculated size of the package and SHA512 hash and adds this information to the rest of the metadata, which are then stored as JSON dictionary in the repository-wide metadata file packages. Finally, it creates another SHA512 hash of the packages file and signs it using ECDSA key to ensure the integrity and tamperproofness of the repository data. The signature is stored in packages.sig file. Public key for the signature verification is already pre-imported on the LXC hosts as part of the basic VM installation. For more details on package manager, see the Package Manager documentation.

Usage

lxc-pack <buildpath>
  where the buildpath can be either specific meta file or a directory containing one

Keys used in meta file

The meta file is in JSON format. All values are strings except for depends which is an array of strings and size which is an integer.

title

  • Usage: "title": "<title>"
  • Description: Sets human readable package name. Also helps to distinguish if the package is user-installable or if it is a dependency / component to another application. All packages which have title set, will show up in a list of user-installable packages in VMMgr web GUI.
  • Mandatory: Only for full user-installable container packages.

desc-xx

  • Usage: "desc-<lang>": "<description>"
  • Description: Sets human readable long description of the package. Language code lang is ISO 639-1 two-letter code.
  • Mandatory: Only for full user-installable container packages.

lxcpath

  • Usage: "lxcpath": "<directory>[/subdirectory]"
  • Description: Sets the source path for lxc-pack and subsequently also for VMMgr. The directory is a relative path under /var/lib/lxc. In case only the directory is given, lxc-pack takes all subdirectories and files in the directory, usually resulting in a full container package (both filesystem layer and configuration). If a /subdirectory is given, then only the subdirectory is packaged, resulting in filesystem layer-only package, usually used as a shared dependency for other containers.
  • Mandatory: Yes.

version

  • Usage: "version": "<version>"
  • Description: Sets the package version. This should correspond to the actual version of the packaged product.
  • Mandatory: Yes.

release

  • Usage: "release": "<release>"
  • Description: Sets the package release version. Used when the same basic version of the packaged product needs to be repacked with updated base layers or install/upgrade/uninstall scripts.
  • Mandatory: Yes.

license

  • Usage: "license": "<license>"
  • Description: Sets the license of the packaged product.
  • Mandatory: Yes.

depends

  • Usage: "depends: ["<dependency1>", "<dependency2>", ...]
  • Description: Sets the package dependencies which needs to be installed before this package.
  • Mandatory: Yes (can be empty for the basic OS filesystem layer).

size

  • Usage: "size": "<bytes>"
  • Description: Sets the package archive size.
  • Mandatory: Populated automatically by lxc-pack.

sha512

  • Usage: "sha512": "<hash>"
  • Description: Sets the package archive SHA512 hash.
  • Mandatory: Populated automatically by lxc-pack.