iris_exec command-line utility

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

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, and their options are documented elsewhere.

Syntax

• <process name | Java class> is either one of the 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.
• -- 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 to find where a property is set. The sudo -u prefix selects the operating system account, as described in Accounts and permissions:

Launch options

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

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

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 define. See OS users and groups for details.

The account determines the workspace directory that iris_exec uses:

The iris_exec section of the system-managed 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 describes the variables and JVM arguments that launch reads:

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 directory and the process.name value that iris_exec passes to launch.

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:

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 named processes

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

The importer and schema creator pages in the Data guide 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. 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:

The class must be on the 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.

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

Related documentation

• Java process launch configuration
• Property Inspector
• Run scripts on Deephaven Enterprise workers
• Running local command line scripts (Legacy)
• Batch data import
• hostconfig
• OS users and groups
• Install custom libraries
• Process startup troubleshooting