---
title: Per-user workers
---

## Back-End / Server Configuration

The ability to run worker-processes as specific system users (run-as) attempts to work as similarly as possible to the default/non-run-as system. Two additional scripts are packaged in the installer, which require `sudo` configuration to run properly. See the [Sudo configuration](#sudo-configuration) section below for details. If the run-as feature is not desired, then no additional configuration is required.

## Architecture

Worker processes are spawned by the RemoteQueryDispatcher via shell-script with a number of parameters. In the case that we wish to run a worker “as” a specific system-user, the `start_db_query_worker_as` (or `start_dnd_worker_as` for Core+) script is called. These scripts are sudo-wrappers around the pre-existing scripts, which are currently used for spawning workers. The underlying scripts are still called directly for “non-as” worker creation.

In addition to sudo-execing existing scripts, the `start_db_query_worker_as` and `start_dnd_worker_as` scripts will ensure that directory ownership of class-compilation directories is changed to `${user}:dbquery` with permissioning of 2775. This permissioning will allow the worker-process running as the specified user to create directories/files under `/db/TempFiles/${worker-user}`, but will allow cleanup to be performed by the dbquery user as part of the RQD’s existing functionality. This path may be changed with the `RemoteQueryDispatcher.userWorkspaceRoot` property.

Mappings between DH-users and system-users are stored within the existing ACL database, which is consistent with all other permissioning within the system. As with other permission configurations, the table may be modified using a dedicated tab within the ACL Editor. See the [Front-End Configuration](#front-end-configuration) section for information regarding user-mappings.

## Enabling

Enabling per-user functionality is done via configuration option - generally within `iris-environment.prop`. In most cases, the `db_merge_server` would not have this option enabled, only the `db_query_server`.

```yaml
[service.name=dbquery|iris_console|web_api_service] {
    RemoteQueryDispatcher.startWorkersAsSystemUser=true

    # the following are defaulted parameters with their sane defaults
    # RemoteQueryDispatcher.startWorkersAsDispatcherUser=iris
    # RemoteQueryDispatcher.userWorkspaceRoot=/db/TempFiles
}
```

## Sudo configuration

In order for the `start_db_query_worker_as` and `start_dnd_worker_as` commands to run properly, the following section must be added to the system sudo-configuration via `visudo`:

```
################################################################################
# Run commands by "dbquery" with the exec system call directly, and force
# umask to allow group-write
Defaults:dbquery !pam_session,!pam_setcred,!use_pty,umask_override,umask=002

# Allow environment for PQs to be preserved
Defaults:dbquery env_keep += "PQ_OWNER PQ_NAME PQ_VERSION PQ_SERIAL MYSQLDBACLPROVIDER.PASS RQP_WORKER_NONCE RQP_PROCESS_INFO_ID RQP_DISPATCHER_NAME JAVA_OPTS DND_PATH VIRTUAL_ENV"

# Allow "dbquery" to start worker for dbquerygrp users. "ALL=(%dbquerygrp)"
# may be changed to "ALL=(ALL)" to permit sudo to all users instead of just the
# specific group. All "run-as" users must be included in dbquerygrp
dbquery ALL=(%dbquerygrp) NOPASSWD: /usr/illumon/latest/bin/start_db_query_worker
dbquery ALL=(%dbquerygrp) NOPASSWD: /usr/illumon/latest/bin/start_dnd_worker
dbquery ALL=(%dbquerygrp) NOPASSWD: /bin/kill

# Allow "dbquery" to run (as root) a script which ensures proper directory
# ownership & permissions for per-user class-cache
dbquery ALL=(root) NOPASSWD: /usr/illumon/latest/bin/chown_user_cache
################################################################################
```

Additionally, users must be added to the `dbquerygrp` for workers to successfully start "as" a given user.

## Front-end configuration

A new tab has been added to the existing ACL Editor, which is enabled when the `RemoteQueryDispatcher.startWorkersAsSystemUser=true` property is visible to the front-end.

![A new tab in the existing ACL Editor](../../assets/sys-admin/configuration/peruser1.png)

Mappings may be added individually via **Update** button in the top-left of the screen, or in batches via secondary-click/**Update Run-As Mapping** on multi-selected users.

![The **Update Run-As Mapping** option highlighted in in the **Update** dropdown menu](../../assets/sys-admin/configuration/per-user2.png)

![A dialog prompting the user to select a system user](../../assets/sys-admin/configuration/per-user3.png)

Similarly, user-mappings may be deleted individually or in batches by selecting/multi-selecting the row(s) and selecting **Delete Run-As Mapping** from the secondary-click menu.

Changes to system-user mappings are checked when starting a new worker process. Changes will not be applied to workers which are running at the time of the change.

## Related documentation

- [Deephaven properties files](./deephaven-properties-overview.md)
- [ACLs](../permissions/permissions-overview.md)