Installation

Choose your release

LXD upstream maintains different release branches in parallel:

  • Long term support (LTS) releases: currently LXD 4.0.x and LXD 3.0.x
  • Feature releases: LXD 4.x

LTS releases are recommended for production environments as they will benefit from regular bugfix and security updates but will not see new features added or any kind of behavioral change.

To get all the latest features and monthly updates to LXD, use the feature release branch instead.

Installing a package

Linux

The easiest way to install LXD on Linux is to install the snap package, which is available for different Linux distributions.

If this option does not work for you, see the other installation options.

Snap package

LXD upstream publishes and tests snap packages that work for a number of Linux distributions, for example, Ubuntu, Arch Linux, Debian, Fedora and OpenSUSE.

Complete the following steps to install the snap:

  1. Check the provided distributions to see if a snap is available for your Linux distribution.
    If it is not, use one of the other installation options.

  2. Install snapd. See the installation instructions on snapcraft.io.

  3. Install the snap package.
    For the latest feature release, use:

    sudo snap install lxd
    

    For the LXD 4.0 LTS release, use:

    sudo snap install lxd --channel=4.0/stable
    

For more information about LXD snap packages (regarding more versions, update management etc.), see Managing the LXD snap.

Note

On Ubuntu 18.04, if you previously had the LXD deb package installed, you can migrate all your existing data over with:

sudo lxd.migrate

Other installation options

Some Linux distributions provide installation options other than the snap package.

To install the feature branch of LXD on Alpine Linux, run:

apk add lxd

To install the feature branch of LXD on Arch Linux, run:

pacman -S lxd

Fedora RPM packages for LXC/LXD are available in the COPR repository.

To install the LXD package for the feature branch, run:

dnf copr enable ganto/lxc4
dnf install lxd

See the Installation Guide for more detailed installation instructions.

To install the feature branch of LXD on Gentoo, run:

emerge --ask lxd

Other operating systems

Note

The builds for other operating systems include only the client, not the server.

LXD upstream publishes builds of the LXD client for macOS through Homebrew.

To install the feature branch of LXD, run:

brew install lxc

The LXD client on Windows is provided as a Chocolatey package. To install it:

  1. Install Chocolatey by following the installation instructions.
  2. Install the LXD client:

    choco install lxc
    

You can also find native builds of the LXD client on GitHub. To download a specific build:

  1. Make sure that you are logged into your GitHub account.
  2. Filter for the branch or tag that you are interested in (for example, the latest release tag or master).
  3. Select the latest build and download the suitable artifact.

Installing from source

To build and install LXD from source, follow the instructions in Installing LXD from source.

Initial configuration

Note

"Instances" means both containers and virtual machines.

Before you can create an instance, you need to configure LXD.

Run the following command to start the interactive configuration process:

sudo lxd init

See Interactive setup options for an explanation of the different configuration options.

To create a non-optimized minimal setup with default options, you can skip the configuration steps by adding the --minimal flag:

sudo lxd init --minimal

Note

Compared to the interactive configuration, the minimal setup will be slower and provide less functionality. Especially the dir storage backend (which is used by default) is slower and doesn't provide fast snapshots, fast copy/launch, quotas and optimized backups.

If you want to use an optimized setup, go through the interactive configuration process instead.

Security and access control

Access control for LXD is based on group membership. The root user and all members of the lxd group can interact with the local daemon.

If the lxd group is missing on your system, create it and restart the LXD daemon. You can then add trusted users to the group. Anyone added to this group will have full control over LXD.

Because group membership is normally only applied at login, you might need to either re-open your user session or use the newgrp lxd command in the shell you're using to talk to LXD.

Warning

Anyone with access to the LXD socket can fully control LXD, which includes the ability to attach host devices and file systems. Therefore, you should only give access to users who would be trusted with root access to the host.

You can learn more about LXD security here.

Interactive setup options

You can configure the following options during the initial configuration of LXD.

default=no means the feature is disabled by default.

Feature Description Basic configuration options More information
Clustering A cluster combines several LXD servers. They share the same distributed database and can be managed uniformly using the LXD client (lxc) or the REST API. default=no;
If set to yes, you can either connect to an existing cluster or create a new one.
LXD documentation:
Clustering
MAAS server MAAS is an open-source tool that lets you build a data center from bare-metal servers. default=no;
If set to yes, you can connect to an existing MAAS server and specify the name, URL and API key.
- maas.io
- MAAS - How to manage VM hosts
Network bridge Provides network access for the instances. You can either use an existing bridge (or interface) or let LXD create a new bridge (recommended).
You can also create additional bridges and assign them to instances later.
LXD documentation:
- Networks
- Network interface
Storage pools Instances etc. are stored in storage pools. For testing purposes, you can create a loop-backed storage pool.
But for production use you should use an empty partition (or full disk) instead of loop-backed storages (because loop-backed pools are slower and their size can't be reduced).
The recommended backends are ZFS and btrfs.
You can also create additional storage pools later.
LXD documentation:
- Storage
- Comparison of methods
- Backend comparison chart
Network access Allows access to the server over network. default=no;
If set to yes, you can connect to the server over network.
You can set a password or accept the client certificate manually.
-
Automatic image update You can download images from image servers. In this case, images can be updated automatically. default=yes;
If set to yes, LXD will update the downloaded images regularly.
LXD documentation:
Image handling
YAML lxd init preseed Will display a summary of your chosen configuration options in the terminal. default=no -

Note about virtual machines

Since version 4.0 LXD also natively supports virtual machines and thanks to a built-in agent, they can be used almost like containers.

LXD uses qemu to provide the VM functionality.

See below for how to start a virtual machine.

You can find more information about virtual machines in our forum1.

Note

For now virtual machines support less features than containers. See Advanced Guide - Instance configuration for details.

LXD client

The LXD client lxc is a command tool to manage your LXD servers.

Overview

The following command will give you an overview of all available commands and options:

lxc

Use lxc [command] --help for more information about a command, like flags and further options.

Launch an instance

You can launch an instance with the lxc launch command.

To launch a container:

lxc launch imageserver:imagename instancename

To launch a virtual machine:

lxc launch imageserver:imagename instancename --vm

In the commands above, replace:

  • imageserver with the name of a built-in or added image server (e.g. ubuntu or images).
  • imagename with the name of an image (e.g. 20.04 or debian/11). See Section "Images" for details.
  • instancename with a name of your choice (e.g. ubuntuone). If left empty, LXD will pick a random name.

For example, to create a container based on the Ubuntu Focal Fossa image (provided by LXD) with the instancename ubuntuone, enter the following command:

lxc launch ubuntu:20.04 ubuntuone

Configuration of instances

See Advanced Guide - Instance Configuration.

Images

Instances are based on Images, which contain a basic operating system (for example a linux distribution) and some other LXD-related information.

In the following we will use the built-in remote image servers (see below).

For more options see Advanced Guide - Advanced options for Images.

Use remote image servers

The easiest way is to use a built-in remote image server.

You can get a list of built-in image servers with:

lxc remote list

LXD comes with 3 default servers:

  1. ubuntu: (for stable Ubuntu images)
  2. ubuntu-daily: (for daily Ubuntu images)
  3. images: (for a bunch of other distros)

List images on server

To get a list of remote images on server images, type:

lxc image list images:

Details:

Most details in the list should be self-explanatory.

Search for images

You can search for images, by applying specific elements (e.g. the name of a distribution).

Show all Debian images:

lxc image list images: debian

Show all 64-bit Debian images:

lxc image list images: debian amd64

Images for virtual machines

It is recommended to use the cloud variants of images (visible by the cloud-tag in their ALIAS). They include cloud-init and the LXD-agent. They also increase their size automatically and are tested daily.

Instance management

List all instances:

lxc list

Start/stop

Start an instance:

lxc start instancename

Stop an instance:

lxc stop instancename

Shell/terminal inside container

Get a shell inside a container:

lxc exec instancename -- /bin/bash

By default you are logged in as root:

root@containername:~#

Log in as a user instead

Note

In many containers you need to create a user first.

lxc exec instancename -- su --login username

Exit the container shell, with:

username@containername:~# exit

Run command from host terminal

Run a single command from host's terminal:

lxc exec containername -- apt-get update

Shell/terminal inside virtual machine

You can see your VM boot with:

lxc console instancename

(detach with ctrl+a-q)

Once booted, VMs with the LXD-agent built-in, can be accessed with:

lxc exec instancename bash

Exit the VM shell, with:

exit

Copy files and folders between container and host

Copy from an instance to host

Pull a file with:

lxc file pull instancename/path-in-container path-on-host

Pull a folder with:

lxc file pull -r instancename/path-in-container path-on-host

For example:

lxc file pull instancename/etc/hosts .

Copy from host to instance

Push a file with:

lxc file push path-on-host instancename/path-in-container

Push a folder with:

lxc file push -r path-on-host instancename/path-in-container

Remove instance

Warning

This will delete the instance including all snapshots. Deletion will be final in most cases and restore is unlikely!

See Tips & Tricks in Advanced Guide on how to avoid accidental deletion.

Use:

lxc delete instancename

Further information & links

You find more information on the following pages:


  1. Running virtual machines with lxd, including a short howto for a Microsoft Windows VM.