github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/drivers/external/nspawn.mdx

---
layout: docs
page_title: 'Drivers: Systemd-Nspawn'
sidebar_title: 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` - Path to the image to be used in the container. This can either be a
  [directory](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-D)
  or the path to a file system
  [image](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-i)
  or block device. Can be specified as a relative path from the configured Nomad
  plugin directory. **This option is mandatory**.
* [`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
    }
  }
  ```


## Networking

Currently the `nspawn` driver only supports host networking.

## 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`).

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

```hcl
plugin "nspawn" {
  config {
    enabled = 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