2019-01-29 20:53:05 +00:00
---
2020-02-06 23:45:31 +00:00
layout: docs
page_title: 'Drivers: LXC'
description: The LXC task driver is used to run application containers using LXC.
2019-01-29 20:53:05 +00:00
---
# LXC Driver
Name: `lxc`
The `lxc` driver provides an interface for using LXC for running application
2019-02-01 18:12:18 +00:00
containers. You can download the external LXC driver [here][lxc-driver]. For more detailed instructions on how to set up and use this driver, please refer to the [LXC guide][lxc-guide].
2019-01-29 20:53:05 +00:00
2019-11-11 13:51:30 +00:00
~> **Note:** The LXC client set up has changed in Nomad 0.9. You must use the new [plugin syntax][plugin] and install the external LXC driver in the [plugin_dir][plugin_dir] prior to upgrading. See [plugin options][plugin-options] below for an example. Note the job specification remains the same.
2019-01-29 20:53:05 +00:00
## Task Configuration
```hcl
task "busybox" {
driver = "lxc"
config {
log_level = "trace"
verbosity = "verbose"
template = "/usr/share/lxc/templates/lxc-busybox"
2019-11-11 13:51:30 +00:00
template_args = []
# these optional values can be set in the template
distro = ""
release = ""
arch = ""
image_variant = "default"
image_server = "images.linuxcontainers.org"
gpg_key_id = ""
gpg_key_server = ""
disable_gpg = false
flush_cache = false
force_cache = false
2019-01-29 20:53:05 +00:00
}
}
```
The `lxc` driver supports the following configuration in the job spec:
2020-02-06 23:45:31 +00:00
- `template` - The LXC template to run.
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
```hcl
config {
template = "/usr/share/lxc/templates/lxc-alpine"
}
```
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `template_args` - A list of argument strings to pass into the template.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `log_level` - (Optional) LXC library's logging level. Defaults to `error`.
2019-01-29 20:53:05 +00:00
Must be one of `trace`, `debug`, `info`, `warn`, or `error`.
2020-02-06 23:45:31 +00:00
```hcl
config {
log_level = "debug"
}
```
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `verbosity` - (Optional) Enables extra verbosity in the LXC library's
2019-01-29 20:53:05 +00:00
logging. Defaults to `quiet`. Must be one of `quiet` or `verbose`.
2020-02-06 23:45:31 +00:00
```hcl
config {
verbosity = "quiet"
}
```
2019-01-29 20:53:05 +00:00
2020-10-15 13:53:25 +00:00
- `volumes` - (Optional) A list of `host_path:container_path` strings to
2020-10-16 15:40:06 +00:00
bind-mount host paths to container paths. Mounting host paths outside of the
[allocation working directory] is allowed by default. You can prevent
mounting host paths outside of the [allocation working directory] on
individual clients by setting the [`volumes_enabled`](#volumes_enabled)
2020-10-16 16:55:45 +00:00
option to `false` in the client's configuration
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
~> **Note:** Unlike the similar option for the docker driver, this
option must not have an absolute path as the `container_path`
component. This will cause an error when submitting a job.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
Setting this does not affect the standard bind-mounts of `alloc`,
`local`, and `secrets`, which are always created.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
```hcl
config {
volumes = [
# Use absolute paths to mount arbitrary paths on the host
"/path/on/host:path/in/container",
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
# Use relative paths to rebind paths already in the allocation dir
"relative/to/task:also/in/container"
]
}
```
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `release` - (Optional) The name/version of the distribution. By default this is set by the template.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `arch` - (Optional) The architecture of the container. By default this is set by the template.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `image_server` - (Optional) The hostname of the image server. Defaults to `images.linuxcontainers.org`.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `image_variant` - (Optional) The variant of the image. Defaults to `default` or as set by the template.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `disable_gpg` - (Optional) Disable GPG validation of images. Defaults to `false`, and enabling this flag is not recommended.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `flush_cache` - (Optional) Flush the local copy of the image (if present) and force it to be fetched from the image server. Defaults to `false`.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `force_cache` - (Optional) Force the use of the local copy even if expired. Defaults to `false`.
2019-11-11 13:51:30 +00:00
2020-02-06 23:45:31 +00:00
- `gpg_key_server`: GPG key server used for checking image signatures. Default is set by the underlying LXC library.
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `gpg_key_id`: GPG key ID used for checking image signatures. Default is set by the underlying LXC library.
2019-01-29 20:53:05 +00:00
## Networking
Currently the `lxc` driver only supports host networking. See the `none`
networking type in the `lxc.container.conf` [manual][lxc_man] for more
information.
## Client Requirements
The `lxc` driver requires the following:
2020-02-06 23:45:31 +00:00
- 64-bit Linux host
- The `linux_amd64` Nomad binary
- The LXC driver binary placed in the [plugin_dir][plugin_dir] directory.
- `liblxc` to be installed
- `lxc-templates` to be installed
2019-01-29 20:53:05 +00:00
2019-11-11 13:51:30 +00:00
## Plugin Options
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `enabled` - The `lxc` driver may be disabled on hosts by setting this option to `false` (defaults to `true`).
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `volumes_enabled`<a id="volumes_enabled"></a> - Specifies whether host can bind-mount host paths to container paths (defaults to `true`).
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `lxc_path` - The location in which all containers are stored (commonly defaults to `/var/lib/lxc`). See [`lxc-create`][lxc-create] for more details.
2019-11-11 13:51:30 +00:00
2023-01-30 14:48:43 +00:00
- `gc` block:
2020-02-06 23:45:31 +00:00
- `container` - Defaults to `true`. This option can be used to disable Nomad
from removing a container when the task exits. Under a name conflict,
Nomad may still remove the dead container.
2019-01-29 20:53:05 +00:00
An example of using these plugin options with the new [plugin
syntax][plugin] is shown below:
```hcl
plugin "nomad-driver-lxc" {
config {
enabled = true
volumes_enabled = true
lxc_path = "/var/lib/lxc"
2019-11-11 13:51:30 +00:00
gc {
container = false
}
2019-01-29 20:53:05 +00:00
}
}
```
2020-02-06 23:45:31 +00:00
2019-01-29 20:53:05 +00:00
Please note the plugin name should match whatever name you have specified for the external driver in the [plugin_dir][plugin_dir] directory.
## Client Configuration
2019-11-11 13:51:30 +00:00
-> Only use this section for pre-0.9 releases of Nomad. If you are using Nomad
2019-01-29 20:53:05 +00:00
0.9 or above, please see [plugin options][plugin-options]
2019-11-11 13:51:30 +00:00
The `lxc` driver has the following [client-level options][client_options]:
2019-01-29 20:53:05 +00:00
2020-02-06 23:45:31 +00:00
- `lxc.enable` - The `lxc` driver may be disabled on hosts by setting this
2019-01-29 20:53:05 +00:00
option to `false` (defaults to `true`).
## Client Attributes
The `lxc` driver will set the following client attributes:
2020-02-06 23:45:31 +00:00
- `driver.lxc` - Set to `1` if LXC is found and enabled on the host node.
- `driver.lxc.version` - Version of `lxc` e.g.: `1.1.0`.
2019-01-29 20:53:05 +00:00
## Resource Isolation
This driver supports CPU and memory isolation via the `lxc` library. Network
isolation is not supported as of now.
[lxc-create]: https://linuxcontainers.org/lxc/manpages/man1/lxc-create.1.html
[lxc-driver]: https://releases.hashicorp.com/nomad-driver-lxc
2023-01-25 17:31:14 +00:00
[lxc-guide]: /nomad/tutorials/plugins/plugin-lxc
2019-01-29 20:53:05 +00:00
[lxc_man]: https://linuxcontainers.org/lxc/manpages/man5/lxc.container.conf.5.html#lbAM
2023-01-25 17:31:14 +00:00
[plugin]: /nomad/docs/configuration/plugin
[plugin_dir]: /nomad/docs/configuration#plugin_dir
2020-01-03 20:57:48 +00:00
[plugin-options]: #plugin-options
2023-01-25 17:31:14 +00:00
[client_options]: /nomad/docs/configuration/client#options
[allocation working directory]: /nomad/docs/runtime/environment#task-directories 'Task Directories'