Raw Fork/Exec Driver

Name: raw_exec

The raw_exec driver is used to execute a command for a task without any isolation. Further, the task is started as the same user as the Nomad process. As such, it should be used with extreme care and is disabled by default.

Task Configuration

task "webservice" {
  driver = "raw_exec"

  config {
    command = "my-binary"
    args    = ["-flag", "1"]
  }
}

The raw_exec driver supports the following configuration in the job spec:

command - The command to execute. Must be provided. If executing a binary that exists on the host, the path must be absolute. If executing a binary that is downloaded from an artifact, the path can be relative from the allocation's root directory.
args - (Optional) A list of arguments to the command. References to environment variables or any interpretable Nomad variables will be interpreted before launching the task.
cgroup_v1_override - (Optional) A map of controller names to paths. The task will be added to these cgroups. The task will fail if these cgroups do not exist. WARNING: May conflict with other Nomad driver's cgroups and have unintended side effects.
cgroup_v2_override - (Optional) Adds the task to a unified cgroup path. Paths may be relative to the cgroupfs root or absolute. WARNING: May conflict with other Nomad driver's cgroups and have unintended side effects.

The task.user field cannot be set on a Task using the raw_exec driver if the Nomad client has been hardened according to the production guide.

oom_score_adj - (Optional) A positive integer to indicate the likelihood of the task being OOM killed (valid only for Linux). Defaults to 0.
work_dir - (Optional) Sets a custom working directory for the task. This must be an absolute path. This will also change the working directory when using nomad alloc exec.

Examples

To run a binary present on the Node:

task "example" {
  driver = "raw_exec"
 
  config {
    # When running a binary that exists on the host, the path must be absolute/
    command = "/bin/sleep"
    args    = ["1"]
  }
}

To execute a binary downloaded from an artifact:

task "example" {
  driver = "raw_exec"
 
  config {
    command = "name-of-my-binary"
  }
 
  artifact {
    source = "https://internal.file.server/name-of-my-binary"
    options {
      checksum = "sha256:abd123445ds4555555555"
    }
  }
}

Capabilities

The raw_exec driver implements the following capabilities.

Feature	Implementation
`nomad alloc signal`	true
`nomad alloc exec`	true
filesystem isolation	none
network isolation	host, group
volume mounting	none

Client Requirements

The raw_exec driver can run on all supported operating systems. For security reasons, it is disabled by default. To enable raw exec, the Nomad client configuration must explicitly enable the raw_exec driver in the plugin's options:

plugin "raw_exec" {
  config {
    enabled = true
  }
}

Nomad versions before v0.9 use the following client configuration. This configuration is also supported in Nomad v0.9.0, but is deprecated in favor of the plugin block:

client {
  options = {
    "driver.raw_exec.enable" = "1"
  }
}

Plugin Options

enabled - Specifies whether the driver should be enabled or disabled. Defaults to false.
denied_host_uids - (Optional) Specifies a comma-separated list of host uids to deny. Ranges can be specified by using a hyphen separating the two inclusive ends. If a "user" value is specified in task configuration and that user has a user id in the given ranges, the task will error before starting. This will not be checked on Windows clients.

config {
  denied_host_uids = "0,10-15,22"
}

denied_host_gids - (Optional) Specifies a comma-separated list of host gids to deny. Ranges can be specified by using a hyphen separating the two inclusive ends. If a "user" value is specified in task configuration and that user is part of any groups with gid's in the specified ranges, the task will error before starting. This will not be checked on Windows clients.

config {
  denied_host_gids = "2,4-8"
}

Client Options

Note: client configuration options will soon be deprecated. Please use plugin options instead. See the plugin block documentation for more information.

driver.raw_exec.enable - Specifies whether the driver should be enabled or disabled. Defaults to false.

Client Attributes

The raw_exec driver will set the following client attributes:

driver.raw_exec - This will be set to "1", indicating the driver is available.

Resource Isolation

The raw_exec driver provides no filesystem isolation.

If the launched process creates a new process group, it is possible that Nomad will leak processes on shutdown unless the application forwards signals properly. Nomad will not leak any processes if cgroups are being used to manage the process tree. Cgroups are used on Linux when Nomad is being run with appropriate privileges, and the cgroup system is mounted.

If the cluster is configured with memory oversubscription enabled, a task using the raw_exec driver can be configured to have no maximum memory limit by setting memory_max = -1.

resources {
  cpu        = 500
  memory     = 128
  memory_max = -1 # no limit
}