systemd containers

systemd-nspawn and machinectl are lightweight container management tools.

They are deployed as part of systemd with the systemd-container package.

system preparing

we should enable namespaces kernel feature

$ echo 'kernel.unprivileged_userns_clone=1' >/etc/sysctl.d/nspawn.conf
$ systemctl restart systemd-sysctl.service

It's require action to make work UIDs mapping. You can read more from official documentation.

creating Debian container

Require debootstrap package to get basic environment for our container

$ debootstrap --include=systemd-container stable /var/lib/machines/debian
I: Target architecture can be executed
I: Retrieving InRelease
I: Checking Release signature

systemd-container package required to login container using machinectl

After bootstrapping we can login to container to make additional changes

$ systemd-nspawn -D /var/lib/machines/debian -U --machine debian
Spawning container buster on /var/lib/machines/buster.
Press ^] three times within 1s to kill container.
Selected user namespace base 818610176 and range 65536.

# set root password
root@stable:~# passwd
New password:
Retype new password:
passwd: password updated successfully

# allow login via local tty
root@stable:~# echo 'pts/0' >>/etc/securetty

# logout from container using ctrl+D
root@buster:~# logout
Container buster exited successfully.

now we can boot container using systemd-nspawn@.service unit

$ systemctl start systemd-nspawn@debian

@debian - that name should be same as machine folder name in /var/lib/machines/

checking state of machine

$ machinectl list
debian container systemd-nspawn debian 10      -

# or
$ systemctl status systemd-nspawn@buster
‚óŹ systemd-nspawn@buster.service - Container buster
   Loaded: loaded (/lib/systemd/system/systemd-nspawn@.service; disabled; vendor preset: enabled)
   Active: active (running) since ...

now we can login to console

$ machinectl login buster
Connected to machine debian. Press ^] three times within 1s to exit session.

Debian GNU/Linux 10 debian pts/0

debian login:


container communicates with host machine using virtual interface named ve-{container_name}

$ ip a show dev ve-buster
77: ve-buster@if2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether ... brd ff:ff:ff:ff:ff:ff link-netnsid 1

Enable and start systemd-networkd.service on the host and in the container to automatically provision the virtual link via DHCP with routing onto host's external network interfaces.

TODO: Describe advanced networking configuration

Usage example

Deploy FreedomBox on a Sid container. This will take around 1.2 GB of disk space.

# create a new container using debootstrap
$ CDIR=/var/lib/machines/freedombox
$ sudo debootstrap --include=systemd-container sid $CDIR
$ sudo systemd-nspawn -D $CDIR --machine FreedomBox
root@FreedomBox:~# apt-get install -y freedombox

# set root password and stop the container
root@FreedomBox:~# passwd root
root@FreedomBox:~# ^D

# start the container and its services
$ sudo systemd-nspawn -D $CDIR --machine FreedomBox -b

# Browse to

# To stop the container, either issue:
$ sudo machinectl stop FreedomBox

# or log in and run "halt". Simply logging out does not stop a container started with "-b"

CategorySoftware | CategoryVirtualization | CategorySystemAdministration