---
title: Controller and dispatcher usage restrictions
---

[Remote Query Dispatchers (dispatchers)](./dispatcher.md) and [Persistent Query Controllers (controllers)](./pq-controller.md) can be configured to restrict which users or [Persistent Query (PQ)](../../query-management/pq-overview.md) types are allowed to run. These restrictions are defined using specific properties and apply to both the controller and the dispatchers.

Deephaven systems include some default restrictions:

- Certain PQ types, such as `ScriptMergeServer` and `CsvImport`, are restricted to merge servers.
- Some PQ types can only be created by users in specific groups. For instance, import queries are limited to users in the `iris-datamanagers` or `iris-dataimporters` groups.
- By default, merge servers restrict access to users in the `iris-schemamanagers` group. See [Dispatcher group restrictions](#dispatcher-group-restrictions) for details on how to modify this.

To modify these permissions, you can add users to the appropriate groups using the [ACL Editor](../../interfaces/web/permissions.md#the-acl-editor) or the command-line tool [dhconfig acls](../configuration/dhconfig/acls.md).

The terms _server_ and _dispatcher_ are used interchangeably to refer to the Remote Query Dispatcher process that creates [workers](./overview.md#workers).

The terms _server type_ and _server class_ are used interchangeably to describe the classes used to restrict:

- The types of Persistent Queries that can be started on a dispatcher.
- The users who can start PQs or [Code Studios](../../interfaces/web/code-studio.md).

> [!NOTE]
> A Code Studio is historically referred to as a console, and this term is often used in property names.

There are two main parts to setting up restrictions on where users can create workers:

1. The controller handles the options presented to a user based on PQ types and user group membership.
   - [Server classes](#server-classes) restrict Persistent Query types to specific server classes.
   - [Console server classes](#console-server-classes) restrict Code Studios to specific server classes.
2. The dispatcher enforces restrictions to ensure that clients bypassing the controller cannot ignore the restrictions.
   - [Dispatcher group restrictions](#dispatcher-group-restrictions) explains how to set up the properties to enforce these restrictions.

The following sections provide more detail about the classes and groups used to restrict the dispatchers and the Persistent Query types that can be run on them. Then a complete example walks through the process of setting up a new server class, adding a console server class, and restricting the dispatcher to specific groups.

> [!CAUTION]
> The examples restart processes and change server configuration, so should only be run on a system where outages do not matter.

After you complete the examples, [undo any of the changes you made](#remove-changed-properties).

## Server classes

Each dispatcher belongs to a single server class, defined in the controller's properties by the dispatcher's `iris.db.<server number>.class` value. The [controller configuration documentation](./pq-controller.md#query-and-merge-servers) provides details on predefined server classes for query servers and merge servers. You can also define custom server classes in addition to the predefined ones.

For example, the following property is automatically generated in most installations, defining the first server to be of the default class `Query`:

```text
iris.db.1.class=Query
```

If additional server classes are defined, you will need to set the appropriate properties:

- [Console server classes](#console-server-classes) refer to the server classes defined by these `iris.db.<number>.class` properties.
- Since Persistent Queries are only allowed to run on `Query` or `Merge` server classes in a default installation, a [custom-defined server class](./pq-controller.md#query-types) won't be able to run persistent queries without further changes.

See [add a new server class](#add-a-new-server-class) below for a walkthrough of these properties.

## Console server classes

The server class specified by the `iris.db.<server number>.class` property can also refer to a console-specific server class. This is useful for servers that should be available to privileged users for their Code Studios (interactive consoles) but not necessarily for Persistent Queries.

To define a console server class, add properties that the Persistent Query Controller can access. Each class specifies the ACL groups that a user must belong to in order to start a Code Studio on dispatchers of that class. If you want the server to be available to everyone, either omit the following property or explicitly set it to the "allusers" ACL group:

```text
ConsoleServerClass.<server class name>.allowedGroups=<ACL groups allowed>
```

The [combine PQ and console classes](#combine-pq-and-console-classes) section below illustrates these properties in use.

## Console groups

As the [server definitions](./pq-controller.md#server-definitions) section describes, console groups are placed directly into the server's definition to restrict users who can start Code Studios on that dispatcher. A user who isn't in a group won't be able to start Code Studios on the restricted dispatcher. This example restricts a dispatcher to only allow users in the `merge-console-group` or `iris-superusers` groups to create Code Studios on the server.

```text
iris.db.<n>.consoleGroups=merge-console-group,iris-superusers
```

See [console groups restrictions](#console-groups-restrictions) below for an end-to-end example.

## Dispatcher group restrictions

All the properties described so far affect the controller and its clients, determining which dispatchers are visible to users. However, it is possible for clients to connect directly to dispatchers and request workers, bypassing these restrictions. To prevent this, Deephaven recommends adding properties to ensure that only clients in specified ACL groups can start workers, even when connected directly.

Use the following property to specify which groups can start workers. If a user is not in any of these groups, they will not be able to start workers on this dispatcher:

```text
RemoteQueryDispatcher.allowedGroups=<comma-delimited list of ACL groups>
```

Use [stanzas](../configuration/deephaven-properties-files.md#scoped-stanzas) to avoid applying the restriction to all dispatchers. To apply restrictions to one server, put the property in a stanza with the `host` qualifier and the host's FQDN and IP, such as:

```text
[host=hostname|host-ip] {
    RemoteQueryDispatcher.allowedGroups=allowed_group_1,allowed_group_2
}
```

The default configuration includes the following restriction for merge servers (by putting it in a stanza with `service.name=dbmerge`), ensuring that non-privileged users cannot bypass the controller restrictions and start merge workers directly.

```text
RemoteQueryDispatcher.allowedGroups=iris-schemamanagers
```

> [!NOTE]
> If `RemoteQueryDispatcher.allowedGroups` is used, and the group `iris-superusers` (or another group that the `iris` user is in such as `iris-schemamanagers`) is not in the list of groups, Persistent Queries will not start on that dispatcher.

See the [Query and Merge Servers](./pq-controller.md#query-and-merge-servers) documentation for details on adding ACL group restrictions to the list of available servers when users create interactive consoles.

The [dispatcher group restrictions](#dispatcher-group-restrictions) example illustrates these properties.

## End-to-end example

### Initial example setup

Before editing properties, use the [`dhconfig properties export`](../configuration/dhconfig/properties.md) command to export `iris-environment.prop` to a local file. Keep a copy of the exported file as a backup before making changes.

To run these examples you need a cluster with at least two query servers. The examples assume that the second server (`iris.db.2.<properties>`) is a query server. You can verify this by viewing `iris-endpoints.prop`. For instance, use `dhconfig` to print the file and grep for the different servers and their classes:

```bash
/usr/illumon/latest/bin/dhconfig properties export --file iris-endpoints.prop | grep "iris.db.*.class"
```

You should see at least two query nodes in your cluster, plus a merge server — select one of them for the examples. For example, a three-node cluster might have the following output from that command:

```text
iris.db.1.class=Query
iris.db.2.class=Query
iris.db.3.class=Merge
```

The examples use `iris.db.2` but can be updated to use a query server of your choice.

The examples require two users. Since neither user is granted superuser or data-manager privileges, they can only see basic Persistent Query types such as Live Query, Batch Query, and Live Query Replay.

- `user1` is a user with additional group membership that shows how the restrictions work. Only an administrative user can add these privileges, which are described in each example.
- `user2` is a basic user with no extra privileges.

Add the users with the [ACL Editor](../permissions/web-acl-editor.md). After adding the users, add `user1` to `PrivilegedLargeGroup`.

![acl-1.png](../../assets/sys-admin/pq-controller/acl-1.png)

The examples update a lot of properties. See [viewing and changing configuration](../configuration/configuration-overview.md#managing-configuration) for details on how to change configuration files. After exporting `iris-environment.prop`, add the new and updated properties to the end of the exported file so that they override default values, then import the file with `dhconfig properties import`.

The examples use an existing extra query server (as described above) in the existing configuration for the examples, and you may assign it a unique name to make it clear. At the end of the exported `iris-environment.prop`, add the following stanza to change the server's name to `Large_Query_Host`:

```text
[service.name=iris_controller|controller_tool] {
    iris.db.2.name=Large_Query_Host
}
```

Since adding new types of Persistent Queries is beyond the scope of this guide, these examples edit existing ones. First, make a copy of the Persistent Query types file to ensure you can safely make changes.

```bash
sudo -u irisadmin cp /usr/illumon/latest/etc/PersistentQueryConfigurationTypes.xml /etc/sysconfig/illumon.d/resources/CustomQueryConfigurationTypes.xml
```

Add the following to `iris-environment.prop` to use your cloned file instead of the original one:

```text
iris.controller.configurationTypesXml.deephaven=CustomQueryConfigurationTypes.xml
```

### Add a new server class

Define a new server class called `LargeQuery` and assign query server 2 to it. In the `iris_controller` stanza in `iris-environment.prop`, add the following property, then import the file. Your `iris-environment.prop` file now includes:

```text
iris.controller.configurationTypesXml.deephaven=CustomQueryConfigurationTypes.xml

[service.name=iris_controller|controller_tool] {
    iris.db.2.name=Large_Query_Host
    iris.db.2.class=LargeQuery
}
```

Edit your copied Persistent Query types file `/etc/sysconfig/illumon.d/resources/CustomQueryConfigurationTypes.xml`. Change the `Script` configuration type (the first one in the file) so that it only runs on servers of type `LargeQuery`, replacing the existing line with:

```xml
<ConfigurationType name="Script" displayableName="Live Query (Script)" serverTypes="LargeQuery" supportsReplicas="true">
```

Import your modified `iris-environment.prop` file, and [restart the controller and web service](#restart-services) to pick up the changes.

Both `user1` and `user2` will see the same server options.

- For live queries, the only option is the newly-defined `Large_Query_Host`.
- Other PQ types will show `AutoQuery` and any defined query servers.
- Code Studios are allowed on both `Query_1` and `Large_Query_Host`.

### Combine PQ and console classes

In `iris-environment.prop`:

- Use `ConsoleServerClass` to define a `PrivilegedLargeClass` server class that is available to users in group `PrivilegedLargeGroup`.
- Update the `class` for our chosen server in the properties so that the controller knows about the console server class - it is the property's _class_ name, not _group_ name.

Your `iris-environment.prop` file now includes:

```text
iris.controller.configurationTypesXml.deephaven=CustomQueryConfigurationTypes.xml

ConsoleServerClass.PrivilegedLargeClass.allowedGroups=PrivilegedLargeGroup

[service.name=iris_controller|controller_tool] {
    iris.db.2.name=Large_Query_Host
    iris.db.2.class=PrivilegedLargeClass
}
```

To allow PQ creation on the console server class, edit your configuration types file `/etc/sysconfig/illumon.d/resources/CustomQueryConfigurationTypes.xml`. Update the `Script` configuration type (the first one) so that it is allowed to start on server classes of either `Query` or the new `PrivilegedLargeClass`.

```text
<ConfigurationType name="Script" displayableName="Live Query (Script)" serverTypes="Query,PrivilegedLargeClass" supportsReplicas="true">
```

Import your modified `iris-environment.prop` file, and [restart the controller and web service](#restart-services) to pick up the changes.

Users will now see different behaviors:

- Both `user1` and `user2` can run `Live Query` PQs on `Large_Query_Host` because `PrivilegedLargeClass` is listed in that query type's `serverTypes`. Since `Query` is also listed, these PQs can be run on standard query servers as well.
- Other query types cannot be run on `Large_Query_Host` because they are not listed in other PQ `serverTypes` definitions.
- `user1`, being a member of `PrivilegedLargeGroup`, still sees `Large_Query_Host` as an option for starting a new Code Studio.
- The unprivileged `user2` cannot start Code Studios on `Large_Query_Host`.

### Console groups restrictions

Edit `iris-environment.prop`:

- Modify the stanza to only define a `consoleGroups` property to allow `PrivilegedLargeGroup,iris-superusers`.
- Remove the `ConsoleServerClass.PrivilegedLargeClass.allowedGroups` property if it exists, as it is no longer needed. This change will make the `Large_Query_Host` server a member of the `Query` server class, which is the default.

Your `iris-environment.prop` file now includes:

```text
iris.controller.configurationTypesXml.deephaven=CustomQueryConfigurationTypes.xml

[service.name=iris_controller|controller_tool] {
    iris.db.2.name=Large_Query_Host
    iris.db.2.consoleGroups=PrivilegedLargeGroup,iris-superusers
}
```

Ensure that your copied Persistent Query types file `/etc/sysconfig/illumon.d/resources/CustomQueryConfigurationTypes.xml` has the `Script` configuration type (the first one in the file) using the originally defined server types of `Query`:

```xml
<ConfigurationType name="Script" displayableName="Live Query (Script)" serverTypes="Query" supportsReplicas="true">
```

Import your modified `iris-environment.prop` file, and [restart the controller and web service](#restart-services) to pick up the changes.

The users see similar behavior as in the combining PQ and console classes examples:

- Both `user1` and `user2` can run `Live Query` PQs on `Large_Query_Host` because it is now a `Query` server class.
- Since `user1` is a member of `PrivilegedLargeGroup`, they still see `Large_Query_Host` in the options for a new Code Studio.
- The unprivileged `user2` cannot start Code Studios on `Large_Query_Host`.

### Dispatcher restrictions

Creating a direct client to a dispatcher is beyond the scope of this example. To illustrate the dispatcher rejecting a request from a user not in the required groups, add a restriction to one of the dispatchers without updating the controller's restrictions.

Edit `iris-environment.prop`.

- Do not apply class restrictions of any kind to the server - the only definition should be the name.
- Add a stanza for the same dispatcher we have been updating, using its host and IP. You can find valid stanzas in your cluster's generated `iris-endpoints.prop` file with:

```bash
/usr/illumon/latest/bin/dhconfig properties export --file iris-endpoints.prop | grep "\[host="
```

- Create a host-specific stanza like the one that you found above, and add the group that `user1` is a member of.

Your `iris-environment.prop` file now includes these properties, with a valid host-specific stanza instead of `fqdn-1|ip-1`:

```text
iris.controller.configurationTypesXml.deephaven=CustomQueryConfigurationTypes.xml

[service.name=iris_controller|controller_tool] {
    iris.db.2.name=Large_Query_Host
}

[host=fqdn-1|ip-1] {
    RemoteQueryDispatcher.allowedGroups=PrivilegedLargeGroup
}
```

Ensure that your copied Persistent Query types file `/etc/sysconfig/illumon.d/resources/CustomQueryConfigurationTypes.xml` has the `Script` configuration type (the first one in the file) using the originally defined server types of `Query`:

```xml
<ConfigurationType name="Script" displayableName="Live Query (Script)" serverTypes="Query" supportsReplicas="true">
```

Import your modified `iris-environment.prop` file, and [restart the controller, web service, and both query servers](#restart-services) to pick up the changes.

Both users will have the option to start a Code Studio on `Large_Query_Host`, but the results will be different:

- Both users can start Code Studios on the unrestricted server.
- Since `user1` is in the `PrivilegedLargeGroup` they can create a Code Studio on the restricted server.
- Since `user2` is not in the `PrivilegedLargeGroup`, attempting to create a Code Studio on `Large_Query_Host` results in an error like `{user2} is not permitted to create new jobs on <host name>`.

### PQ-only server (no Code Studios)

To configure a server that runs Persistent Queries but does not allow Code Studios, set `consoleGroups` to a non-existent group. This effectively disables Code Studio access while still allowing PQs.

Edit `iris-environment.prop` to include:

```text
[service.name=iris_controller|controller_tool] {
    iris.db.2.name=PQ_Only_Host
    iris.db.2.consoleGroups=no-such-group
}
```

Import your modified `iris-environment.prop` file, and [restart the controller and web service](#restart-services) to pick up the changes.

With this configuration:

- All users with appropriate PQ permissions can run Persistent Queries on `PQ_Only_Host`.
- No users can start Code Studios on `PQ_Only_Host` because no one is a member of `no-such-group`.
- The server will not appear in the Code Studio server selection dropdown.

### Restart services

After changing the controller and dispatcher properties, restart the controller and web service on the infrastructure node using the following commands:

```bash
/usr/illumon/latest/bin/dh_monit restart iris_controller
/usr/illumon/latest/bin/dh_monit restart web_api
```

Also restart any impacted dispatchers on their nodes:

```bash
/usr/illumon/latest/bin/dh_monit restart db_query_server
```

If the changes are for a merge server, use its service name:

```bash
/usr/illumon/latest/bin/dh_monit restart db_merge_server
```

### Remove changed properties

Remember to remove any properties you added to `iris-environment.prop` and re-import the file. You can restore from the backup you made earlier in the `irisadmin` home directory. After re-importing, restart the controller and web API service:

```bash
/usr/illumon/latest/bin/dh_monit restart iris_controller
/usr/illumon/latest/bin/dh_monit restart web_api
```

## Related documentation

- [ACL Editor](../../interfaces/web/permissions.md#the-acl-editor)
- [Configuration tools](../configuration/dhconfig/overview.md)
- [Dispatcher](./dispatcher.md)