nomad/website/content/docs/job-declare/task-driver/java.mdx

---
layout: docs
page_title: Use the Java task driver in a job
description: Nomad's Java task driver lets you run JAR files in your workloads. Learn how to configure a job task that uses the Java task driver. Configure paths, JAR args, JVM options, namespace isolation, work directory, and Linux capabilities.
---

# Use the Java task driver in a job

Name: `java`

The `java` driver is used to execute Java applications packaged into a Java Jar
file. The driver requires the Jar file to be accessible from the Nomad
client via the [`artifact` downloader](/nomad/docs/job-specification/artifact).

Refer to [Configure the Java task driver](/nomad/docs/deploy/task-driver/java)
for capabilities, client requirements, and plugin configuration.

## Task Configuration

```hcl
task "webservice" {
  driver = "java"

  config {
    jar_path    = "local/example.jar"
    jvm_options = ["-Xmx2048m", "-Xms256m"]
  }
}
```

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

- `class` - (Optional) The name of the class to run. If `jar_path` is specified
  and the manifest specifies a main class, this is optional. If shipping classes
  rather than a Jar, please specify the class to run and the `class_path`.

- `class_path` - (Optional) The `class_path` specifies the class path used by
  Java to lookup classes and Jars.

- `jar_path` - (Optional) The path to the downloaded Jar. In most cases this will just be
  the name of the Jar. However, if the supplied artifact is an archive that
  contains the Jar in a subfolder, the path will need to be the relative path
  (`subdir/from_archive/my.jar`).

- `args` - (Optional) A list of arguments to the Jar's main method. References
  to environment variables or any [interpretable Nomad
  variables](/nomad/docs/reference/runtime-variable-interpolation) will be interpreted before
  launching the task.

- `jvm_options` - (Optional) A list of JVM options to be passed while invoking
  java. These options are passed without being validated in any way by Nomad.

- `pid_mode` - (Optional) Set to `"private"` to enable PID namespace isolation for
  this task, or `"host"` to disable isolation. If left unset, the behavior is
  determined from the [`default_pid_mode`][default_pid_mode] in plugin configuration.

!> **Warning:** If set to `"host"`, other processes running as the same user will
be able to access sensitive process information like environment variables.

- `ipc_mode` - (Optional) Set to `"private"` to enable IPC namespace isolation for
  this task, or `"host"` to disable isolation. If left unset, the behavior is
  determined from the [`default_ipc_mode`][default_ipc_mode] in plugin configuration.

!> **Warning:** If set to `"host"`, other processes running as the same user will be
able to make use of IPC features, like sending unexpected POSIX signals.

- `cap_add` - (Optional) A list of Linux capabilities to enable for the task.
  Effective capabilities (computed from `cap_add` and `cap_drop`) must be a
  subset of the allowed capabilities configured with [`allow_caps`][allow_caps].
  Note that `"all"` is not permitted here if the `allow_caps` field in the
  driver configuration doesn't also allow all capabilities.


```hcl
config {
  cap_add = ["net_raw", "sys_time"]
}
```

- `cap_drop` - (Optional) A list of Linux capabilities to disable for the task.
  Effective capabilities (computed from `cap_add` and `cap_drop`) must be a subset
  of the allowed capabilities configured with [`allow_caps`][allow_caps].

```hcl
config {
  cap_drop = ["all"]
  cap_add  = ["chown", "sys_chroot", "mknod"]
}
```

- `work_dir` - (Optional) Sets a custom working directory for the task. This path must be
  absolute and within the task's [chroot](/nomad/docs/deploy/task-driver/java#chroot) or in a [host volume][] mounted
  with a [`volume_mount`][volume_mount] block. This will also change the working
  directory when using `nomad alloc exec`.

## Examples

A simple config block to run a Java Jar:

```hcl
task "web" {
  driver = "java"

  config {
    jar_path    = "local/hello.jar"
    jvm_options = ["-Xmx2048m", "-Xms256m"]
  }

  # Specifying an artifact is required with the "java" driver. This is the
  # mechanism to ship the Jar to be run.
  artifact {
    source = "https://internal.file.server/hello.jar"

    options {
      checksum = "md5:123445555555555"
    }
  }
}
```

A simple config block to run a Java class:

```hcl
task "web" {
  driver = "java"

  config {
    class       = "Hello"
    class_path  = "${NOMAD_TASK_DIR}"
    jvm_options = ["-Xmx2048m", "-Xms256m"]
  }

  # Specifying an artifact is required with the "java" driver. This is the
  # mechanism to ship the Jar to be run.
  artifact {
    source = "https://internal.file.server/Hello.class"

    options {
      checksum = "md5:123445555555555"
    }
  }
}
```

[default_pid_mode]: /nomad/docs/deploy/task-driver/java#default_pid_mode
[default_ipc_mode]: /nomad/docs/deploy/task-driver/java#default_ipc_mode
[cap_add]: /nomad/docs/deploy/task-driver/java#cap_add
[cap_drop]: /nomad/docs/deploy/task-driver/java#cap_drop
[no_net_raw]: /nomad/docs/upgrade/upgrade-specific#nomad-1-1-0-rc1-1-0-5-0-12-12
[allow_caps]: /nomad/docs/deploy/task-driver/java#allow_caps
[docker_caps]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
[cgroup controller requirements]: /nomad/docs/deploy/production/requirements#hardening-nomad
[volume_mount]: /nomad/docs/job-specification/volume_mount
[host volume]: /nomad/docs/configuration/client#host_volume-block