---
layout: docs
page_title: 'Drivers: systemd-nspawn'
description: The nspawn task driver is used to run application containers using systemd-nspawn.
---

# nspawn Driver

Name: `nspawn`

The `nspawn` driver provides an interface for using systemd-nspawn for running
application containers. You can download the external systemd-nspawn driver
[here][nspawn-driver]. For more detailed instructions on how to set up and use
this driver, please refer to the [guide][nspawn-guide].

## Task Configuration

```hcl
task "debian" {
  driver = "nspawn"
  config {
    image = "/var/lib/machines/Debian"
    resolv_conf = "copy-host"
  }
}
```

The `nspawn` driver supports the following configuration in the job spec:

- [`boot`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-b) -
  (Optional) `true` (default) or `false`. Search for an init program and invoke
  it as PID 1. Arguments specified in `command` will be used as arguments for
  the init program.

- [`ephemeral`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-x) -
  (Optional) `true` or `false` (default). Make an ephemeral copy of the image
  before staring the container.

- [`process_two`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-a) -
  (Optional) `true` or `false` (default). Start the command specified with
  `command` as PID 2, using a minimal stub init as PID 1.

- [`read_only`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--read-only) -
  (Optional) `true` or `false` (default). Mount the used image as read only.

- [`user_namespacing`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-U) -
  (Optional) `true` (default) or `false`. Enable user namespacing features
  inside the container.

- `command` - (Optional) A list of strings to pass as the used command to the
  container.

  ```hcl
  config {
    command = [ "/bin/bash", "-c", "dhclient && nginx && tail -f /var/log/nginx/access.log" ]
  }
  ```

- [`console`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--console=MODE) -
  (Optional) Configures how to set up standard input, output and error output
  for the container.

- `image` - The image to be used in the container. This can either be the path
  to a
  [directory](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-D),
  the path to a file system
  [image](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-i)
  or block device or the name of an image registered with
  [`systemd-machined`](https://www.freedesktop.org/software/systemd/man/systemd-machined.service.html).
  A path can be specified as a relative path from the configured Nomad plugin
  directory. **This option is mandatory**.

- `image_download` - (Optional) Download the used image according to the
  settings defined in this block. Structure is documented below.

- [`pivot_root`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--pivot-root=) -
  (Optional) Pivot the specified directory to the be containers root directory.

- [`resolv_conf`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--resolv-conf=) -
  (Optional) Configure how `/etc/resolv.conf` is handled inside the container.

- [`user`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-u) -
  (Optional) Change to the specified user in the containers user database.

- [`volatile`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--volatile) -
  (Optional) Boot the container in volatile mode.

- [`working_directory`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--chdir=) -
  (Optional) Set the working directory inside the container.

- [`bind`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--bind=) -
  (Optional) Files or directories to bind mount inside the container.

  ```hcl
  config {
    bind {
      "/var/lib/postgresql" = "/postgres"
    }
  }
  ```

- [`bind_read_only`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#--bind=) -
  (Optional) Files or directories to bind mount read only inside the container.

  ```hcl
  config {
    bind_read_only {
      "/etc/passwd" = "/etc/passwd"
    }
  }

  ```

- `environment` - (Optional) Environment variables to pass to the init process
  in the container.

  ```hcl
  config {
    environment = {
      FOO = "bar"
    }
  }
  ```

- `port_map` - (Optional) A key-value map of port labels. Works the same way as
  in the [docker driver][docker_driver].

  **Note:** `systemd-nspawn` will not expose ports to the loopback interface
  of your host.

  ```hcl
  config {
    port_map {
      http = 80
    }
  }
  ```

The `image_download` block supports the following arguments:

- `url` - The URL of the image to download. The URL must be of type `http://` or
  `https://`. **This option is mandatory**.

- [`verify`](https://www.freedesktop.org/software/systemd/man/machinectl.html#pull-tar%20URL%20%5BNAME%5D) -
  (Optional) `no` (default), `signature` or `checksum`. Whether to verify the
  image before making it available.

- `force` - (Optional) `true` or `false` (default) If a local copy already
  exists, delete it first and replace it by the newly downloaded image.

- `type` - (Optional) `tar` (default) or `raw`. The type of image to download.

## Networking

The `nspawn` driver has support for host networking and also bridge mode
networking. It can therefore be used with Nomad's [Consul Connect
integration][consul_connect_integration].

## Client Requirements

The `nspawn` driver requires the following:

- 64-bit Linux host
- The `linux_amd64` Nomad binary
- The nspawn driver binary placed in the [plugin_dir][plugin_dir] directory.
- `systemd-nspawn` to be installed
- Nomad running with root privileges

## Plugin Options

- `enabled` - The `nspawn` driver may be disabled on hosts by setting this
  option to `false` (defaults to `true`).

- `volumes` - Enable support for Volumes in the driver (defaults to `true`).

An example of using these plugin options with the new [plugin syntax][plugin] is
shown below:

```hcl
plugin "nspawn" {
  config {
    enabled = true
    volumes = true
  }
}
```

## Client Attributes

The `nspawn` driver will set the following client attributes:

- `driver.nspawn` - Set to `true` if systemd-nspawn is found and enabled on the
  host node and Nomad is running with root privileges.

- `driver.nspawn.version` - Version of `systemd-nspawn` e.g.: `244`.

[nspawn-driver]: https://github.com/JanMa/nomad-driver-nspawn/releases
[nspawn-guide]: https://github.com/JanMa/nomad-driver-nspawn
[plugin]: /docs/configuration/plugin
[plugin_dir]: /docs/configuration#plugin_dir
[plugin-options]: #plugin-options
[client_options]: /docs/configuration/client#options
[docker_driver]: /docs/drivers/docker#using-the-port-map
[consul_connect_integration]: /docs/integrations/consul-connect