There is excellent documentation for getting started with LXD in the online LXD README. There is also an online server allowing you to try out LXD remotely. Stephane Graber also has an excellent blog series on LXD 2.0. Finally, there is great documentation on how to drive lxd using juju.

This document will offer an Ubuntu Server-specific view of LXD, focusing on administration.

LXD is pre-installed on Ubuntu Server cloud images. On other systems, the lxd package can be installed using:

sudo apt install lxd

This will install LXD as well as the recommended dependencies, including the LXC library and lxcfs.

In general, Ubuntu 16.04 should have all the desired features enabled by default. One exception to this is that in order to enable swap accounting the boot argument swapaccount=1 must be set. This can be done by appending it to the GRUB_CMDLINE_LINUX_DEFAULT=variable in /etc/default/grub, then running 'update-grub' as root and rebooting.

By default, LXD is installed listening on a local UNIX socket, which members of group LXD can talk to. It has no trust password setup. And it uses the filesystem at /var/lib/lxd to store containers. To configure LXD with different settings, use lxd init. This will allow you to choose:

You must run 'lxd init' as root. 'lxc' commands can be run as any user who is member of group lxd. If user joe is not a member of group 'lxd', you may run:

adduser joe lxd

as root to change it. The new membership will take effect on the next login, or after running 'newgrp lxd' from an existing login.

For more information on server, container, profile, and device configuration, please refer to the definitive configuration provided with the source code, which can be found online

This section will describe the simplest container tasks.

By default, LXD is socket activated and configured to listen only on a local UNIX socket. While LXD may not be running when you first look at the process listing, any LXC command will start it up. For instance:

lxc list

This will create your client certificate and contact the LXD server for a list of containers. To make the server accessible over the network you can set the http port using:

lxc config set core.https_address :8443

This will tell LXD to listen to port 8843 on all addresses.

Containers are configured according to a set of profiles, described in the next section, and a set of container-specific configuration. Profiles are applied first, so that container specific configuration can override profile configuration.

Container configuration includes properties like the architecture, limits on resources such as CPU and RAM, security details including apparmor restriction overrides, and devices to apply to the container.

Devices can be of several types, including UNIX character, UNIX block, network interface, or 'disk'. In order to insert a host mount into a container, a 'disk' device type would be used. For instance, to mount /opt in container c1 at /opt, you could use:

lxc config device add c1 opt disk source=/opt path=opt

See:

lxc help config

for more information about editing container configurations. You may also use:

lxc config edit c1

to edit the whole of c1's configuration in your specified $EDITOR. Comments at the top of the configuration will show examples of correct syntax to help administrators hit the ground running. If the edited configuration is not valid when the $EDITOR is exited, then $EDITOR will be restarted.

Profiles are named collections of configurations which may be applied to more than one container. For instance, all containers created with 'lxc launch', by default, include the 'default' profile, which provides a network interface 'eth0'.

To mask a device which would be inherited from a profile but which should not be in the final container, define a device by the same name but of type 'none':

lxc config device add c1 eth1 none

Containers all share the same host kernel. This means that there is always an inherent trade-off between features exposed to the container and host security from malicious containers. Containers by default are therefore restricted from features needed to nest child containers. In order to run lxc or lxd containers under a lxd container, the 'security.nesting' feature must be set to true:

lxc config set container1 security.nesting true

Once this is done, container1 will be able to start sub-containers.

In order to run unprivileged (the default in LXD) containers nested under an unprivileged container, you will need to ensure a wide enough UID mapping. Please see the 'UID mapping' section below.

LXD supports flexible constraints on the resources which containers can consume. The limits come in the following categories:

For a full list of limits known to LXD, see the configuration documentation.

By default, LXD creates unprivileged containers. This means that root in the container is a non-root UID on the host. It is privileged against the resources owned by the container, but unprivileged with respect to the host, making root in a container roughly equivalent to an unprivileged user on the host. (The main exception is the increased attack surface exposed through the system call interface)

Briefly, in an unprivileged container, 65536 UIDs are 'shifted' into the container. For instance, UID 0 in the container may be 100000 on the host, UID 1 in the container is 100001, etc, up to 165535. The starting value for UIDs and GIDs, respectively, is determined by the 'root' entry the /etc/subuid and /etc/subgid files. (See the subuid(5) manual page.

It is possible to request a container to run without a UID mapping by setting the security.privileged flag to true:

lxc config set c1 security.privileged true

Note however that in this case the root user in the container is the root user on the host.

LXD confines containers by default with an apparmor profile which protects containers from each other and the host from containers. For instance this will prevent root in one container from signaling root in another container, even though they have the same uid mapping. It also prevents writing to dangerous, un-namespaced files such as many sysctls and /proc/sysrq-trigger.

If the apparmor policy for a container needs to be modified for a container c1, specific apparmor policy lines can be added in the 'raw.apparmor' configuration key.

All containers are confined by a default seccomp policy. This policy prevents some dangerous actions such as forced umounts, kernel module loading and unloading, kexec, and the open_by_handle_at system call. The seccomp configuration cannot be modified, however a completely different seccomp policy - or none - can be requested using raw.lxc (see below).

LXD configures containers for the best balance of host safety and container usability. Whenever possible it is highly recommended to use the defaults, and use the LXD configuration keys to request LXD to modify as needed. Sometimes, however, it may be necessary to talk to the underlying lxc driver itself. This can be done by specifying LXC configuration items in the 'raw.lxc' LXD configuration key. These must be valid items as documented in the lxc.container.conf(5) manual page.

LXD is image based. When you create your first container, you will generally do so using an existing image. LXD comes pre-configured with three default image remotes:

To view the images available on one of these servers, you can use:

lxc image list ubuntu:

Most of the images are known by several aliases for easier reference. To see the full list of aliases, you can use

lxc image alias list images:

Any alias or image fingerprint can be used to specify how to create the new container. For instance, to create an amd64 Ubuntu 14.04 container, some options are:

lxc launch ubuntu:14.04 trusty1
lxc launch ubuntu:trusty trusty1
lxc launch ubuntu:trusty/amd64 trusty1
lxc launch ubuntu:lts trusty1

The 'lts' alias always refers to the latest released LTS image.

To view debug information about LXD itself, on a systemd based host use

journalctl -u LXD

On an Upstart-based system, you can find the log in /var/log/upstart/lxd.log. To make LXD provide much more information about requests it is serving, add '--debug' to LXD's arguments. In systemd, append '--debug' to the 'ExecStart=' line in /lib/systemd/system/lxd.service. In Upstart, append it to the exec /usr/bin/lxd line in /etc/init/lxd.conf.

Container logfiles for container c1 may be seen using:

lxc info c1 --show-log

The configuration file which was used may be found under /var/log/lxd/c1/lxc.conf while apparmor profiles can be found in /var/lib/lxd/security/apparmor/profiles/c1 and seccomp profiles in /var/lib/lxd/security/seccomp/c1.