Container systemd-nspawn – Installation

Author: Peter Boy (pboy) | Creation Date: N/A | Last update: N/A | Related Fedora Version(s): 33

Work in progress.General conceptualization of content, text completion in progress.

Request for comments on the content concept

Some Useful information

The systemd-nspawn container runtime is part of the systemd system software. It has been offloaded into its own package, systemd-container, a while ago and must now installed separately. The toolset is powerful, yet lightweight and has low runtime overhead.

The management tools already used for the host system are applied to containers simply by specifying an additional parameter (-m <CONTAINER>), e.g. journalctl. Start and stop of containers is done using systemctl in the same way as all other system services. This makes the learning curve quite flat and maintenance quite simple.

The creation of a container filesystem or the provision of a corresponding image is treated as "out of scope" by systemd-nspawn. There are a number of alternative options. By far the easiest and most efficient way is simply to use dnf in the container’s directory, and this is the recommended procedure. Additional options are presented at the end.

Installation Destination

The systemd-nspawn tools as machinctl first search for containers in /var/lib/machines/. If not exist, this directory is automatically created the installation process. For each container to be created, a subdirectory with its name will be generated and the it’s directory tree will be created therein. The directory is therefore directly container ROOT.

According to the default concept of Fedora Server disk partitioning, a separate logical volume should be created for this purpose and mounted at the respective position. There are 2 valid alternatives and one 'quick & dirty' solution:

  • Logical volume of appropriate size for all containers, formatted as BTRFS and mounted at /var/lib/machines

  • For eaxch container a thin provisioned logical volume of appropriate inital size, formatted as XFS and mounted at /var/lib/machines/<CONTAINER>

and as a quick solution

  • Logical volume of appropriate size for all containers, formatted as XFS and mounted at /var/lib/machines

The former one is the most recommended way.

BTRFS Logical Volume

(comming soon)

Thin Provisioning XFS Volumes per Container

(comming soon

XFS Logical Volume

(comming soon)

Software Installation

  • Checking SELinux labels according to the choosen storage alternative[source,]

ls -alZ  /var/lib/machines
if necessary, fix the SELinux labels
[…]# restorecon  -vFr /var/lib/machines
[…]# chown root:root /var/lib/machines
[…]# chmod 700 /var/lib/machines
  • Installation step

 […]# dnf install systemd-container

Container Creation

  1. Creating a Subdirectory

    • According to the storage strategie BTRFS subvolume, LVM thin volume, subdrectory

  2. Creating Fedora 33 directory tree

  […]# dnf --releasever=33 --best --setopt=install_weak_deps=False --installroot=/var/lib/machines/{ctname}/ install dhcp-client dnf fedora-release glibc glibc-langpack-en glibc-langpack-de iproute iputils less passwd systemd vim-minimal
During installation, a message appears several times:
 Scriptlet executed: {PACKAGE} install-info: File or directory not found for /dev/nul
Can be savely be ignored.

Container Configuration And Commissioning

  1. Set the password for root:

    (for the time being SELinux must be switched into permissive mode, otherwise passwd fails)
    […]# setenforce 0
    […]# systemd-nspawn -D /var/lib/machines/{ctname}   passwd
    ## Example: […]#  systemd-nspawn -D /var/lib/machines/testn   passwd
    […]# setenforce 1
  2. Configuring Network connectivity

    1. On Host

    2. Inside Container

  3. Boot Container and loggin[source,]

[…]# systemd-nspawn -D /var/lib/machines/{ctname}  -b

## expect
## OK Spawning container test01 on /var/l…01.
## OK …
##{ctname} login:

Container as System Service

[…]# systemctl  enable  systemd-nspawn@{ctname}
[…]# systemctl  start  systemd-nspawn@{ctname}
[…]# systemctl  status  systemd-nspawn@{ctname}

Loggin to the container [source,]

[…]# machinectl  login  {ctname}

Alternately (e.g. if login as root is blocked

[…]# machinectl  shell  {ctname}


SELinux blocks container startup

  • usual SELinux fix

Root login fails

  • journalctl displays: pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !

  • Solution: Delete /etc/securetty[7] and /usr/share/factory/etc/securetty on the container file system.

Using machinetl without root permission

  • (requires polkit fix)


Containers of foreign distributions

Debian & Ubuntu

Fedora includes a customized version of the Debian / Ubuntu installer. This can be used to create the file system for corresponding containers. [source,]

[…]# dnf install debootstrap
[…]# debootstrap  {distro}  {targetdir}  {repo-url}

As an Ubuntu example

[…]# debootstrap  bionic /var/lib/machines/bionic

and a Debian example[source,]

[…]# debootstrap stable /var/lib/machines/deb

The installation process displays some error messages, about stub-resolv.con, release agent, of firewall config. These can savely be ignored.

Project mkosi

  • Program very extensive

  • Provide customer image management

The project uses python and pip is a easy installation path.

[…]# yum install git
[…]# python3 -m pip install --user git+
  • start the program

  • usage by example

These nice people helped write this page:

Peter Boy, Jan Kuparinen

Want to help? Learn how to contribute to Fedora Docs.