dhconfig ACLs

The acls configuration data type of the dhconfig tool is used to add, remove and modify system access controls such as users, passwords, keys, and row/column ACLs. Authentication is required for most acls actions.

Usage

Typical usage for the acls configuration data type is one of:

The first command is either a high-level ACL action (import or export) or an ACL subtype:

Command / SubtypeDescription
importImport ACLs from a file.
exportExport ACLs to a file.
usersManage users.
groupsManage groups.
publickeysManage public keys.
rowsManage row ACLs.
columnsManage column ACLs.
inputtablesManage input table ACLs.
helpShow help information.

Each subtype has its own set of actions and arguments. As with other dhconfig configuration data types, the --help action provides detailed information on the available options and arguments, as well as usage examples, at every level of the dhconfig acls command. For a list of all available subtypes, run:

Which prints the following:

For more information about a specific subtype - for example, users - you can run:

Which will return the following:

Finally, for more information about a specific action - for example, add - you can run:

Which will return the following:

A description of all the subcommand's options and some usage examples follows.

Due to the number of available options and combinations, an exhaustive list of all possible commands is not provided here. Instead, this guide presents some usage examples and recommends that you use the --help option as needed for more information.

Common options

In addition to the common dhconfig options, every acls action and subcommand accepts the following option:

OptionDescription
--directRead and write directly to the backing ACL store instead of going through the ACL write service. Use this when the ACL write service is not running, for example, during installation or recovery. Authentication is implied by file system permissions, so you must run dhconfig as a privileged user (such as irisadmin). The --user and --key authentication options do not apply. For the users, groups, publickeys, rows, columns, and inputtables actions, dhconfig rejects --user when --direct is set. The import action does not reject it, but authentication is not used.

The --etcd option has the same effect as --direct for acls commands, but dhconfig prints a warning recommending --direct instead.

The acls commands accept --diskprops but ignore it. They read properties through the standard configuration path, or directly from etcd when --direct or --etcd is set.

The list subcommands and export do not require authentication, but they do need sufficient file-system permissions, such as running as irisadmin. They reject the --user, --pwfile, and --key options.

export

The export action exports the entire ACL database to a file in XML format, or in JSON if the file name ends in json. See ACL storage for backup and restore examples. If the file name does not already end in .xml or .json, dhconfig appends the extension, so --file /tmp/acls creates /tmp/acls.xml. The import action reads the file name exactly as you give it. Key arguments are:

OptionDescription
-f,--file <arg>Name of the file to export to.
--typeType of ACL to export. Allowed values: passwd, columnacls, groupstrategy, inputtableeditors, strategyaccount, tableacls, usergroup, systemuser, publickeys.

Example usage:

import

The import action imports ACL data into the backing store. The action's arguments change how imported ACLs interact with existing ones. import's arguments are extensively documented in dhconfig's --help output, so we will not repeat all of them here; however, there are some key arguments that are worth mentioning.

When handling existing ACLs, the following options are important:

OptionDescription
-f,--file <arg>Name of the file to import from. Required.
--ignore-existingIgnore existing entries and continue.
-o,--overwriteOverwrite any existing entry.
--replace-allReplace the entire ACL database with the imported ACL. When this option is set, all existing ACLs are removed and replaced with those in the import file. This is useful for restoring a known good state or migrating ACLs between environments. Public keys for protected users are kept, unless you also set --include-protected, which removes the default protected users from that list. Users named with --protect-keys always keep their keys. This requires --direct (or --etcd). Cannot be combined with --overwrite. It also cannot be used with a partial --type selection, and the file must come from a full export.
If none of these options are set, the action will fail if there are any conflicting ACLS.

Other important options include:

OptionDescription
--include-protectedInclude protected keys in the import. If this is not set, public keys for protected users, such as iris, merge, and tdcp, are skipped.
--protect-keys <arg>Users to protect from public key import. System users specified by the AclImporter.protectedUsers are also protected unless --include-protected is set.
--typeType of ACL to import. Allowed values: passwd, columnacls, groupstrategy, inputtableeditors, strategyaccount, tableacls, usergroup, systemuser, publickeys. The export file might contain all the types. This will import only the specified type(s) and ignore the rest. Multiple values are allowed here.
--continue-after-errorLog and skip individual records that fail validation instead of aborting the entire import. See Continue after error below.

Example usage:

To replace the entire ACL database with the imported ACL, run the following as a privileged user such as irisadmin, because --direct requires it:

Import ACLs, overwriting any that already exist:

Continue after error

By default, the import action aborts on the first record that fails validation. The --continue-after-error flag changes this behavior so that invalid records are logged and skipped, allowing the rest of the import to proceed. A summary of all skipped records is printed at the end.

This is especially useful when continuously streaming ACL updates from a primary cluster into a secondary one, where some records in the source may not pass validation on the target. Three common scenarios follow. These checks run in the ACL write service, so records written with --direct are not checked this way.

ScenarioDescriptionExample
Non-ASCII account namesAccount names containing spaces, unicode, or other non-printable characters (often caused by copy-paste errors).<user>0123456F 2</user>
Invalid column ACLsColumn ACL records using * as the column name, which was valid in older releases but is rejected in current versions.<column>*</column>
User-name group membershipA group whose name matches an existing user has members assigned to it. This configuration is no longer permitted.User xyz exists, and the group xyz has members.

Example usage:

Import ACLs from a file, skipping any records that already exist and any that fail validation:

Import only password and user-group records, skipping invalid ones:

When records are skipped, the tool logs each error individually and prints a summary at the end:

Note

The --continue-after-error flag does not only affect validation errors: exceptions while processing a record can also include backing-store failures. The failed record is skipped and processing continues, so an operational failure can leave a partial import. Structural errors in the XML file (such as malformed XML) or authentication failures still cause the import to abort.

users

The users action lets you manage users of the system. It supports the following subcommands:

SubcommandDescription
addAdd a user.
deleteRemove a user.
listList users.
remove-passwordRemove a user's password.
remove-runasRemove a user's system user mapping.
set-passwordSet a user's password.
set-runasSet a user's system user mapping.

...each of which has its own set of options, which are documented in dhconfig's --help output. We won't go into detail on all of them here, but we will elaborate on some of the more complex subcommands.

add

Add a user to the system.

ArgumentDescription
-n,--name <arg>User name to create.
-g,--group <arg> ...Groups to add the user to. To specify multiple groups, list them as separate arguments (e.g., --group G1 G2 G3).
--hashed-password <arg>The password for the user, hashed in apr1 format. Create a hashed password with openssl passwd -apr1 (see The --hashed-password option).
-f,--file <arg>Name of a CSV file of users to create, with user names in the first column and apr1-hashed passwords in the second. The file must not have a header row. Cannot be combined with --new-key. The --name, --hashed-password, and --group options are accepted but ignored when you use --file, although invalid values for them are still rejected.
--new-key <arg>Path to a public key file for the new user. The user name in the key file must match --name.

Usage examples:

Create a user with a public key:

Create a user with a hashed password and add them to multiple groups:

Create every user listed in a CSV file:

delete

Remove a normal user from the system. You cannot delete special system users such as iris, merge, and tdcp.

ArgumentDescription
-n,--name <arg> ...Users to delete. To specify multiple users, list them as separate arguments (e.g., --name user1 user2).
-f,--file <arg>Name of a CSV file of users to delete, with user names in the first column and no header row. Other columns are ignored. Cannot be combined with --name.

Example usage:

list

List users and their group memberships.

ArgumentDescription
-n,--name <arg> ...Users to display. To specify multiple users, list them as separate arguments (e.g., --name user1 user2).
-g,--group <arg> ...Only display members of these groups. To specify multiple groups, list them as separate arguments.
--include-run-asInclude the system user mapping for each user (see set-runas).
--csvWrite the output as CSV.
-f,--file <arg>Name of a file to write the output to, in CSV format.

Example usage:

set-password

Set the password for a user. An authenticated user with sufficient permissions can set the password for any user. Any user can set their own password.

ArgumentDescription
-n,--name <arg>User name to set the password for. Defaults to the --user value if omitted. Required whenever --user is not set, such as when you authenticate with a key or use --direct.
--hashed-password <arg>The new password, hashed in apr1 format. If omitted, you will be prompted to enter the new password on the command line. Create a hashed password with 'openssl passwd -apr1' (see The --hashed-password option below.)

Note

The arguments to this command can be confusing.

--name and --hashed-password specify the name of the target user and the new password for that user.

--user and --pwfile specify the name and current password of a user for authentication .

The command will prompt for either or both passwords on the command line if you don't provide them as arguments.

The --pwfile option

This option is used to specify a file containing the base64-encoded current password for the user specified by the --user option. This is one way to provide the required authentication for the set-password command.

The --hashed-password option

This option is used to specify the new password for the user specified by the --name option. The value is an apr1-encoded password.

Note that the apr1 encoding can contain characters that will be interpreted by the shell. You can avoid this by enclosing the value in single quotes or storing it in a variable.

Examples

Set the password for user targetUser. This command will prompt for adminuser's password and then the new password for targetUser.

Set the password for user targetUser. This command will authenticate using the private key for iris and will prompt for the new password for targetUser.

Set the password for user targetUser. This command provides all the required passwords on the command line.

Set the password for your own user. This command will prompt for your current password and then the new password.

Warning

Some of the examples above leave the plaintext password in shell history. It is more secure to use only the options that read sensitive information from files or the command line.

Deephaven-to-system user mappings: set-runas and remove-runas

In some environments, it is necessary for a Deephaven user's worker processes to run as a specific system user on the host operating system. This mapping allows administrators to specify which system account the Remote Query Dispatcher uses when it starts workers for a given Deephaven user, such as workers that run Persistent Queries (PQs). This is typically managed using the set-runas and remove-runas subcommands. The mapping is also visible using the --include-run-as option with the list subcommand.

The set-runas command maps a Deephaven user to a specific system (OS-level) user account. This mapping determines which system user identity the Remote Query Dispatcher uses when it starts worker processes for the Deephaven user.

By default, the Remote Query Dispatcher does not use this mapping. With set-runas and RemoteQueryDispatcher.startWorkersAsSystemUser=true, a particular Deephaven user's workers instead run as a designated system user. This is especially useful in environments with strict security, compliance, or auditing requirements, where it is important to control and track which system accounts are used.

Typical use cases include:

  • Ensuring that actions requiring access to restricted files or services are performed under the appropriate system user account.
  • Enabling more granular auditing by associating system-level actions with individual Deephaven users.
  • Complying with organizational policies that require separation of privileges or user accountability.

Example usage:

This command maps the Deephaven user dh_user to the system user sys_user, so the Remote Query Dispatcher starts dh_user's worker processes as sys_user.

Important

The mapping takes effect only when RemoteQueryDispatcher.startWorkersAsSystemUser=true, which defaults to false. When that property is enabled, a user without a mapping cannot start workers, except for users listed in RemoteQueryDispatcher.startWorkersAsDispatcherUser (default iris). See per-user workers.

Options:

OptionDescription
-n,--name <arg>Deephaven user name to create a mapping for.
--system-user <arg>The system (OS) user to run operations as.

groups

The groups action lets you manage groups. This action has several subcommands:

SubcommandDescription
add-memberAdd a user to one or more groups.
deleteDelete one or more groups.
listList the groups.
remove-memberRemove users from one or more groups.

The options for each subcommand are detailed in dhconfig's --help output.

add-member

To add user1 and user2 to groups G1, G2, and G3, run:

delete

To delete groups G2 and G3, run:

list

List groups and their members.

ArgumentDescription
-g,--group <arg> ...Groups to display. To specify multiple groups, list them as separate arguments.
--csvWrite the output as CSV.
-f,--file <arg>Name of a file to write the output to, in CSV format.

To list all groups, run:

remove-member

To remove user1 and user2 from groups G1 and G5, run:

publickeys

The publickeys action lets you manage public keys for users.

list

List public keys for users. By default, the output is a table showing truncated keys. If you specify --csv or --file, the output will include the full public key. Use the --include-hash option to add a unique hash value for each key, which can be used with the delete subcommand.

ArgumentDescription
--include-hashInclude an identifying hash for use with acls publickeys delete.
--csvWrite the output as CSV, including the full public key.
-f,--file <arg>Name of a file to write the output to, in CSV format.
-n,--name <arg> ...Users to display keys for. To specify multiple users, list them as separate arguments (e.g., --name user1 user2).

Example usage:

import

Import a public key. --file may be a Deephaven public key file, private key file, or a file containing a list of keys to be added as user publickey pairs. Use --ignore-existing to skip any keys that already exist.

delete

Delete a public key. You may use the --file option to delete a public key identified by the specified key file, or the --hash option to remove a key based on the hash provided by list.

rows, columns, and inputtables

The actions rows, columns, and inputtables may be used to manage table-level ACLs. Each supports the list, add, and delete subcommands.

list

List the row, column, or input table ACLs. All filters are optional; when you set more than one, an ACL must match every filter to be listed.

ArgumentDescription
-g,--group <arg> ...Groups to filter on. To specify multiple groups, list them as separate arguments.
-n,--namespace <arg> ...Namespaces to filter on. To specify multiple namespaces, list them as separate arguments.
-t,--table-name <arg> ...Table names to filter on. To specify multiple tables, list them as separate arguments.
--csvWrite the output as CSV instead of a formatted table.
-f,--file <arg>Write the output as CSV to this file, even if --csv is omitted.

add and delete

Add or remove a single ACL. --group, --namespace, and --table-name are required for both subcommands, and each takes exactly one value.

ArgumentApplies toDescription
-g,--group <arg>All subtypes; add and deleteGroup for the ACL.
-n,--namespace <arg>All subtypes; add and deleteNamespace for the ACL.
-t,--table-name <arg>All subtypes; add and deleteTable name for the ACL.
-c,--columns <arg> ...columns; add and deleteColumn names for the ACL. Required. To specify multiple columns, list them as separate arguments.
--acl <arg>rows and columns; add onlyThe ACL (filter generator) to create. Required.
--can-edit <arg>inputtables; add onlyWhether the group can edit the input table: true or false. Required. Combine with --overwrite to change the value on an existing entry.
-o,--overwriteAll subtypes; add onlyOverwrite any existing entry.

Example usage:

Add a row ACL for the Asia group to the Trades table in the Market namespace:

Delete a column ACL for the Desk group from the Trades table in the Market namespace:

List all input table ACLs:

Allow the Desk group to edit the Trades input table in the Market namespace: