---
title: iris_exec command-line utility
---

> [!NOTE]
> The `hostconfig`, `sudo -u` account, and workspace behavior on this page applies to [traditional installations](../installation/basic-install.md). In Kubernetes, the management shell pod has no `hostconfig`. Set `WORKSPACE`, `CONFIGFILE`, and `DEVROOT` as environment variables if the deployment does not already supply them.

`iris_exec` runs a Deephaven Java command-line utility on a Deephaven server. It sets up the environment, classpath, and configuration that the Deephaven services use, then runs the requested utility in the foreground of the terminal. Deephaven uses `iris_exec` for the [Property Inspector](../../resources/faq/property-inspector.md), the Legacy batch importers and schema creators, and other administrative tasks.

`iris_exec` is installed at `/usr/illumon/latest/bin/iris_exec`. For an overview of how it relates to the other Deephaven launch scripts, see [Java process launch configuration](./java-process-launch.md).

This page documents `property_inspector`, `run_local_script`, and running any other Java class. The Legacy importers, schema creators, and `update_acl_db` are listed under [Legacy named processes](#legacy-named-processes), and their options are documented elsewhere.

## Syntax

```syntax
iris_exec <process name | Java class> [<launch options>] [-- <process arguments>]
```

- `<process name | Java class>` is either one of the [named processes](#named-processes) or the fully qualified name of a Java class with a `main` method. `iris_exec` treats any value that is not a named process as a class name.
- `<launch options>` control how `iris_exec` starts the Java process. See [Launch options](#launch-options).
- `--` separates the launch options from the arguments for the process itself. Use it before any process argument that starts with a dash, so that `iris_exec` does not parse the argument as a launch option. Everything after `--` is passed to the process unchanged.
- `iris_exec` does not support empty arguments (`""`). It drops the first empty argument and every argument after it.
- Quote any argument that contains spaces or shell metacharacters, such as `"SELECT *"`. The shell expands unquoted metacharacters before `iris_exec` starts.

Run `iris_exec` with no arguments to print the usage message and the list of named processes.

The following example uses the [Property Inspector](../../resources/faq/property-inspector.md) to find where a property is set. The `sudo -u` prefix selects the operating system account, as described in [Accounts and permissions](#accounts-and-permissions):

```bash
sudo -u irisadmin /usr/illumon/latest/bin/iris_exec property_inspector -- \
    -pf iris-environment.prop \
    -pn my.property.name
```

## Launch options

Launch options appear between the process name and `--`. The following options have an effect when used with `iris_exec`:

| Option           | Description                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-j <arg>`       | Adds a JVM argument, such as `-j -Xmx8g` or `-j -Dmy.property=value`. Repeat the option for each argument. After `--`, `-j` has a different meaning for `run_local_script`; see [run_local_script](#run_local_script).                                                                                                                                                                     |
| `-a <arg>`       | Adds one argument for the process. To pass several arguments, use `--` instead. Combining `-a` with arguments after `--` joins the `-a` value to the first argument after `--`, so avoid combining them.                                                                                                                                                                                   |
| `-p <path>`      | Directory, or comma-separated list of directories, of customer JAR files to add to the classpath. Overrides `CUSTOMER_JAR_DIR`.                                                                                                                                                                                                                                                            |
| `-C <path>`      | Prefix to add to the front of the classpath.                                                                                                                                                                                                                                                                                                                                               |
| `-f <file>`      | Properties file that the process loads. Defaults to the `CONFIGFILE` value in the [`hostconfig`](./configuration-file-locations-overview.md#hostconfig) file.                                                                                                                                                                                                                              |
| `-w <directory>` | Workspace directory. Overrides the [default workspace](#accounts-and-permissions).                                                                                                                                                                                                                                                                                                         |
| `-d <directory>` | Root of the Deephaven installation (`DEVROOT`). Defaults to the installation that contains the `iris_exec` script.                                                                                                                                                                                                                                                                         |
| `-l <file>`      | Log4j configuration file.                                                                                                                                                                                                                                                                                                                                                                  |
| `-L <path>`      | Java executable to use, overriding the installation's default (`DH_JAVA`).                                                                                                                                                                                                                                                                                                                 |
| `-J <path>`      | Java home directory (`JAVA_HOME`). The JVM still comes from `DH_JAVA` when that is set, so use `-L` to change the JVM.                                                                                                                                                                                                                                                                     |
| `-A <name>`      | Prefix for log file names that [`launch`](./java-process-launch.md#process-launch) derives, typically under `<workspace>/../logs`, such as GC logs and `hs_err` files. Defaults to `java`. A `-j -DlogDir=<dir>` argument or a mounted `/srv/ramdisk` changes where some of these files go. It does not change the console output or the process name that `iris_exec` passes to `launch`. |
| `-e <32\|64>`    | Bitness of the JVM environment, passed through to `launch`. Defaults to `64`.                                                                                                                                                                                                                                                                                                              |
| `-m <file>`      | Additional master configuration file to source before launching. `iris_exec` always sources `/etc/sysconfig/illumon` first, when it exists. It sources this file after it creates the workspace directory, so the file cannot change which workspace directory `iris_exec` creates.                                                                                                        |
| `-D`             | Starts the JVM with a JDWP debug listener on the first free port from `9500`.                                                                                                                                                                                                                                                                                                              |
| `-v`             | Enables verbose garbage collection logging.                                                                                                                                                                                                                                                                                                                                                |
| `-q`             | Suppresses initialization information.                                                                                                                                                                                                                                                                                                                                                     |

The following behaviors also apply:

- Without `-f`, `iris_exec` uses `CONFIGFILE` from the `hostconfig` file, which is `iris-common.prop` by default. If `CONFIGFILE` is empty, it falls back to the `DEFAULT_CONFIGFILE` environment variable, and exits with an error if neither is set.
- **Ignored options:** `iris_exec` shares an option parser with the other launch scripts, so it also accepts `-o`, `-B`, `-u`, `-t`, `-r`, and `-s`. It does not pass these options on, so they have no effect.

## Accounts and permissions

Most utilities must run under a specific operating system account. Prefix the command with `sudo -u <account>`:

| Task                                      | Typical account                           |
| ----------------------------------------- | ----------------------------------------- |
| Data imports and merges                   | `dbmerge` (the `DH_MERGE_USER` account)   |
| `property_inspector` and other admin work | `irisadmin` (the `DH_ADMIN_USER` account) |

These are the default account names. An installation may use different names, which the `DH_ADMIN_USER`, `DH_MERGE_USER`, and `DH_QUERY_USER` variables in [`cluster.cnf`](../installation/cluster-config-guide.md) define. See [OS users and groups](../installation/os-users-and-groups.md) for details.

The account determines the workspace directory that `iris_exec` uses:

| Running as                                    | Workspace                               |
| --------------------------------------------- | --------------------------------------- |
| The merge, query, or admin account, or `root` | `/db/TempFiles/<user>/<process name>`   |
| Any other account                             | `${TMPDIR:-/tmp}/<user>/<process name>` |

The `iris_exec` section of the system-managed [`hostconfig`](./configuration-file-locations-overview.md#hostconfig) file defines this behavior, and upgrades overwrite that file. Make site-specific changes in the customer `hostconfig` file instead. A change to the `iris_exec` section applies to every process launched through `iris_exec`.

## Environment variables

`sudo` discards the current environment, so define environment variables after `sudo`. The [launch configuration](./java-process-launch.md#process-launch) describes the variables and JVM arguments that `launch` reads:

```bash
sudo -u irisadmin MY_ENV=my_value /usr/illumon/latest/bin/iris_exec property_inspector \
    -j -Dservice.name=dhctl -- -pf iris-environment.prop -pn my.property.name
```

The `hostconfig` file sets `CONFIGFILE` and `WORKSPACE` unconditionally, so a value defined after `sudo` does not survive. `DH_JAVA` comes from `cluster.cnf`, which `iris_exec` sources first, and falls back to the system JDK. Use `-f`, `-w`, or `-L` to override these values. To change other variables that `hostconfig` sets, edit the customer `hostconfig` file or source an additional file with `-m`.

## Named processes

`iris_exec` maps a few short names to Java classes, so `iris_exec property_inspector` and `iris_exec com.illumon.util.tools.PropertyInspector` launch the same Java class. They are not identical launches: the process name is the first argument, so it determines the default [workspace](#accounts-and-permissions) directory and the `process.name` value that `iris_exec` passes to `launch`.

| Process name         | Description                                                                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `property_inspector` | Shows which properties are set, where they are set, and where they are duplicated or overridden. See [Property Inspector](../../resources/faq/property-inspector.md). |
| `run_local_script`   | Runs a local script on a Legacy worker. For Core+ workers, use the separate [`run_local_script`](../../development/run-local-script.md) command instead.              |
| Legacy processes     | Importers, schema creators, and `update_acl_db`. See [Legacy named processes](#legacy-named-processes).                                                               |

### run_local_script

`iris_exec run_local_script` runs a local Groovy or Python script on a Legacy worker. The script file extension selects the language:

```syntax
iris_exec run_local_script [<launch options>] -- -s <script> [<options>] [<variable> <value> ...]
```

The `-j` option has a different effect on each side of `--`. Before `--`, it is an `iris_exec` launch option that sets a JVM argument for the local process that runs the utility. After `--`, it is a `run_local_script` option that sets a JVM argument for the remote worker that runs the script. For the options, see [Running local command line scripts (Legacy)](../../legacy/sys-admin/command-line.md).

### Legacy named processes

The remaining named processes run on the Legacy engine and do not apply to Core+. This page does not document their options:

| Category        | Process names                                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| Importers       | `csv_import`, `jdbc_import`, `xml_import`, `json_import`, `quandl_import`, `binary_import`, and `downsample_import`   |
| Schema creators | `csv_schema_creator`, `jdbc_schema_creator`, `xml_schema_creator`, `json_schema_creator`, and `quandl_schema_creator` |
| ACL management  | `update_acl_db`                                                                                                       |

The importer and schema creator pages in the [Data guide](../../data-guide/batch-data/batch-intro.md) document the importers and schema creators. `update_acl_db` updates the ACL database. Command-line CSV imports with `csv_import` are deprecated; see [CSV import](../../data-guide/batch-data/csv.md). Run `iris_exec` with no arguments to list every name that the installation recognizes.

## Run other Java classes

To run a class that has no short name, pass its fully qualified name. `iris_exec` sets up the same classpath and configuration that it provides to the named processes:

```bash
sudo -u irisadmin /usr/illumon/latest/bin/iris_exec com.example.MyTool -- --my-argument value
```

The class must be on the [classpath](./java-process-launch.md#classpath). The usual approach is to place its JAR files directly in `/etc/sysconfig/illumon.d/java_lib`, which `launch` always adds to the classpath. To add other directories, use the `-p` option or the `CUSTOMER_JAR_DIR` variable. `iris_exec` does not search subdirectories. Alternatively, use the `-C` option to add a classpath prefix. See [Install custom libraries](../installation/basic-install.md#install-custom-libraries).

## Troubleshooting

- **The process reports missing or unrecognized options.** Confirm that `--` separates the launch options from the process arguments, especially when an argument starts with a dash.
- **Arguments after an empty argument are missing.** Remove empty (`""`) arguments. `iris_exec` drops the first empty argument and everything after it.
- **A permission error appears when the process writes files.** Run the command under the account that the [accounts table](#accounts-and-permissions) recommends, or set a writable workspace with `-w`.
- **An environment variable has no effect.** Define the variable after `sudo`, as in the [environment variables example](#environment-variables), and use `-f`, `-w`, or `-L` for `CONFIGFILE`, `WORKSPACE`, or `DH_JAVA`.
- **A custom class is not found.** Confirm that its JAR file is directly inside `/etc/sysconfig/illumon.d/java_lib` or a directory that `CUSTOMER_JAR_DIR` or `-p` references, or add it to the classpath with `-C`.
- **The process fails during startup.** See [Process startup troubleshooting](../troubleshooting/process-startup-troubleshooting.md).

## Related documentation

- [Java process launch configuration](./java-process-launch.md)
- [Property Inspector](../../resources/faq/property-inspector.md)
- [Run scripts on Deephaven Enterprise workers](../../development/run-local-script.md)
- [Running local command line scripts (Legacy)](../../legacy/sys-admin/command-line.md)
- [Batch data import](../../data-guide/batch-data/batch-intro.md)
- [`hostconfig`](./configuration-file-locations-overview.md#hostconfig)
- [OS users and groups](../installation/os-users-and-groups.md)
- [Install custom libraries](../installation/basic-install.md#install-custom-libraries)
- [Process startup troubleshooting](../troubleshooting/process-startup-troubleshooting.md)