Debian Template

The Debian template provides the following options, which are quite different from the options offered by the download template:

The Debian template–specific options can be passed to lxc-create after a -- like this:

 lxc-create --name=NAME [-lxc-create-options] -- [-template-options]

Usage: /usr/share/lxc/templates/lxc-debian -h|--help -p|--path=<path> [-c|--clean] [-a|--arch=<arch>] [-r|--release=<release>]
                                        [--mirror=<mirror>] [--security-mirror=<security mirror>]
                                        [--package=<package_name1,package_name2,...>]

Options :

 -h, --help             print this help text
 -p, --path=PATH        directory where config and rootfs of this VM will be kept
 -a, --arch=ARCH        The container architecture. Can be one of: i686, x86_64,
                        amd64, armhf, armel, powerpc. Defaults to host arch.
 -r, --release=RELEASE  Debian release. Can be one of: wheezy, jessie, stretch, sid.
                        Defaults to current stable.
 --mirror=MIRROR        Debian mirror to use during installation. Overrides the MIRROR
                        environment variable (see below).
 --security-mirror=SECURITY_MIRROR
                        Debian mirror to use for security updates. Overrides the
                        SECURITY_MIRROR environment variable (see below).
 --packages=PACKAGE_NAME1,PACKAGE_NAME2,...
                        List of additional packages to install. Comma separated, without space.
 -c, --clean            only clean up the cache and terminate
 --enable-non-free      include also Debian's contrib and non-free repositories.

Environment variables:                                                                                                                                                                               

 MIRROR                 The Debian package mirror to use. See also the --mirror switch above.
                        Defaults to 'http://httpredir.debian.org/debian'
 SECURITY_MIRROR        The Debian package security mirror to use. See also the --security-mirror switch above.
                        Defaults to 'http://security.debian.org/'

The following is an example usage of the Debian template to create a Stretch-based container:

$ sudo lxc-create -t debian -n stretch-test -- --release stretch --packages=wget,iputils-ping --mirror=http://deb.debian.org/debian/ --security-mirror=http://deb.debian.org/debian-security/
debootstrap is /usr/sbin/debootstrap
Checking cache download in /var/cache/lxc/debian/rootfs-stretch-amd64 ...
gpg: keybox '/var/cache/lxc/debian/archive-key.gpg' created
gpg: directory '/home/stylesen/.gnupg' created
gpg: new configuration file '/home/stylesen/.gnupg/dirmngr.conf' created
gpg: new configuration file '/home/stylesen/.gnupg/gpg.conf' created
gpg: /home/stylesen/.gnupg/trustdb.gpg: trustdb created
gpg: key 7638D0442B90D010: public key "Debian Archive Automatic Signing Key (8/jessie) <[email protected]>" imported
gpg: Total number processed: 1
gpg:            imported: 1
gpg: no ultimately trusted keys found
Downloading debian minimal ...
I: Retrieving InRelease
----------OUTPUT TRUNCATED----------
I: Base system installed successfully.
Download complete.
Copying rootfs to /var/lib/lxc/stretch-test/rootfs...Generating locales (this might take a while)...
 en_IN.en_IN...character map file `en_IN' not found: No such file or directory
done
Generation complete.                                                                                                                                                                               
update-rc.d: error: cannot find a LSB script for checkroot.sh
update-rc.d: error: cannot find a LSB script for umountfs
update-rc.d: error: cannot find a LSB script for hwclockfirst.sh
Creating SSH2 RSA key; this may take some time ...
----------OUTPUT TRUNCATED----------
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of start.

Current default time zone: 'Etc/UTC'
Local time is now:      Wed May 24 15:13:39 UTC 2017.
Universal Time is now:  Wed May 24 15:13:39 UTC 2017.

Root password is 'root', please change !
Installing packages: wget iputils-ping
Hit:1 http://deb.debian.org/debian stretch InRelease
----------OUTPUT TRUNCATED----------
Processing triggers for libc-bin (2.24-10) ...
W: --force-yes is deprecated, use one of the options starting with --allow instead.
$

Let’s examine the steps involved in creating the preceding Debian container:

1. The Debian template uses debootstrap to create a minimal Debian system with the provided parameters such as release, mirror, and security_mirror. This minimal Debian system is bootstrapped in the folder /var/cache/lxc/debian/, if the requested rootfs is not already available there. The rootfs created in /var/cache/lxc/debian/ is copied to /var/lib/lxc/{container-name}, where container-name is the name of the container passed via the -n option.

2. After copying the rootfs, the Debian template script sets up the basic configuration for the newly created container.

The following are some options that are unique to the Debian templates:

• The option --packages accepts a comma-separated list of packages that should be installed to the newly created container. Once the minimal Debian system rootfs is copied to the container location, the download template script installs the list of packages supplied to the --packages option into the newly created container using apt. This happens before starting the container, as part of container creation itself. It comes in handy when we want to get a container set up with all tools and software packages installed before booting into the container.

• The --mirror and --security-mirror options accept Debian mirror URLs that will be used for downloading any packages needed, whether for the bootstrap or in the list of extra packages requested. Some users may have a local Debian mirror from which they can install the packages instead of wasting Internet bandwidth; otherwise, a user can point to a mirror close to the user’s geographical location to expedite the download.

Fedora Template

The Fedora template provides the following options to create a Fedora-based container:

Host CPE ID from /etc/os-release:
usage:
        /usr/share/lxc/templates/lxc-fedora -n|--name=<container_name>
        [-p|--path=<path>] [-c|--clean] [-R|--release=<Fedora_release>]
        [--fqdn=<network name of container>] [-a|--arch=<arch of the container>]
        [--mask-tmp]
        [-h|--help]
Mandatory args:
 -n,--name      container name, used to as an identifier for that container
Optional args:                                                                                                                                                                               
 -p,--path      path to where the container will be created,
                defaults to /var/lib/lxc.
 --rootfs       path for actual rootfs.
 -c,--clean     clean the cache
 -R,--release   Fedora release for the new container.
                Defaults to host's release if the host is Fedora.
    --fqdn      fully qualified domain name (FQDN) for DNS and system naming
 -a,--arch      Define what arch the container will be [i686,x86_64]
 --mask-tmp     Prevent systemd from over-mounting /tmp with tmpfs.
 -h,--help      print this help

The following is an example of using the Fedora template to create a container based on Fedora release 25:

$ sudo lxc-create -t fedora -n fedora-test -- --release 25
Host CPE ID from /etc/os-release:
Checking cache download in /var/cache/lxc/fedora/x86_64/25/rootfs ...
Downloading fedora minimal ...
Fetching release rpm name from http://mirror.rise.ph/fedora/linux/releases/25/Everything/x86_64/os//Packages/f...
 % Total   % Received % Xferd  Average Speed   Time   Time    Time  Current
                               Dload   Upload  Total  Spent   Left  Speed
----------OUTPUT TRUNCATED----------
Bootstrap Environment testing...

Fedora Installation Bootstrap Build...

Downloading stage 0 LiveOS squashfs file system from archives.fedoraproject.org...
Have a beer or a cup of coffee.  This will take a bit (∼300MB).
----------OUTPUT TRUNCATED----------
Complete!
Fixing up rpm databases
Download complete.
Copy /var/cache/lxc/fedora/x86_64/25/rootfs to /var/lib/lxc/fedora-test/rootfs ...
Copying rootfs to /var/lib/lxc/fedora-test/rootfs ...
Storing root password in '/var/lib/lxc/fedora-test/tmp_root_pass'
Expiring password for user root.
passwd: Success
installing fedora-release package
Redirecting to '/usr/bin/dnf -y install fedora-release' (see 'man yum2dnf')

Failed to set locale, defaulting to C
Fedora 25 - x86_64                              4.7 MB/s |  50 MB      00:10                                                                                                                                                      
Fedora 25 - x86_64 - Updates                    2.0 MB/s |  23 MB      00:11    
Last metadata expiration check: 0:00:11 ago on Thu May 25 22:59:00 2017.
Package fedora-release-25-2.noarch is already installed, skipping.
Dependencies resolved.
Nothing to do.
Complete!

Container rootfs and config have been created.
Edit the config file to check/enable networking setup.

You have successfully built a Fedora container and cache. This cache may
be used to create future containers of various revisions. The directory
/var/cache/lxc/fedora/x86_64/bootstrap contains a bootstrap
which may no longer needed and can be removed.

A LiveOS directory exists at /var/cache/lxc/fedora/x86_64/LiveOS.
This is only used in the creation of the bootstrap run-time-environment
and may be removed.

The temporary root password is stored in:

        '/var/lib/lxc/fedora-test/tmp_root_pass'

The root password is set up as expired and will require it to be changed
at first login, which you should do as soon as possible. If you lose the
root password or wish to change it without starting the container, you
can change it from the host by running the following command (which will
also reset the expired flag):

        chroot /var/lib/lxc/fedora-test/rootfs passwd

$                                                                                                                                                                              

The following steps are involved in creating the preceding Fedora container:

1. The Fedora template downloads a minimal Fedora system with the provided parameters such as release. This minimal Fedora system is created in the folder /var/cache/lxc/fedora/, if the requested rootfs is not already there.

2. Inside this minimal Fedora system, the required Fedora mirrors are set up and the basic software packages are installed using yum package manager.

3. The rootfs created in /var/cache/lxc/fedora/ is copied to /var/lib/lxc/{container-name}, where container-name is the name of the container passed via the -n option.

4. After copying the rootfs, the Fedora template script sets up the basic configuration for the newly created container. The template also generates a root password and copies it to a specific location within the container directory.

$ /usr/share/lxc/templates/lxc-{name} --help

Unified Image

The unified image format is a single tarball that is self-contained with all the files required to support an LXD image. This is the format used for officially supplied LXD images in the past (now the official images are split images, as explained in the following section). The tarball may be either compressed or uncompressed. The SHA256 checksum of the image tarball is used as the image identifier.

The contents of the unified image tarball are as follows:

• rootfs/

• metadata.yaml

• templates/ (optional)

A typical metadata.yaml file looks something like this:

architecture: "x86_64"
creation_date: 1495726848
properties:
        architecture: "x86_64"
        description: "Ubuntu 16.04 LTS server (20170525)"
        os: "ubuntu"
        release: "xenial"
templates:
        /etc/hostname:
        when:
        - create
        - copy
        template: hostname.tpl
        /var/lib/cloud/seed/nocloud-net/meta-data:
        when:
        - create
        - copy
        template: cloud-init-meta.tpl
        /var/lib/cloud/seed/nocloud-net/network-config:
        when:
        - create
        - copy
        template: cloud-init-network.tpl
        /var/lib/cloud/seed/nocloud-net/user-data:
        when:
        - create
        - copy
        template: cloud-init-user.tpl
        properties:
        default: |                                                                                                              
                #cloud-config
                {}
        /var/lib/cloud/seed/nocloud-net/vendor-data:
        when:
        - create
        - copy
        template: cloud-init-vendor.tpl
        properties:
        default: |
                #cloud-config
                {}
        /etc/init/console.override:
        when:
        - create
        template: upstart-override.tpl
        /etc/init/tty1.override:
        when:
        - create
        template: upstart-override.tpl
        /etc/init/tty2.override:
        when:
        - create
        template: upstart-override.tpl
        /etc/init/tty3.override:
        when:
        - create
        template: upstart-override.tpl
        /etc/init/tty4.override:
        when:
        - create
        template: upstart-override.tpl

This metadata.yaml files has two mandatory fields, architecture and creation_date. The architecture field specifies the architecture to which the image applies, and the creation_date field specifies the date of creation of the image in UNIX time_t format. The other extra properties available in the metadata file are there for the convenience of the user; they give a detailed description of the image. These extra properties are used by commands such as lxc image list and to perform a key/value search for a particular image. These extra properties can be edited by the users with the help of the lxc image edit command, though the architecture and creation_date fields are immutable.

Templates

LXD templates use the pongo2 templating engine for the template syntax. The template provides a way to generate or regenerate some files during the lifecycle of a container. In custom images, there can also be custom templates added to change or dynamically configure certain files within the container. The templates found in the metadata.yaml file previously discussed can take one of the following values for the when key:

• create: Run at the time a new container is created from the image

• copy: Run when a container is created from an existing one

• start: Run every time the container is started

The following context is available during the template execution:

• trigger: Name of the event that triggered the template

• path: Path of the file being templated

• container: Key/value map of container properties (name, architecture, privileged, and ephemeral)

• config: Key/value map of the container’s configuration

• devices: Key/value map of the devices assigned to this container

• properties: Key/value map of the template properties specified in metadata. yaml

Split Image

The split image format has two distinct tarballs, one for the rootfs and the other for metadata. The metadata file contains the following:

• expiry

• create-message

• templates (optional)

• config-user

• config

• excludes-user

The rootfs tarball simply contains the container root filesystem at its root. A listing of the untarred rootfs.tar file will have the following folders:

$ ls
bin   dev  home  lib64  opt   root  sbin  sys  usr
boot  etc  lib   mnt    proc  run   srv   tmp  var
$

These two tarballs may be either compressed or uncompressed, and each tarball may choose its own compression algorithm—it is not mandatory to use the same compression algorithm for both the tarballs. This is the current format in which the LXD project officially generates its images at the time of this writing. The image identifier is the SHA256 checksum of the concatenation of the metadata and the rootfs tarball (in that order). For example, to calculate the image identifier, we can use the following command on the metadata and rootfs tarballs:

$ cat meta.tar.xz rootfs.tar.xz | sha256sum
119fd125d0c4f67525096aa5d34759cf15971fd667915dd84ad509b3d18c1848  -
$

Many operating system distributions provide a rootfs tarball, which can be directly used as the rootfs tarball without any modification. This is the major advantage of the split-image format over the older single-image format.

Copying Images

LXD provides a way to copy an image from a remote image server to the local image store without creating or launching a container immediately. The copied image can be used later to create a container—this is useful when you want to cache certain images when you have an Internet connection and later use these cached images to create containers when disconnected from the Internet.

$ sudo lxc image copy images:debian/jessie local:
Image copied successfully!               
$
$ sudo lxc image list
+-------+-------------+------+-------------+------+--------+---------------+
|ALIAS| FINGERPRINT |PUBLIC| DESCRIPTION   | ARCH | SIZE   | UPLOAD DATE   |
+-------+-------------+------+-------------+------+--------+---------------+
|     | 489c3fa793c4| no   |Debian jessie   |x86_64| 94.17MB| May 26, 2017  |
                            amd64                           at 9:20am (UTC)                            (20170504_02:41)
+-------+-------------+------+-------------+------+-------+---------------+
$

To save yourself from having to remember the cryptic fingerprint as an image identifier for the copied image in the local image store, you can create an alias while copying the image as follows:

$ sudo lxc image copy images:debian/stretch local: --alias debian-stretch
Image copied successfully!               
$ sudo lxc image list debian
+---------+-------------+-------+-------------+-------+----v-+-------------+
| ALIAS | FINGERPRINT  |PUBLIC| DESCRIPTION    | ARCH  | SIZE  | UPLOAD DATE  |
+---------+-------------+-------+-------------+-------+------+-------------+
|debian-| 93e45634460f | no   | Debian stretch | x86_64|95.98MB| May 26, 2017 | stretch                         amd64                             at 9:14am (UTC)                                  (20170504_02:41)
+---------+-------------+-------+-------------+-------+------+-------------+
$                                                                              

Importing Images

The LXD image formats described previously in the “LXD Image Formats” section can be imported to the local image store using the lxc import command as describe in this section.

To import a single tarball or the unified tarball, with an alias to refer it, use the following command:

$ sudo lxc image import xenial-server-cloudimg-amd64-lxd.tar.xz --alias custom-xenial
Image imported with fingerprint: a1fca7830c07fb024fa246fb02798e3627caafd793bba81397e6a7bd8b5f547e
$ sudo lxc image list
+--------+-------------+--------+-------------+------+------+-------------+
| ALIAS | FINGERPRINT | PUBLIC | DESCRIPTION  | ARCH | SIZE | UPLOAD DATE |
+--------+-------------+--------+-------------+------+------+-------------+
|custom-| a1fca7830c07 | no     | Ubuntu 16.04  |x86_64|0.00MB| May 26, 2017|  xenial                           LTS server                    at 9:23am (UTC)                                 (20170525)
+--------+-------------+--------+-------------+------+------+-------------+
$

To import split tarballs (i.e., two separate tarballs) with an alias, use the following command:

$ sudo lxc image import meta.tar.gz rootfs.tar.xz --alias split-xenial
Image imported with fingerprint: e127122143e88dd7f18eae7e60cfecdc6f0c4fc5b469689def6f4a0c70fab0d7
$ sudo lxc image list
+--------+-------------+--------+------------+-------+------+--------------+
| ALIAS | FINGERPRINT | PUBLIC |   DESCRIPTION  | ARCH |SIZE   | UPLOAD DATE |
+--------+-------------+--------+------------+-------+------+--------------+
| split | e127122143e8| no     | Ubuntu 16.04   |x86_64|81.93MB|May 26, 2017 | -xenial                         LTS server                     at 9:30am (UTC)                                     (20170525)
+--------+-------------+--------+-------------+------+------+--------------+                                                                              
$

Viewing and Editing Image Information

To get detailed information about an image, use the following command:

$ sudo lxc image info ubuntu:16.04
Fingerprint: 8fa08537ae51c880966626561987153e72d073cbe19dfe5abc062713d929254d
Size: 153.70MB
Architecture: x86_64
Public: yes
Timestamps:
        Created: 2017/05/16 00:00 UTC
        Uploaded: 2017/05/16 00:00 UTC
        Expires: 2021/04/21 00:00 UTC
        Last used: never
Properties:
        description: ubuntu 16.04 LTS amd64 (release) (20170516)
        os: ubuntu
        release: xenial
        version: 16.04
        architecture: amd64
        label: release
        serial: 20170516
Aliases:
        - 16.04
        - 16.04/amd64
        - default
        - default/amd64
        - lts
        - lts/amd64
        - x
        - x/amd64
        - xenial
        - xenial/amd64
Auto update: disabled                                                
$

The lxc image edit command allows you to edit this image information with the help of a text editor that will pop up when the command is issued:

$ sudo lxc image edit split-xenial

The contents shown for editing inside the text editor will look like the following:

### This is a yaml representation of the image properties.
### Any line starting with a '# will be ignored.
###
### Each property is represented by a single line:
### An example would be:
###  description: My custom image

auto_update: false
properties:
 architecture: x86_64
 description: Ubuntu 16.04 LTS server (20170525)
 os: ubuntu
 release: xenial         
public: false

Deleting Images

You can delete images from the image store as follows:

$ sudo lxc image delete 3e50ba589426

For the last argument, you can use either the image alias or the fingerprint.

Exporting Images

If you want to send LXD images to someone else, there is an option to export an image:

$ sudo lxc image export split-xenial
Output is in .
$ ls * -alh
-rw------- 1 root root 82M May 26 15:10 e127122143e88dd7f18eae7e60cfecdc6f0c4fc5b469689def6f4a0c70fab0d7.tar.xz
-rw------- 1 root root 456 May 26 15:10 meta-e127122143e88dd7f18eae7e60cfecdc6f0c4fc5b469689def6f4a0c70fab0d7.tar.gz
$