Configuration Overview

We are in the process of updating the information contained in this document. If you need assistance with the steps/processes described within, please contact Deephaven Support.

Most Deephaven server configuration is in the following locations:

  • /etc/sysconfig - This is where the Deephaven installation-specific files reside. Files under this path are not modified when a system update occurs. Of particular interest:
  • /etc/sysconfig/illumon.confs/illumon.iris.hostconfig - Also may be found via the soft-link /etc/sysconfig/illumon. This file controls the environment for each Deephaven server-side process (run via service iris <service name>). For example, see Adding JAR Directories to add customer JAR directories to the Deephaven installation with this file.
  • /etc/sysconfig/illumon.d/resources - Configuration files for each Deephaven server-side process (referenced by the hostconfig).
  • /etc/sysconfig/illumon.d/schema - Database schema files (XML). This is the recommended location for customer database schema files.
  • /etc/sysconfig/illumon.d/java_lib - Custom user and third-party Java libraries. "Extension" libraries placed here will be found on the classpath.
  • /etc/sysconfig/illumon.d/override - This path contains any class files that should override those contained in java_lib jars.
  • /etc/sysconfig/illumon.d/hotfixes - This path contains any jar files that should be used instead of those contained in the java_lib directories.
  • /usr/illumon - This is where Deephaven system files reside. These are not meant to be modified except when a new release occurs. The current release is referenced by the soft-link /usr/illumon/latest. While it should not be necessary to modify these files, it may be useful to be aware of the following:
  • /usr/illumon/latest/etc - System-wide internal configuration and defaults.
  • /usr/illumon/latest/java_lib - Deephaven system Java libraries.

Deephaven uses several formats of configuration data to control its operation. For core Deephaven services, there are three main forms of configuration:

  • Java properties files - These are text files, usually named with a .prop extension, that store key-value pairs. These are the largest stores of Deephaven configuration data, and control most of its operations and behavior. In a standard installation, all Deephaven properties have been consolidated into iris-common.prop, where any non-default property values should be stored, for any Deephaven process.
  • XML files - Some Deephaven processes and utilities use eXtensible Markup Language files. XML is a text format, but with specific requirements for delimitation of data elements, and with support for hierarchical representations of information.
  • YAML files - These files, named with a .yml extension, are used to configure the Data Routing Service. The YAML configuration file format centralizes the information governing the locations, servers, and services that determine how data is handled.
  • Other configuration files - These are also text files, but their format is specified by the applications that use them. The main example for Deephaven of this type of file is the hostconfig file that configures process startup for services. In this case, the file is actually a shell script.

There are also other configuration settings and other uses of the principal configuration files in Deephaven. The details of these are described in the following sections.

Properties Files

Properties files, or "prop" files, are Java constructs that provide applications with easy access to a collection of settings. Properties files can contain comments (starting with a pound/hash sign [#]) and key=value settings. Most Deephaven processes use the unified properties file iris-common.prop. (Note: some legacy cases may have different files per process.) This makes it easier to find the specific setting you need, and to synchronize processes that need to share a configuration value (e.g., a port number). It is stored in the /etc/sysconfig/illumon.d/resources/ folder.

Properties Files Syntax

Our modification of the standard Java properties file format allows for scoped sections of configuration that will only apply to certain processes. Deephaven's includefiles functionality allows other files to be included in the properties file, although these may not be included in a scope.

Example

The following demonstrates a scoped section for the Access Control List write server, which needs to use a user account with higher permissions than the standard ACL access credentials:

[service.name=db_acl_write_server|iris_db_user_mod] {
# Override the standard credentials and use a login with write permissions
MysqlDbAclProvider.user=aclwriter
MysqlDbAclProvider.passwordFile=acl_write_passphrase.txt
}

Deephaven's configuration file parser includes a set of language constructs, which we will explain here. Users may want to write their own properties files - for example, depending on the worker they are using - or create custom entries for certain processes. The existing file set up includes:

Scope definitions

A scope definition establishes the conditions that must exist for the configuration parser to read the subsequent lines until the end of the scoped region. A scope definition is of the form:

[property1.name=value1{|value2|...valueN}{, property2.name=valueX{|valueY…}}]

The minimum scope declaration is [property.name=value]. In this case, only if the system has a defined system configuration property with name property.name and a value equal to value will the subsequent lines be parsed.

It is possible to include multiple values for a given property, or to include multiple properties. To include multiple values, use the vertical pipe character "|" to distinguish between the different values. Note that this is not escaped; currently it is not possible to use property values with a vertical pipe in them for scoping purposes. This is an or operation; as long as at least one of the specified values matches the value of the specified system configuration property, the scope is considered to match the context.

Example:

[property1.name=value1|value2] → "Property1.name equals value1 OR value2."

It is also possible to include multiple property names within one scope. This is an and operation; each property name within a scope declaration must match at least one value from the defined list of available values. Undefined properties are considered to never match any scope; a property with a defined value of empty-string is also not permitted.

Example:

[property1.name=value1|value2,property2.name=valueX] → "property1.name equals value1 or value2, and property2.name equals valueX"

Whitespace is ignored for property names, and is ignored on the left side of values, but trailing whitespace is not ignored; standard Java properties do accept trailing whitespace, so this definition does as well.

Example:

[        property1.name    =  value1  ]  →  "property1.name" = "value1  "

A scope opener may be placed immediately after a scope definition on the same line. Anything else immediately after a scope definition is an invalid format.

Example:

[property1.name=value1] {

Scope openers

A scope opener is the open-curly-brace character "{". A scope opener defines the block of lines that will be read or ignored depending on whether or not the scope definition is matched. A scope opener may be placed on the same line as a scope definition, immediately after the scope definition (ignoring whitespace), or may be placed onto a line of its own.

A scope opener that does not follow a scope declaration is an invalid format. As "{" by itself is not a valid Java property declaration, this is consistent with the Java property specification, and no potential Java properties are thereby excluded.

A scope opener with no subsequent scope closer is an invalid format. Each scope section must be properly closed.

Scope closers

A scope closer is the end-curly-brace character "}". A scope closer defines the end of a block of lines that will be read or ignored depending on whether or not the scope definition is matched. A scope closer must be placed on a line by itself, except in the trivial case of a scope opener followed immediately by a scope closer with no declarations in between (in which case no action can happen and there is no point to making such a section).

A scope closer that does not follow a scope opener is an invalid format. As "}" by itself is not a valid Java property declaration, this is consistent with the Java property specification, and no potential Java properties are thereby excluded.

Anything following a scope closer will be parsed normally, including new property declarations or scope definitions.

The final keyword

A new language element is the final keyword. This keyword establishes that the immediately subsequent property declaration on the same line may not be further modified, whether within the same file or by some file that includes the file in which the final keyword appeared. This can be important if there are properties which are important to keep consistent between processes, ensuring that a key property cannot be overridden in a scope section or subsequent file.

The final keyword is used in the following form:

final <declaration>

The <declaration> is a standard Java property declaration of the form property.name{=value}. If no value is specified, then the property is assigned the value of empty-string. Anything after the final keyword is assumed to be part of the Java property declaration, so no other commands may be included on the same line as a final keyword.

Using the final keyword without a subsequent declaration is an invalid format; some property must exist to be declared final.

Note that the final keyword means that no property may be declared with the exact name 'final', with or without a value.

The finalize keyword

A new language element is the finalize keyword. This keyword establishes that the immediately subsequent property name may not be further modified, as though that property had been declared final. This can be useful if a property may have different values in different scopes, but after the sections have been parsed, whatever state the property is in should not be further changed.

The finalize keyword is used in the following form:

finalize <property.name>{, <property2.name>}

The <property.name> is a standard Java property name. As Java property names do not have leading or trailing whitespace, any whitespace around the property name will be trimmed. If the property being finalized did not previously exist, it is not created, and is not able to be created by anything later. This is a key difference from the use of the final keyword.

Note that everything on the line after the finalize keyword is treated as property names; no other commands may follow a use of the finalize keyword. The finalize keyword means that no property may be declared with the exact name 'finalize', with or without a value.

Using the finalize keyword without a subsequent property name is an invalid format; some property must be specified to be finalized.

The includefiles keyword

Deephaven property files may use the includefiles keyword to indicate that the contents of some other file should be included into the properties generated by the current file. iris-common.prop includes a reference of this sort to the iris-defaults.prop file, which contains default values for most Deephaven properties. The values from the current file will be considered to override the values from the included file, if both files include a property with the same name. includefiles explicitly must be the first non-comment, non-whitespace line in the .prop file, and may not be included in a scope, as shown in the example below:

includefiles=iris-defaults.prop,my-settings.prop

...

########## Iris DB RemoteQueryDispatcher settings ##########

RemoteQueryUtils.hostnameSuffixesToTruncateForDisplay=

RemoteQueryDispatcherParameters.name=default
RemoteQueryDispatcherParameters.host=localhost
RemoteQueryDispatcherParameters.queryPort=22013
RemoteQueryDispatcher.workerPort=22012
RemoteQueryDispatcher.workerServerPorts=23000-23999
RemoteQueryDispatcher.webPort=8084

Note that everything before the first equals sign is the key name, and everything after it is the value. If a value is a list, it is up to the application to define how that list should be formatted. Some Deephaven lists (such as tailer configuration file names and includefiles names) are comma-delimited, while others (such as schema paths) are semi-colon delimited.

A property name without an assigned value (such as the RemoteQueryUtils.hostnameSuffixesToTruncateForDisplay property above) will be treated as defining the property to have an empty value (i.e. an empty string). This is not the same as if the property does not exist in the properties files.

Only one includefiles directive is allowed in a properties file, but it can list multiple files to include, and these can, in turn, include other files.

There is no uniqueness requirement when adding a setting into a properties file. Instead, the properties collection that applications use within Java provides a "last in, wins" view of the settings. If a value is set multiple times, in a single properties file, or in multiple properties files linked with includefiles, whichever setting is applied last is the one that is used. Properties files are evaluated from top to bottom. Properties file entries are always case-sensitive for the property name, and often case-sensitive for the value.

The iris-defaults.prop properties file is delivered with the Deephaven installation. It provides default values for settings that can be changed, but rarely need to be, and also provides initial values for properties that will most likely need to be updated in production environments. These latter properties might work in a single-machine test environment, but need to be set differently when Deephaven is scaled to multiple servers. As mentioned above, the recommendation is to have a custom properties file (or, potentially, multiple custom properties files for different services, servers, or users) that includes iris-defaults.prop at the top, and then has its own specific settings further down that add to or override the inherited settings.

Java also allows for properties to be set for a process by passing them as JVM arguments. These are of the form:

-DpropertyName=propertyValue

Settings using -D are applied after properties file(s) settings, so they have the highest priority and override settings taken from properties files.

The properties file that a Deephaven process will load is set with a -D property as well:

-DConfiguration.rootFile=myIrisSettings.prop

The process will attempt to load this file (myIrisSettings.prop) from the Java classpath. This involves searching both in filesystem paths and also inside any JAR files that are included in the classpath. The first instance of a file in the classpath that matches the name will be loaded. Any included files encountered while loading properties file(s) will also be found from the classpath. This loading happens when the Deephaven Configuration class is initialized by the process. After that, all properties are kept in memory, so in most cases changes to properties file settings will not be picked up until the processes that use them are restarted.

The Property Inspector Utility

The Property Inspector class in the Deephaven Util JAR can inspect properties files or chains of properties files to provide visibility into what properties files are being included, where properties are set, and where properties are duplicated or overridden.

On a Deephaven server, this utility can be executed using iris_exec, as follows:

/usr/illumon/latest/bin/iris_exec property_inspector

Parameter Value

Description

-pf,--propertyFile <value>

(required) The starting properties file to read.

-pn,--propertyName <value>

(optional) A specific property to search for. Asterisks can be used as wildcard characters here.

-cs,--csv

(optional) Format output as CSV (for easy import into a spreadsheet).

-fm,--mode <value in {ALL (default), ALL_DUPLICATES, NON_DUPLICATES, FILE_DUPLICATES, COMPARE}>

(optional) Search mode. ALL_DUPLICATES will show properties whose value is set more than once anywhere in the chain of properties files, while FILE_DUPLICATES will only show properties whose values are set more than once in the same file. NON_DUPLICATES will show properties whose value is not set more than once anywhere in the chain of properties files. COMPARE, when used with the -in or -ex options (or both), will check whether specific properties are included in the chain of properties files. When using COMPARE, at least one of -in or -ex must be specified.

-out <value>

(optional) If specified, the output from the Property Inspector will be printed to the specified file. Otherwise, the output will be displayed in the console.

-in <value>

(optional) A file containing a list of property names that must be included at least once in the chain of properties files, when using the COMPARE mode.

-ex <value>

(optional) A file containing a list of property names that must not be included in the chain of properties files, when using the COMPARE mode.

Example:

The command below searches for all properties whose names start with IrisLogDefaults.: (Note: the "--" is required. It separates arguments to iris_exec from arguments to property_inspector. See: Schema Inference.)

/usr/illumon/latest/bin/iris_exec property_inspector -- -pf iris-console.prop -pn IrisLogDefaults.*

When the command above is run, the following results are generated (edited for brevity/clarity):

Searching for: IrisLogDefaults.*, starting with file: "iris-console.prop"

Name: IrisLogDefaults.useMainClassNameForLogs Value: true --- Line: 562 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.logLevel Value: INFO --- Line: 563 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.logType Value: STANDARD_LOG_CREATOR --- Line: 564 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.writeDatabaseProcessLogs Value: false --- Line: 565 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.writeDatabaseAuditLogs Value: false --- Line: 566 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.captureLog4j Value: true --- Line: 567 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.captureSysout Value: false --- Line: 568 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.captureSyserr Value: false --- Line: 569 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.useLogAggregatorService Value: false --- Line: 570 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.useDynamicPartitions Value: false --- Line: 571 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.aliveMessageSeconds Value: 0 --- Line: 572 --- File: iris-defaults.prop --- Scope: []
Name: IrisLogDefaults.binaryLogTimeZone Value: --- Line: 573 --- File: iris-defaults.prop --- Scope: []

See also: How do I use Property Inspector to search for properties within the unified config files?

Configuration Files

Configuration files are text files whose format varies depending on the requirements of the applications that use them. The main use of conf files in Deephaven is the hostconfig file, which is used in all configurations.

Hostconfig

The hostconfig file is normally located under /etc/sysconfig/illumon.confs, and named illumon.iris.hostconfig. The hostconfig file is sourced (run) by another bash script, which means it supports bash scripting to make if/then and case statement type decisions. This file provides information needed to start and monitor Deephaven processes. It contains details that must be passed to the processes as they are started, such as how much memory should be allocated, what account they should run under, and what properties file they should use.

Whenever a Deephaven service is started by Monit, it uses the Deephaven launch script to start the service, which sources the hostconfig file. For more information on Monit Services, see the Monit Manual.

For example, the following is a section of a hostconfig file that configures the Deephaven Controller process:

iris_controller)
   CONFIGFILE=iris-common.prop
   EXTRA_ARGS="-j -Xms4G -j -Xmx4G -j -Xmn32m -j -Dservice.name=iris_controller"
   RUN_AS=irisadmin
   WORKSPACE=/db/TempFiles/$RUN_AS/$proc
   ;;

In this case, the process will be directed to use the iris-common.prop properties file, run under the irisadmin account, and be allocated 4GB of initial, and maximum, heap space, with 32MB of Eden space. In the EXTRA_ARGS line, the -j indicates to the Deephaven scripts that these are parameters to be passed through directly to the JVM.

If needed, additional processes to be managed by Monit can be added to the hostconfig file. If an existing process needs changes to allocated memory or other startup properties, those changes must be made in this file. See the Deephaven Operations Guide for additional documentation on Deephaven's use of Monit.

Other Configuration Files

Most other configuration files in Deephaven are text files that contain lists of values for various purposes:

1. db_rqc_default_class_push_list.txt

This is the default file for listing classes that exist in the classpath of the client system and should be pushed to the class cache of the query worker at startup. An alternate file for this purpose can be specified by setting the property RemoteQueryClient.defaultClassPushList.

In general, classes pushed from this file will be classes that the user is developing and needs to test, or classes that only one or a very few users need. Production classes that are to be usable by most users should be deployed to query servers by building them into JARs and placing these JARs under /etc/sysconfig/illumon.d/java_lib.

2. Default files

These are the default files that contain a list of Java classes that are added to the query library used by Deephaven queries:

default_static_imports.txt

default_class_imports.txt

default_package_imports.txt

These file names can be overridden by the properties:

IrisDB.queryLibrary.defaultPackageImportList=

IrisDB.queryLibrary.defaultClassImportList=

IrisDB.queryLibrary.defaultStaticImportList=

3. /etc/sysconfig/illumon.d/resources/authusers.txt

The set of Deephaven users, groups and ACLs are stored in MySQL database.  Customers can choose to use LDAP for storing user credentials.  In some situations, customers may wish to maintain the set of Deephaven users in a local file by setting the property:

authentication.server.localusers.enabled=true

In this case, the authusers.txt file contains the list of Deephaven users in htpasswd format.

4. /etc/sysconfig/illumon.d/resources/superusers.txt

This file lists the local superusers as long as the property is set as follows:

authentication.server.localsuperusers.enabled=true

5. /etc/sysconfig/illumon.d/resources/dsakeys.txt

This filename can be overridden by the property:

authentication.server.authorizedkeys.file=...

The dsakeys.txt file lists the DSA keys for Deephaven users as long as the property is set as follows:

authentication.server.authorizedkeys.enabled=true

DSA keys are used in place of passwords for non-interactive users in scripts or batch jobs or delegated API calls. See: Database Authentication to learn more.

6. /etc/sysconfig/illumon.d/resources/db_acl_write_server_passphrase.txt and /etc/sysconfig/illumon.d/resources/db_acl_ro_passphrase.txt

These default files contain the passwords for the MySQL database, used by Deephaven's internal processes when reading or writing user or ACL information.

YAML Files

YAML is a human-readable data serialization language commonly used for configuration files. In Deephaven, a YAML file (which use the extension .yml) is used to configure the Data Routing Service.

See Data Routing Service Configuration via YAML for detailed information.

XML Files

XML (eXtensible Markup Language) files are also text files, and nominally human-readable, but, unlike configuration files and properties files, XML files include more requirements around how data is formatted and delimited. The main structure of XML files is based around elements, which can be single line or multi-line, and which can encapsulate other elements to form hierarchies. Elements can also contain embedded text data directly as content and/or in the form of named attributes.

The main places where XML is used to store Deephaven configuration settings are:

  • Tailer configuration files, which tell a tailer what files and paths it should monitor.
  • Import/Merge script configuration files, which provide one way of automating frequently executed data import and merge operations.
  • Schema files, each of which is an XML file without a root element.
  • Workspace files, which persist the layout of a Deephaven client application (tabs, queries, etc).

See the Tailer XML Configuration Parameters and Schemas sections in the Importing Data guide for detailed information.

Environment Variables

Environment variables are used to set some of the global configuration for Deephaven, most commonly for bin utilities, which rely on JAVA_HOME, and also for the import/merge scripts.

In order to use Deephaven tools like iriscat (/usr/illumon/latest/bin/iriscat), JAVA_HOME must first be set to point to an installation directory that contains a Java 8 installation. This path will include a bin subdirectory that contains a Java runtime executable. Typically, this will be set to /usr/java/latest or /usr/java/latest-64. On Linux, this can be checked by running:

export | grep JAVA_HOME

It can be set similarly with:

export JAVA_HOME=path_to_java

The environment variable CUSTOMER_JAR_DIR can be used to add locations in which Deephaven will search for customer JAR files. See Adding JAR Directories for further details.

Other environment variables, primarily used by the import/merge scripts, are covered in Appendix A of the Deephaven Importing Data guide.

Last Updated: 28 February 2020 12:20 -05:00 UTC    Deephaven v.1.20200121  (See other versions)

Deephaven Documentation     Copyright 2016-2020  Deephaven Data Labs, LLC     All Rights Reserved