dhconfig configuration tool overview
Deephaven's dhconfig tool in /usr/illumon/latest/bin simplifies management of the various configurations and services of the system. It is the primary mechanism for managing configuration in Deephaven. This tool handles schema, data routing, properties, ACLs, service registry configuration, controller configuration, data import server, and table checkpoint files.
Note
In the text below, /usr/illumon/latest/bin/dhconfig is shortened to dhconfig for clarity, as if /usr/illumon/latest/bin has been added to the shell PATH with PATH=$PATH:/usr/illumon/latest/bin.
Usage
dhconfig \
[schemas|properties|routing|dis|checkpoint|serviceregistry|pq|acls] \
[import|export|list|delete|help|validate|add|show-claims|status|restart|stop|reload|check-repo|selection-provider|leader|users|groups|publickeys|rows|columns|inputtables] \
[arguments]
The first argument is a configuration data type:
The second argument is an action:
importexportlistdeletehelpvalidateaddshow-claimsstatusrestartstopreloadselection-providerleaderusersgroupspublickeysrowscolumnsinputtables
Note
The actions above are not valid for every command. See the documentation for each configuration data type for specifics.
Important
dhconfig is designed for easy exploration and provides detailed, context-sensitive help for every command and argument. Use dhconfig help to see top-level guidance, including available configuration types and common actions. For more specific information, use commands like dhconfig schemas help to get targeted usage details. All actions, types, and arguments support unambiguous prefixes (for example, dhconfig pro ex will be correctly interpreted as dhconfig properties export), and help messages always display the full canonical names.
Note
Where to run dhconfig:
Run dhconfig on a server where Deephaven is installed and you have access to the configuration server with appropriate authentication credentials.
For enterprise or production environments:
- Use a privileged account (such as
irisadmin) on a main Deephaven server - When using the
--etcdoption, ensure access to the necessary etcd client files (only supported on servers with both Deephaven and etcd access)
For single-node or test environments:
- Run
dhconfiglocally on the Deephaven node
Note: Running dhconfig from remote clients or desktops is not standard or supported unless they have the full Deephaven installation and required access credentials.
Some common options for the command follow. Note that not all arguments are applicable in all contexts.
| Argument | Description |
|---|---|
--etcd | If this argument is given, the command is executed directly against etcd. Authentication is done via file system permissions, and this is only suitable on certain nodes. If omitted, the command is executed through the configuration server. This is useful in contexts when the configuration server might not be running. |
--directory | This specifies an input or output directory where files will be located. It may be included multiple times in some contexts. |
--file | This identifies input files or data items to be included. It may be included multiple times in most contexts. Most commands treat trailing arguments as --file arguments. |
--force | This indicates that data should be overwritten. In most cases, if a file already exists, it won't be updated unless this flag is included. This option can be used to override certain errors. |
--verbose | Print some progress messages to stdout, and the full text of exceptions. |
--help | This produces a usage message with detail appropriate to the configuration data type and command if given. |
All commands have more specific options. Detailed usage is provided when the --help argument is given or if the arguments are incomplete or invalid.
Logging
The dhconfig script creates a log file in /var/log/deephaven/misc if the current user has write permission there, and in /tmp if not. Actions are logged to the AuditEventLog table.
Authentication
All commands support a common authentication framework.
Operations like export, list, and validate that do not change the system configuration can be used without authentication. These operations are read-only and allow users to inspect the current configuration without requiring elevated privileges.
However, if authentication options such as --user, --pwfile, or --key are provided during these operations, they are validated regardless of whether authentication is necessary. This ensures that any provided credentials are correct and align with the system's authentication framework, even for non-modifying actions.
Actions that modify configuration—such as import, add, and delete—require authentication with sudo, --key, or --user.
If --etcd is specified, authentication is implied by file system permissions and the authentication arguments do not apply. You must run dhconfig as a privileged user when using --etcd.
| Authentication Argument | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| --user | Authentication uses the Deephaven username specified with --user. After entering the command, you will be prompted interactively to enter the password for that user. The operation is then authorized based on the groups and permissions associated with the specified Deephaven user. |
| --user and --pwfile | Authentication uses the Deephaven user and password file specified.* | |
| --key | This specifies a private key file identifying the user. The user running the dhconfig command must have read permission on the key file. The default value is taken from the property AuthenticationClientManager.defaultPrivateKeyFile. |
Important
You can create a password file with this command: echo -n "your-password" | base64 > password.txt.
Be sure to protect the file with appropriate filesystem permissions.
For example, you can make the file readable only by your user with:
chmod 600 password.txt
As a convenience, dhconfig attempts to use the default iris private key file if it is readable. Executing with sudo or sudo -u irisadmin automatically authenticates by setting -DAuthenticationClientManager.defaultPrivateKeyFile=/etc/sysconfig/illumon.d/auth/priv-iris.base64.txt.
Editing configuration
The properties, routing, dis, and schemas data types support direct editing in versions 20250219 and later. The edit commands require authentication.
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig properties edit iris-environment.prop
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig dis edit dis-kafka
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig routing edit
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig schema edit LearnDeephaven.Orders
The default editor is /bin/vi. You can specify a different editor with the --editor command line argument, or by setting environment variable EDITOR.
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig properties edit iris-environment.prop --editor /usr/bin/emacs
sudo -u irisadmin EDITOR=/usr/bin/emacs /usr/illumon/latest/bin/dhconfig properties edit iris-environment.prop
The command will ask for confirmation after you save changes to the file. All validation performed by the import commands also applies when editing. If validation fails, you will have the chance to edit again.
Editing configuration without edit
If the edit commands are not available, or you choose not to use them, you must export, edit, and import configuration items.
Properties
The following commands edit iris-environment.prop:
/usr/illumon/latest/bin/dhconfig properties export iris-environment.prop --directory /tmp
vi /tmp/iris-environment.prop
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig properties import /tmp/iris-environment.prop
Data routing
The following commands edit the data routing configuration:
/usr/illumon/latest/bin/dhconfig routing export /tmp/routing.yml
vi /tmp/routing.yml
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig routing import /tmp/routing.yml
Data Import Servers
The following commands edit some or all of the DIS configurations. Specify which configurations to include in the exported file, or export them all. See dhconfig dis for more command line options.
/usr/illumon/latest/bin/dhconfig dis export dis-kafka --directory /tmp
vi /tmp/dis-kafka.yml
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig dis import /tmp/dis-kafka.yml --force
Schemas
The following commands edit schema ExampleNamespace.ExampleTable:
/usr/illumon/latest/bin/dhconfig schema export ExampleNamespace.ExampleTable --directory /tmp
vi /tmp/ExampleNamespace.ExampleTable.schema
sudo -u irisadmin /usr/illumon/latest/bin/dhconfig schema import /tmp/ExampleNamespace.ExampleTable.schema --force