---
layout: docs
page_title: Raw Fork/Exec task driver
description: Nomad's Raw Exec task driver lets you execute commands with no resource isolation. Learn how to use the Raw Fork/Exec task driver in your jobs. Configure the command to execute, command arguments, cgroup overrides, work directory, and out-of-memory (OOM) behavior. Review the Isolated Fork/Exec task driver capabilities, plugin options, client requirements, and client attributes.
---

# Raw Fork/Exec task 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

```hcl
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`](/nomad/docs/job-specification/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](/nomad/docs/runtime/interpolation) 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.

~> On Linux, you cannot set the `task.user` field on a task using the `raw_exec`
driver if you have hardened the Nomad client according to the
[production][hardening] guide. On Windows, when Nomad is running as a [system
service][service], you may specify a less-privileged service user. For example,
`NT AUTHORITY\LocalService`, `NT AUTHORITY\NetworkService`.

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

- `denied_envvars` - (Optional) Passes a list of environment variables that
  the driver should scrub from the task environment. Supports globbing, with "*"
  wildcard accepted as prefix and/or suffix.

## 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`](/nomad/docs/job-specification/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](/nomad/docs/concepts/plugins/task-drivers#capabilities-capabilities-error).

| 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.

```hcl
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.

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

- `denied_envvars` - (Optional) Passes a list of environment variables that
  the driver should scrub from all task environments. Supports globbing with "*"
  wildcard accepted as prefix and/or suffix.

```hcl
config {
  denied_envvars = ["AWS_SECRET_KEY", "*_TOKEN"]
}
```
## Client Options

~> Note: client configuration options will soon be deprecated. Please use
[plugin options][plugin-options] instead. See the [plugin block][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`.

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

[hardening]: /nomad/docs/install/production/requirements#user-permissions
[service]: /nomad/docs/install/windows-service
[plugin-options]: #plugin-options
[plugin-block]: /nomad/docs/configuration/plugin
