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:

dhconfig acls <action> [arguments]
dhconfig acls <subtype> <action> [arguments]

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

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 ACL command. For a list of all available subtypes, run:

dhconfig acls --help

Which prints the following:

dhconfig acls [import|export|users|groups|publickeys|rows|columns|inputtables|help] [arguments]

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

dhconfig acls users --help

Which will return the following:

dhconfig acls users [--configfile <arg>] [--diskprops] [--etcd] [-h] [-k <arg> | -user <arg>] [-pf <arg>]  [-v]
Supported subcommands [add|delete|list|remove-password|remove-runas|set-password|set-runas]

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

dhconfig acls users add --help

Which will return the following:

usage: dhconfig acls users add [--configfile <arg>] [--direct] [--diskprops] [--etcd] [-g <arg>] [-h] [--hashed-password
       <arg>] [-k <arg> | -user <arg>] [-n <arg>] [--new-key <arg>] [-pf <arg>]  [-v]
Create a  user.

...followed by a description of all of the subcommand's options and some usage examples.

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.

export

The export action exports the entire ACL database as an XML file. Key arguments are:

Example usage:

dhconfig acls export --file /tmp/acls.xml

dhconfig acls export --file /tmp/acls.xml --type passwd --type publickeys

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:

Other important options include:

Example usage:

To replace the entire ACL database with the imported ACL, run:

dhconfig acls import --replace-all --file /tmp/acls.xml

users

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

...each of which has its own set of subcommands, 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.

Usage examples:

In this example, we create a user with a private key:

dhconfig acls users add --name steven --new-key /path/to/keyfile

delete

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

Example usage:

dhconfig acls users delete --name greg

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.

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.

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.

echo -n the_password | base64 > /safe/location/pwfile.txt

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.

# Generate a hashed password and print it
openssl passwd -apr1 mynewpassword

# Generate a hashed password and store it in an environment variable
HASHED_PASSWORD=$(openssl passwd -apr1 mynewpassword)

Examples

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

/usr/illumon/latest/bin/dhconfig acls users set-password --name targetUser --user adminuser

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.

sudo -u irisadmin /usr/illumon/latest/bin/dhconfig acls users set-password --name targetUser

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

/usr/illumon/latest/bin/dhconfig acls users set-password --name targetUser --hashed-password $HASHED_PASSWORD --user adminuser --pwfile /safe/location/pwfile.txt

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

/usr/illumon/latest/bin/dhconfig acls users set-password --user myusername

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

In some environments, it is necessary for a Deephaven user to execute processes or queries as a specific system user on the host operating system. This mapping allows administrators to specify which system account should be used when a given Deephaven user initiates certain actions, such as running Persistent Queries (PQs) or other privileged tasks. 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 is used when the Deephaven user initiates certain privileged operations, such as running Persistent Queries (PQs) or other tasks that require elevated or audited access on the host machine.

By default, privileged operations launched by Deephaven may run as the same user that started the Deephaven service. However, with set-runas, you can configure the system so that actions performed by a particular Deephaven user are instead executed 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 for sensitive operations.

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:

/usr/illumon/latest/bin/dhconfig acls users set-runas --name dh_user --system-user sys_user

This command configures the Deephaven user dh_user so that any privileged operation they initiate will run as the system user sys_user.

Options:

groups

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

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:

dhconfig acls groups add-member --name user1 user2 --group G1 G2 G3

delete

To delete groups G2 and G3, run:

dhconfig acls groups delete --group G2 G3

list

To list all groups, run:

dhconfig acls groups list

remove-member

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

dhconfig acls groups remove-member --name user1 user2 --group G1 G5

publickeys

The publickeys action lets you manage public keys for users.

Example usage:

To import a public key, use import. --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. In this case, we set --ignore-existing to skip any keys that already exist.

dhconfig acls publickeys import --file /path/to/publickeyfile --ignore-existing

To delete a public key, use delete. 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.

dhconfig acls publickeys delete --hash <hash>

rows, columns, and inputtables

The actions rows, columns, and inputtables may be used to manage table-level ACLs.

Example usage:

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

dhconfig acls rows add --namespace Market --table Trades --group Asia --acl "new GroupFilterGenerator()"

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

dhconfig acls columns delete --namespace Market --table Trades --group Desk --columns Price Size

List all input table ACLs:

dhconfig acls inputtables list

Related documentation

• dhconfig overview
• Access Control List
• Authentication
• Public and private keys