Deephaven properties overview

Which file to use, how files relate, and where to put your settings.

Properties files are text files, usually named with a .prop extension, that store key-value pairs. They configure most variable operations and the behavior of a Java process.

There are four main properties files in a typical Deephaven installation:

iris-common.prop — the "root" properties file, which includes other property files.
iris-environment.prop — contains the majority of installation-specific settings.
iris-endpoints.prop — defines server names, addresses, and ports for Deephaven services. This is generated by the installer and should not be manually updated.
iris-defaults.prop — defines common settings needed for all Deephaven installations. This file is replaced on upgrade; override settings in iris-environment.prop instead.

Which prop file to use

Deephaven uses multiple properties files that work together in a hierarchy. The following table shows which file to use for different types of settings:

Setting Type	File	Notes
Customer-specific settings	`iris-environment.prop`	Your customizations go here. Persists through upgrades.
Core+ worker settings	`coreplus-environment.prop`	Settings specific to Core+ workers.
Service endpoints	`iris-endpoints.prop`	DO NOT EDIT — auto-generated by installer.
Deephaven defaults	`iris-defaults.prop`	DO NOT EDIT — replaced on upgrade.
Core+ defaults	`coreplus-defaults.prop`	DO NOT EDIT — replaced on upgrade.

Important

Only edit iris-environment.prop (for Enterprise settings) or coreplus-environment.prop (for Core+ worker settings). Other files are either auto-generated or replaced during upgrades.

Common scenarios

Where do I set heap sizes?

For system processes (DIS, controller, dispatcher): Set in hostconfig using the EXTRA_ARGS variable.

For worker heap limits: Set RemoteQueryDispatcher.maxTotalQueryProcessorHeapMB and related properties in iris-environment.prop. See Worker heap size configuration.

Where do I configure LDAP?

Set LDAP properties in iris-environment.prop within the [service.name=authentication_server] stanza:

[service.name=authentication_server] {
    authentication.server.ldap.enabled=true
    authentication.server.ldap.hosts=ldap.example.com
    # ... other LDAP settings
}

See Configuring users with LDAP for complete details.

Where do I configure CORS?

Set CORS properties in iris-environment.prop:

cors.allowedOrigins=https://deephaven-prod.example.com:8000

See CORS configuration for details.

Where do I change ports?

Don't. Service ports are defined in iris-endpoints.prop, which is auto-generated by the installer. Manual changes will be overwritten during the next upgrade. If you need to change ports, re-run the installer with the appropriate configuration.

Where do I set Core+ worker properties?

Set Core+ worker properties in coreplus-environment.prop. See Core+ properties below.

Prop file precedence

Properties files include other files and override settings in a specific order. Later files override earlier ones.

Enterprise processes

iris-common.prop (root)
  └── includefiles: iris-defaults.prop, iris-environment.prop, iris-endpoints.prop
      │
      ├── iris-defaults.prop      (Deephaven defaults - DO NOT EDIT)
      ├── iris-environment.prop   (your customizations ✓)
      └── iris-endpoints.prop     (auto-generated - DO NOT EDIT)

Settings in iris-environment.prop override those in iris-defaults.prop.

Core+ workers

Core+ workers use a separate property file chain:

coreplus-common.prop (root for Core+ workers)
  └── includefiles: iris-defaults.prop, iris-endpoints.prop, coreplus-defaults.prop, coreplus-environment.prop
      │
      ├── iris-defaults.prop           (Enterprise defaults)
      ├── iris-endpoints.prop          (auto-generated endpoints)
      ├── coreplus-defaults.prop       (Core+ defaults - DO NOT EDIT)
      └── coreplus-environment.prop    (your Core+ customizations ✓)

Settings in coreplus-environment.prop override those in coreplus-defaults.prop, which override iris-defaults.prop.

Core+ properties

Core+ workers run using Deephaven Community Core embedded in Enterprise. They have their own property files with settings specific to Core+ behavior.

Core+ property files

File	Purpose
`coreplus-common.prop`	Root file for Core+ workers. Includes other files.
`coreplus-defaults.prop`	Default settings for Core+ workers. Replaced on upgrade.
`coreplus-environment.prop`	Your Core+ customizations. Persists through upgrades.

Key Core+ properties

The following properties are specific to Core+ workers or have different defaults than Enterprise:

Property	Default	Description
`SessionMonitor.noSessionsTimeoutMillis`	`3000`	Terminate worker after losing all sessions (ms).
`http.session.durationMs`	`75000`	Session token duration (75s, vs 5min in Enterprise).
`AuthHandlers`	`io.deephaven.enterprise.dnd.authentication.DheAuthenticationHandler`	Authentication handler class.
`http.add.header.*.enabled`	varies	Security headers (X-Frame-Options, CSP, etc.).

Scoping by worker type

You can scope properties by worker type using the worker.type property:

[worker.type=DeephavenCommunity] {
    # Settings for standard Core+ workers
    property.name=value
}

[worker.type=CustomWorkerKind] {
    # Settings for custom worker types
    property.name=other_value
}

Main properties files

iris-common.prop

The root properties file. It includes the other property files in a specific order:

includefiles=iris-defaults.prop,iris-environment.prop,iris-endpoints.prop

iris-environment.prop

Contains customer-specific settings. This is the primary file for your customizations. Settings here override those in iris-defaults.prop.

Use scoped stanzas to apply settings to specific services:

[service.name=authentication_server] {
    authentication.server.ldap.enabled=true
}

[service.name=iris_controller] {
    PersistentQueryController.maxInboundMessageSizeMiB=128
}

iris-endpoints.prop

Defines server names, addresses, and ports for Deephaven services. This file is generated by the installer and should not be manually edited — changes are overwritten during upgrades.

iris-defaults.prop

Contains default settings for all Deephaven installations. This file is replaced during upgrades. Do not edit it directly; instead, override specific properties in iris-environment.prop.

Properties file locations

Properties files are stored in etcd and accessed via the Configuration Server. On a Deephaven server, any properties files on disk are just for reference and are not authoritative.

The set of files synchronized to clients using the Deephaven Updater includes a current snapshot of the properties files stored in etcd.

Deephaven properties file format

Deephaven properties files have several important extensions: the ability to include other properties files, scoped blocks, and finalization. See Deephaven properties files for complete details.

Changing a properties file

To change a properties file stored in etcd and managed by the Configuration Server, you must edit it directly with dhconfig properties edit or import the file after changing it with dhconfig properties import.

System properties

Properties can be passed to a Java process on the command line. These properties are set before any properties files are loaded. Some properties, such as those governing the actual start-up process, must be set this way:

the name of the properties file to load
scope defining properties — service.name, process.name
properties used to connect to the Configuration Server

Deephaven processes use a global Configuration object for properties. This Configuration includes all system properties, but system properties do not include the Configuration properties (e.g., System.getProperty("prop.name")).

See Java process launch for details about how Deephaven processes are started, including system properties, JVM arguments, and environment variables.