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

79 lines
4.5 KiB
Markdown

# 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 *lxc-build* 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
```bash
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`.