systemd-nspawn

Run a command in a container

$ systemd-nspawn [[-D|--directory]] [path/to/container_root]

$ systemd-nspawn [[-b|--boot]] [[-D|--directory]] [path/to/container_root]

$ systemd-nspawn [[-D|--directory]] [path/to/container_root] [[-a|--as-pid2]]

$ systemd-nspawn [[-M|--machine]] [container_name] --hostname [container_host] [[-D|--directory]] [path/to/container_root]

systemd-nspawn [OPTIONS...] [DIRECTORY [COMMAND [ARGUMENTS...]]]

-D, --directory=PATH
    Specifies the root directory of the container. This is the only mandatory argument for most uses, defining the container's filesystem.

-M, --machine=NAME
    Assigns a specific machine NAME to the container. This integrates the container with machinectl, allowing for easy management like starting, stopping, and logging in.

-b, --boot
    Instructs nspawn to boot a full system into the container, by looking for an init executable (typically /sbin/init or /usr/lib/systemd/systemd) and executing it. This runs a complete systemd instance inside the container.

-U, --private-users
    Sets up a private user namespace for the container. This maps container's UIDs/GIDs to different UIDs/GIDs on the host, enhancing isolation.

--bind=HOST_PATH[:CONTAINER_PATH][:OPTIONS]
    Bind-mounts a file or directory from the host filesystem into the container. Useful for sharing data or host-specific configurations.

--overlay=HOST_PATH_LOWER:HOST_PATH_UPPER
    Sets up an overlay filesystem for the container. Changes made inside the container are written to HOST_PATH_UPPER, leaving HOST_PATH_LOWER (the base image) untouched.

--network-veth
    Creates a private virtual Ethernet (veth) link for the container, providing it with its own isolated network interface.

--network-bridge=BRIDGE
    Connects the container's private network interface to a specified host bridge device (e.g., br0), allowing the container to share the host's network or be part of a custom network.

--read-only
    Mounts the container's root directory read-only. Any attempts to write will fail or be redirected if an overlay filesystem is also used.

--drop-capability=CAPABILITY
    Drops a specific Linux capability (e.g., CAP_SYS_ADMIN) from the container's process, limiting what it can do inside.

systemd-nspawn is a command-line utility that can be used to run a command or an operating system in a lightweight namespace container.

It's often described as an extended chroot, leveraging Linux namespaces (PID, mount, network, IPC, UTS, user) and control groups (cgroups) to provide a more isolated environment. Unlike full virtualization, nspawn shares the host kernel, making it very fast and resource-efficient. It's particularly useful for testing operating system installations, developing systemd services, or creating minimal, isolated development environments.

While it offers significant isolation, it's generally not considered a hardened security sandbox for untrusted applications like Docker or LXC might be when configured for stronger isolation. Its primary focus is on system-level containerization, enabling a complete operating system to run within a container, often with its own systemd instance, making it ideal for testing system upgrades or different distribution configurations without affecting the host system.

While systemd-nspawn provides strong isolation through Linux namespaces and cgroups, it's important to understand its limitations:

Not a Security Sandbox: It shares the host kernel, making it inherently less isolated than full virtualization. Misconfigurations or kernel vulnerabilities could potentially affect the host system.

Root Privileges: Most features, especially networking and resource management, require root privileges to set up and manage containers.

Resource Management: While cgroups are used, fine-grained resource control (CPU, memory, I/O limits) often requires manual configuration of cgroup settings on the host, which can be complex.

Container Images: systemd-nspawn expects a full root filesystem of a Linux distribution. It doesn't manage image layers or registries like Docker, requiring manual setup or pre-built images.

systemd-nspawn offers several networking modes.
The default is 'host-network', where the container shares the host's network namespace, but this offers minimal network isolation.
Using --network-veth creates a dedicated virtual Ethernet pair, giving the container its own private network stack. This isolated interface can then be connected to a host bridge via --network-bridge=BRIDGE, allowing the container to communicate with the host and other containers on the same bridge, or to gain external network access through the host's routing or NAT setup.

The -M or --machine=NAME option is key to systemd-nspawn's integration with machinectl. When a machine name is provided, nspawn registers the container with systemd-machined. This allows machinectl to manage the container's lifecycle (e.g., machinectl start NAME, machinectl stop NAME, machinectl shell NAME), introspect its status, and manage its resources. This tight integration makes nspawn containers first-class citizens within the systemd ecosystem, providing a unified interface for managing virtual machines and containers.

systemd-nspawn was introduced as part of the systemd project, designed to provide a more advanced form of containerization than traditional chroot environments. Its development focused on deep integration with systemd's capabilities, allowing containers to run full systemd instances and be managed alongside other system services. It aimed to bridge the gap between simple chroot jails and heavier virtualization solutions, providing a lightweight, systemd-native way to run isolated Linux environments, primarily for development, testing, and system recovery scenarios.

chroot(1), machinectl(1), systemd(1), namespaces(7), cgroups(7), lxc(7)