OS users and groups

This page describes the operating system users and groups that Deephaven Enterprise uses to run its services. These accounts enforce separation of privileges between administrative, data-writing, and data-reading processes.

All user and group names are configurable via cluster.cnf during installation. The installer creates any missing accounts automatically.

Overview

Deephaven uses a layered approach to OS-level security:

• Three primary service accounts run different classes of Deephaven processes, each with distinct filesystem permissions.
• Two shared groups enable controlled file sharing between service accounts and, optionally, end users.
• Three private groups provide per-account isolation when needed.
• Infrastructure accounts run supporting services like Monit and Etcd.
• An installer service account handles installation and maintenance via SSH.

Primary service accounts

These three accounts run all Deephaven services. Each is designed with specific access levels to enforce the principle of least privilege.

DH_ADMIN_USER

The administrative service account runs privileged services that manage the Deephaven cluster:

• Configuration Server
• Authentication Server
• Persistent Query Controller
• ACL Write Server
• Web API Service
• Status Dashboard

Security considerations:

• This account has access to cluster secrets, including TLS private keys and authentication configuration.
• Restrict access to this account to trusted system administrators only.
• Never allow user code execution as DH_ADMIN_USER.

Sudoers requirements:

Both DH_SSH_USER and DH_MONIT_USER must be able to run commands as DH_ADMIN_USER:DH_ADMIN_GROUP.

DH_MERGE_USER

The merge service account runs processes with write access to historical table data:

• Merge dispatchers (read-write Remote Query Dispatchers)
• Batch import processes (CSV, JDBC, Parquet importers)
• Any Persistent Query or worker that must write to /db/Systems/ or /db/Namespace/ locations

Security considerations:

• This account can modify or delete historical data.
• Restrict Deephaven user access to trusted users who are members of iris-data* ACL special groups.
• Never set DH_MERGE_USER equal to DH_ADMIN_USER or DH_MONIT_USER — doing so would grant administrative privileges to any user allowed to run code on the merge server.

Sudoers requirements:

Both DH_SSH_USER and DH_MONIT_USER must be able to run commands as DH_MERGE_USER:DH_MERGE_GROUP.

DH_QUERY_USER

The query service account runs processes with read-only access to table data:

• Query dispatchers (read-only Remote Query Dispatchers)
• Interactive console workers
• Most Persistent Queries that do not require write access to historical data

Security considerations:

• This account cannot modify historical data, but can access all data readable by DH_SHARED_GROUP.
• Users may optionally have write access to user tables via Deephaven ACLs.
• Never set DH_QUERY_USER equal to DH_ADMIN_USER or DH_MONIT_USER.

Sudoers requirements:

Both DH_SSH_USER and DH_MONIT_USER must be able to run commands as DH_QUERY_USER:DH_QUERY_GROUP.

Shared groups

Shared groups enable controlled file sharing between service accounts.

DH_SHARED_GROUP

The primary shared group for all Deephaven service accounts. All three primary service accounts (DH_ADMIN_USER, DH_MERGE_USER, and DH_QUERY_USER) have this as their primary group.

Purpose:

• Files created by any Deephaven service are group-owned by DH_SHARED_GROUP, making them accessible to all Deephaven processes.
• Directories under /db/ (historical data, intraday data, system tables) typically have group ownership of DH_SHARED_GROUP.
• Enables merge processes to write data that query processes can read.

Group membership:

DH_SHARED_QUERY_GROUP

A secondary shared group for broader access to Deephaven resources. This group allows non-service-account OS users to run Deephaven workers and access shared resources.

Purpose:

• Enables per-user workers — OS users outside the three primary service accounts can start Deephaven sessions.
• Files that should be accessible to all Deephaven users (including end users running their own workers) can be group-owned by DH_SHARED_QUERY_GROUP.

Group membership:

All three primary service accounts have secondary membership in DH_SHARED_QUERY_GROUP. You may add additional OS users to this group to grant them the ability to run Deephaven workers.

Private groups

Each primary service account has a private group for files that should only be accessible to that specific account.

DH_ADMIN_GROUP

The private group for DH_ADMIN_USER. Used for files that only administrative processes should access, such as:

• TLS private keys
• Authentication secrets
• Etcd client credentials

DH_MERGE_GROUP

The private group for DH_MERGE_USER. Processes run with DH_SHARED_GROUP as the effective group, so files created by merge processes are accessible to other Deephaven services.

DH_QUERY_GROUP

The private group for DH_QUERY_USER. Similar to DH_MERGE_GROUP, this exists primarily for account isolation rather than file ownership.

Infrastructure accounts

DH_MONIT_USER and DH_MONIT_GROUP

The Monit account runs the Monit process manager, which is responsible for:

• Starting Deephaven services at system boot
• Monitoring service health
• Restarting failed services automatically

Sudoers requirements:

DH_MONIT_USER must be able to sudo as all three primary service accounts:

• DH_ADMIN_USER:DH_ADMIN_GROUP
• DH_MERGE_USER:DH_MERGE_GROUP
• DH_QUERY_USER:DH_QUERY_GROUP

By default, DH_MONIT_USER is the same as DH_ADMIN_USER (irisadmin). This simplifies sudoers configuration while maintaining security — Monit itself does not execute user code.

Related settings:

DH_ETCD_USER

The account that runs the Etcd service on native installations. Etcd stores all cluster configuration, ACLs, and runtime state.

File ownership:

• Etcd server secrets: /etc/etcd/dh and /var/lib/etcd are owned by DH_ETCD_USER
• Etcd client secrets: owned by DH_ADMIN_USER, with group access via DH_ADMIN_GROUP

Installer service account

DH_SSH_USER

The service account used by the installer for SSH access to Deephaven servers during installation and maintenance. This account:

• Copies installation files to remote machines
• Runs installation scripts via SSH
• Must have sudoers permission to act as all primary service accounts

Security considerations:

• DH_SSH_USER is not used after installation completes — it only performs installation and upgrade tasks.
• Consider using a dedicated service account rather than a personal user account.
• SSH keys for this account should be carefully protected.

Sudoers requirements:

DH_SSH_USER must be able to sudo as:

• DH_ADMIN_USER:DH_ADMIN_GROUP
• DH_MERGE_USER:DH_MERGE_GROUP
• DH_QUERY_USER:DH_QUERY_GROUP
• DH_MONIT_USER:DH_MONIT_GROUP (if different from DH_ADMIN_USER)

Related settings:

Group membership summary

The following table summarizes group membership for all service accounts:

To verify group membership for any account, run:

Customizing user and group names

All user and group names can be customized in your cluster.cnf file before installation. See Custom user accounts for the complete list of configurable variables.

Example custom configuration:

Related documentation

• Custom user accounts
• Deephaven service accounts
• Basic installation
• Sudoers configuration
• Per-user workers
• Hardening Technical Controls