Appendix D: Installing MAAS in a LXD Container
==============================================

It is possible to install MAAS in a virtual machine or container. Doing so
will help to isolate MAAS from the underlying OS and enable relatively easy
backup and restoration of the complete MAAS environment. To facilitate this
setup, the certification PPA includes a package, called ``maas-lxc-host``,
which includes scripts and tools to run on the host system in order to
install MAAS in a LXC/LXD container. Note, however, that *this procedure is
still experimental!* Although it can be made to work, it is delicate, and
can easily fail because of system-specific configuration issues or because
of minor deviations from the specified procedure.

If you want to run MAAS in this way, follow these steps:

#. Ensure that the host has sufficient disk space. The container consumes
   128 GiB of disk space, in ``/var/snap/lxd/common/lxd/disks/``.

#. Install Ubuntu Server on the server you want to host the LXD container
   and configure the server's network as described earlier, in :doc:`install-configure-ubuntu`.

#. Type ``sudo apt-add-repository ppa:checkbox-dev/stable`` to
   add the Hardware Certification PPA to the host server.

#. Install the ``maas-lxc-host`` package by typing ``sudo apt install
   maas-lxc-host``.

#. If you're using a remote SSH session, type ``screen``. The setup process
   may interrupt network connectivity, so you'll have to reconnect
   mid-process. Better, use a physical console or remote KVM, which will
   not be affected by this interruption.

#. Type ``lxc-setup``. This runs the LXC/LXD setup script, which proceeds
   to run through the setup steps, asking you some questions along the
   way...

   #. If you're running remotely, the script checks to see if ``screen`` is
      in use. If so, you'll be asked to confirm that you want to continue.

   #. At least once, and perhaps multiple times, you'll be asked to enter
      your password. Do so whenever prompted.

   #. The script tries to identify the internal and external network
      devices on the host, and asks you to verify each one. It then creates
      network bridges for the future container. Once this is done, the
      script gives you the option to manually edit the NetPlan
      configuration file, in case you want to make your own tweaks. Note
      that the script tries to configure the external network interface
      (``br1``) using DHCP. This is likely to result in the external
      network interface's IP address changing compared to its original
      configuration unless you manually edit it to use a static IP address;
      but this may not be appropriate. You should make changes suitable for
      your own network.

   #. After configuring the network, your remote network access is likely
      to go down, if you're running remotely. You should be able to
      reconnect (doing so via the internal network interface may be easier
      than trying to find the new external IP address) and run ``screen -r``
      to resume.

   #. After configuring LXD, the script sets up the LXD container's network
      options. As with the host's network configuration, the script gives
      you the option of reviewing and editing the settings. By default, the
      internal network (``eth0``) is given an address one higher than the
      host (for instance, 172.24.124.2, to the host's 172.24.124.1), and
      the external address is configured via DHCP.

   #. At this point, the script asks if you want to set up MAAS in the LXD
      container. If you respond by typing ``Y`` (which is the default), the
      script installs ``maas-cert-server`` in the LXD container and then
      runs ``setup-certlab``, as described in :ref:`Running the Setup Script`.
      For the most part, you can configure the MAAS server in the LXD
      container just as you would a MAAS server running directly on a
      server; however....

   #. When the setup script asks if you want to configure the server as a
      NAT router, you may want to answer ``N``. The NAT control scripts are
      installed on both the host and the container, but using the host as a
      NAT router provides a more direct route to the outside world than
      would be the case if you used the LXD container for this purpose.
      this topic is covered in more detail shortly.

#. If the ``lxc-setup`` script fails at some point, you can try fixing
   whatever problem is reported and re-running the script; however, this
   use case is not yet well-tested and so may fail. You may need to copy
   ``/usr/sbin/lxc-setup`` to your home directory and edit it to work
   around the problems.

The result of this configuration is that the computer will have at least
four IP addresses: internal and external for the host computer itself and
for the LXD container. The latter will run MAAS and an SSH server, but the
latter may not be usable until you import your SSH public keys into the LXD
container's ``ubuntu`` account. You can do this from the host by typing::

  lxc exec lxc-maas bash
  su ubuntu
  ssh-import-id lp:username
  exit
  exit

Change ``username`` to your Launchpad username. Alternatively, you can add
SSH public keys in any way you like, such as by editing
``~/.ssh/authorized_keys``.

If you prefer, you can access the LXD container from the host by typing
``lxc exec lxc-maas bash`` every time; however, this is likely to be more
awkward than enabling direct SSH access to the container.

In either case, the LXD container shares the ``/home/username`` and
``/srv`` directories with the host, where ``username`` is your username on
the host. The former enables you to easily share arbitrary files between the
host and its container; and the latter is intended to simplify
configuration of Apache to deliver virtualization files needed by the
virtualization tests. Because ``setup-certlab`` configures Apache on the
LXD container and optionally downloads virtualization files, it's easy to
set up the container as the server for these files; however, storing these
large files outside of the container may be desirable. You can also install
Apache on the host and deliver these files from that location, if you
prefer.

The ``setup-certlab`` script configures the MAAS server computer (that is,
the LXD container, when MAAS is installed this way) as the router for the
internal network. If you want to use the host instead, you must take some
extra steps:

1. On the host computer, type ``sudo systemctl enable certification-nat``
   to configure it to enable NAT on the next reboot

#. Type ``sudo service certification-nat start`` on the host to start NAT
   immediately.

#. In the MAAS web UI, select Subnets from the options at the top of the
   page, and then select the internal subnet (under the "Subnet" column)
   from the list.

#. Click the Edit button to the right of the Subnet Summary section.

#. Change Gateway IP to match the host computer's IP address, rather
   than the LXD container's IP address. (You can make other changes here,
   too, if necessary for your network.)

#. Click Save Summary to save your changes.

The ``iperf3`` server is installed on both the host and the LXD container
at the end of this process, but it's not configured to launch automatically
from either location. In theory, network tests can use either location as a
target, once you launch ``iperf3`` in the correct environment; however,
running ``iperf3`` on the host is less likely to cause performance problems
and is therefore recommended. If you run ``iperf3`` on the LXD container
and encounter network test failures, you should try running ``iperf3`` on
the host and using it as a target instead. Note that network performance
will be limited by the capabilities of the host; you can't run full-speed
tests against both the host and the LXD container and expect to get twice
the host's native network speed!

A fresh installation of MAAS in a LXC/LXD container will consume about 6
GiB of disk space in the ``/var/snap/lxd/common`` directory (or
``/var/lib/lxd/storage-pools/default/containers/``, if using an Ubuntu
18.04 host). This space is likely to grow over time, especially if you add
support for multiple Ubuntu versions and CPU architectures to your MAAS
configuration. (Each new version requires ``cloud-init`` files that consume
some space.)

You can use numerous commands to manage your MAAS container. These include,
but are not limited to:

* ``lxc list`` -- Shows a list of containers and some summary information
  about them, including their IP addresses and whether or not they're
  running.

* ``lxc info`` -- Displays summary information about a specified container
  (more than is shown by ``lxc list``).

* ``lxc exec`` -- Runs a command in a container. In particular, ``lxc exec
  lxc-maas bash`` runs ``bash`` in the ``lxc-maas`` container (the name of
  the container created by ``lxc-setup``).

* ``lxc stop`` -- Stops a specified container.

* ``lxc start`` -- Starts a specified container. Note that the container
  created by ``lxc-setup`` should start up automatically when the host
  boots.

* ``lxc restart`` -- Restarts a specified container.

* ``lxc snapshot`` -- Creates a snapshot of a specified container.

* ``lxc restore`` -- Restores a snapshot of a specified container.

The ``lxc-setup`` script creates a container that's 128 GiB in size. This
is normally adequate. (If you create a local APT mirror, that mirror can be
much bigger than this, but it will normally be hosted in ``/srv``, which is
a filesystem that's shared with the host, and so does not count against the
container's size.) Versions of ``lxc-setup`` prior to ``maas-cert-server``
0.6.2, however, created a container that's only 30 GiB in size. If the
container fills up, symptoms can include a sluggish container, an
unresponsive MAAS server, and a high CPU load on the host. You can type
``df /`` inside the container to check its disk use. If you find the
container is low on disk space, you may want to begin by reviewing your
installed images in MAAS. Delete unused images, such as for old releases or
architectures you don't test. If you're still low on disk space in the
container, you can increase its size as follows:

#. On the host, verify that ``/var/snap/lxd/common/lxd/disks/default.img``
   exists. This file should hold the container's filesystem; but its
   location could differ if you installed in some unusual way or if you're
   using something other than 20.04 as the host OS.

#. On the host, check to see how much disk space is available in the
   filesystem that holds the container, as just identified. (This is
   usually in your root filesystem, ``/``, so ``df -h /`` will give you the
   information you need.)

#. On the host, type the following commands::

      sudo truncate -s +100G /var/snap/lxd/common/lxd/disks/default.img
      sudo zpool set autoexpand=on default
      sudo zpool online -e default /var/snap/lxd/common/lxd/disks/default.img
      sudo zpool set autoexpand=off default

   If necessary, change the path to the container's filesystem file; and if
   desired or necessary, change ``+100G`` to a suitable value for a change
   to the filesystem size. *Be sure that* ``100G`` *is preceded by a plus
   sign (* ``+`` *)!*

#. Log into the container.

#. Verify that the available disk space has increased, such as by
   typing ``df -h /``.

This documentation can provide only a brief summary of LXC/LXD commands and
tools. For more information, see the official Linux containers
documentation at https://linuxcontainers.org. You can also type ``lxc``
with no options to see a summary of sub-commands, or type ``lxc`` with a
subcommand to see a summary of how to use it, if the subcommand requires
additional options.

.. raw:: pdf

   PageBreak