Controller and dispatcher usage restrictions

You can restrict which users or Persistent Query (PQ) types a Remote Query Dispatcher (dispatcher) or user is allowed to run by defining specific properties. These configurations affect both the Persistent Query Controller (controller) and the dispatchers.

Some restrictions are automatically implemented in any Deephaven system:

  • Certain Persistent Query types, such as ScriptMergeServer and CsvImport, are only allowed to run on merge servers.
  • Some Persistent Query types can only be defined by users in specific groups. For example, import queries can only be created by users in the iris-datamanagers or iris-dataimporters groups.

To grant users permissions for these query types, add them to the appropriate groups using the ACL editor or the command-line dhconfig acl tool.

The terms server and dispatcher are used interchangeably to refer to the Remote Query Dispatcher process that creates 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.

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.
  2. The dispatcher enforces restrictions to ensure that clients bypassing the controller cannot ignore the restrictions.

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 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:

iris.db.1.class=Query

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

  • 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 won't be able to run persistent queries without further changes.

The "new server class" example walks through 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, use the "allusers" group as the ACL group:

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

The "console-only" and "combining PQ and console classes" examples illustrate these properties in use.

Console groups

As the 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.

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

The "console group restrictions" example is 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:

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

Use stanzas to avoid applying the restriction to all dispatchers. To apply restrictions one server, put the property in a stanza with the host qualifier and the host's fqdn and IP, such as:

[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 anyway.

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 documentation for details on adding ACL group restrictions to the list of available servers when users create interactive consoles.

The dispatcher group restriction example illustrates these properties.

Examples

The examples walk through the concepts detailed above.

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.

Initial example setup

Before editing properties, make a backup of iris-common.prop using the "dhconfig properties export" command.

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:

/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:

    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. After adding the users, add user1 to PrivilegedLargeGroup.

acl-1.png

The examples update a lot of properties. See viewing and changing configuration for details on how to change configuration files. Add the new and updated properties to the end of iris-common.prop so that they override default values.

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 iris-common.prop, add the following stanza to change the server's name to Large_Query_Host:

[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 guife, these examples edit existing ones. First, make a copy of the Persistent Query types file to ensure you can safely make changes.

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

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

iris.controller.configurationTypesXml.deephaven=CustomQueryConfigurationTypes.xml

Example - new server class

Follow the initial example setup if you haven't already.

Define a new server class called LargeQuery and assign query server 2 to it. In the new iris_controller stanza in iris-common.prop add the following property, and then import the file. The file now has following additional properties:

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:

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

Import your modified iris-common.prop file, and restart the controller and web service 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.

Example - console-only (no-PQ) server

Follow the initial example setup if you haven't already. Update iris-common.prop with the following changes:

  • 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-common.prop file now includes:

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
}

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:

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

Import your modified iris-common.prop file, and restart the controller and web service to pick up the changes.

Now, the users will see different server options.

  • Since user1 is a member of PrivilegedLargeGroup they see Large_Query_Host in the options for a new Code Studio, but it is unavailable for PQs.
  • The unprivileged user2 can neither start Code Studios nor create PQs on Large_Query_Host.

Example - combining PQ and console classes

Follow the initial example setup if you haven't already.

In iris-common.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-common.prop file now includes:

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.

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

Import your modified iris-common.prop file, and restart the controller and web service 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.

Example - restricting with console groups

Follow the initial example setup if you haven't already.

Edit iris-common.prop:

  • Modify the stanza to only 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-common.prop file now includes:

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:

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

Import your modified iris-common.prop file, and restart the controller and web service to pick up the changes.

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

  • 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.

Example - dispatcher restriction

Follow the initial example setup if you haven't already.

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-common.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:
/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-common.prop file now includes these properties, with a valid host-specific stanza instead of fqdn-1|ip-1:

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:

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

Import your modified iris-common.prop file, and restart the controller, web service, and both query servers 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>.

Restarting services

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

sudo -u irisadmin monit restart iris_controller
sudo -u irisadmin monit restart web_api_service

You also need to restart any impacted dispatchers on their nodes:

sudo -u irisadmin monit restart db_query_server

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

sudo -u irisadmin monit restart db_merge_server

Remove changed properties

Remember to remove any properties you added to iris-common.prop and re-import the file. You can also use the backup you made in the irisadmin home directory.