Cloud On-prem
2.9
latest3.43.33.23.13.02.9
imply.io
Menu
Close

Imply UI config

The Imply UI server can read a config YAML file via the --config parameter where you can specify the server specific options described below. Some (but not all) of these options are also available through the command line. Any option specified in the command line will override its equivalent in the config.

# verbose (Boolean)

Indicates that Imply should run in verbose mode. This will log all the database queries done by Imply UI.

# varDir (string)

The var directory to be used by Imply

# licenseFile (string)

The license file to be used by Imply

# port (number)

The port the server should run on. Defaults to 9095.

# serverHost (string)

The host that the server will bind to. Defaults to all hosts.

# serverRoot (string)

A custom path to act as the server string. Default: ''.

Setting serverRoot to ui will tell the server to serve content from http://your-host/ui.

# healthRoute (string)

The health route that returns 200. Can be used in a load balancer to check that the instance is healthy. Defaults to health.

# serverHttpsOptions (object)

A custom object that will be passed to the node's tls.createSecureContext and will cause the server to listen on an https port. Use this option to enable TLS based serving.

Example:

serverHttpsOptions:
  cert: |
    -----BEGIN CERTIFICATE-----
    MIID/DCCAmSgAwIBAgIQa/oVbFwIQU6UP/cn9jwb0DANBgkqhkiG9w0BAQsFADBu
    ...omitted...
    bWbmFE68ei4p1mVynelYjpSwesnFrIJAvtoqx/Z8ubiExumqMRp5juoH0wHPHgVe
    UFRVFdnYcRaoYHHLw6xWgA==
    -----END CERTIFICATE-----
  key: |
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCx7zU0LVHdS7S+
    ...omitted...
    ODOBKSs+xekw3ioN2eFse/sovLN4icpXSBE1G5hl2zfBNEg5E3r5PtTwu8BRMBc2
    M4ZzeSarlzOFZvMaTvLM36Q=
    -----END PRIVATE KEY-----

Note that when you are writing out a PEM encoded certificate inline you must use the | multiline starter to preserve the newlines which are needed for the PEM format.

For more information about how to generate certificates with OpenSSL see the TLS documentation.

# servingMode ('single' | 'clustered')

Indicates whether the server is running in standalone mode (single) or clustered mode (clustered). Setting this option to clustered mode will enable ZooKeeper (see below). Default to clustered.

Available since 2.9.18.

# zookeeperConnection (string)

A standard ZK connection string. Only needs to be configured in clustered servingMode.

Example: 127.0.0.1:2181,127.0.0.1:2182,127.0.0.1:2183,127.0.0.1:2184/moon

Available since 2.9.18.

# zookeeperPath (string)

The path within which to create the ZK objects. Default to /pivot.

Available since 2.9.18.

# ownHostname (string)

For rolling updates to work, hostname needs to be routable, if the OS reported hostname is not routable you can override it with this setting. Defaults to the OS reported hostname.

Available since 2.9.18.

# disableXsrfLoginCheck (boolean)

Disable the extra header used for XSRF protection in the login screen. This should only be set to true if doing a rolling deployment from 2.9.8 or below to 2.9.9 or above.

# enableApiEndpoint (boolean)

Allow access via the metadata API. Enabling this flag also enables the token configuration view in the UI.

# secureCookie (boolean)

Instructs the server to send the cookie as secure. You should set this if the end connection goes over https such as if serverHttpsOptions is set or if there is an TLS terminator in use.

# keepAliveTimeout (number)

Set the keep alive timeout on the http connections.

# requestLogFormat (string)

A morgan string representing how the request logs will be formatted. For more info about possible values see the Morgan API docs.

# iframe ("allow" | "deny")

Specify whether embedding within and iframe will be allowed. If set to deny, the server will set the following headers:

X-Frame-Options: "DENY"
Content-Security-Policy: "frame-ancestors 'none'"

This is used to prevent Clickjacking. Learn more about it on MDN.

# trustProxy ("none" | "always")

Should the server trust the X-Forwarded-* headers.

# strictTransportSecurity ("none" | "always")

Specify that the server should set the StrictTransportSecurity header.

# keepAlivePingInterval (number)

How often (in ms) to send pings on long running queries to make sure the connection stays open. Defaults to 5000.

This is helpful with certain types of gateways and browsers that otherwise can timeout and close the connection. Note that once the first keep alive is sent the status code will be set as 200 even if the request will eventually fail.

# sessionStore

The store config that defines where the session information for the logged in users will be stored. Only used when userMode is native-users, external-users, or ldap-authentication.

Must have a key storageType set to either redis, mysql, pg, or sqlite and the rest of the object can have any options that can be passed to connect-redis (for storageType Redis) or connect-session-knex (for the other options).

Example (MySQL):

sessionStore:
  storageType: 'mysql'
  tablename: 'imply_sessions'
  connection:
    host: 'awesomeco.3242452413.us-east-1.rds.amazonaws.com'
    user: 'root'
    password: 'super-secret-1234'
    database: 'my_db'

Example (PostgreSQL):

sessionStore:
  storageType: 'pg'
  tablename: 'imply_sessions'
  connection:
    host: 'pghost'
    user: 'root'
    password: 'super-secret-1234'
    database: 'my_db'

Example (SQLite):

sessionStore:
  storageType: 'sqlite'
  connection: 'path-to/session.sqlite'

Example (MySQL + TLS):

sessionStore:
  storageType: 'mysql'
  tablename: 'imply_sessions'
  connection:
    host: 'awesomeco.3242452413.us-east-1.rds.amazonaws.com'
    user: 'root'
    password: 'super-secret-1234'
    database: 'my_db'
    ssl:
      ca: |
        -----BEGIN CERTIFICATE-----
        MIID/DCCAmSgAwIBAgIQa/oVbFwIQU6UP/cn9jwb0DANBgkqhkiG9w0BAQsFADBu
        ...omitted...
        bWbmFE68ei4p1mVynelYjpSwesnFrIJAvtoqx/Z8ubiExumqMRp5juoH0wHPHgVe
        UFRVFdnYcRaoYHHLw6xWgA==
        -----END CERTIFICATE-----

Where the contents of the ssl key is in the same format as tls.createSecureContext. Note that if you are connecting to an AWS RDS you can simply set ssl: "Amazon RDS".

# stateStore

The location, format and other options of the state store. This is an object that has the following keys:

Example:

stateStore:
  type: 'mysql'
  tablePrefix: 'awesome-state-'
  pool: { min: 2, max: 30 }
  acquireConnectionTimeout: 20000
  connection:
    host: 'awesomeco.3242452413.us-east-1.rds.amazonaws.com'
    user: 'root'
    password: 'super-secret-1234'
    database: 'my_db'

Example with a secure connection to the DB instance

stateStore:
  type: 'mysql'
  tablePrefix: 'awesome-state-'
  pool: { min: 2, max: 30 }
  acquireConnectionTimeout: 20000
  connection:
    host: 'awesomeco.3242452413.us-east-1.rds.amazonaws.com'
    user: 'root'
    password: 'super-secret-1234'
    database: 'my_db'
    ssl:
      ca: |
        -----BEGIN CERTIFICATE-----
        MIID/DCCAmSgAwIBAgIQa/oVbFwIQU6UP/cn9jwb0DANBgkqhkiG9w0BAQsFADBu
        ...omitted...
        bWbmFE68ei4p1mVynelYjpSwesnFrIJAvtoqx/Z8ubiExumqMRp5juoH0wHPHgVe
        UFRVFdnYcRaoYHHLw6xWgA==
        -----END CERTIFICATE-----

Where the contents of the ssl key is in the same format as tls.createSecureContext. Note that if you are connecting to an AWS RDS you can simply set ssl: "Amazon RDS".

# maxUrlEntries (number)

Default: 50000. The maxim number of saved URL states to store. Once this limit is reached the oldest URLs would be cleaned up.

# initialSettings (object)

A free form object that can be used to seed the settings.

# userMode

Imply can operate in several user access modes determined by the userMode in the config.yaml file. You have to restart the server in order to affect a change to the config.

The access modes are:

# defaultUserPermissions

An array of objects representing the permissions that will be assigned if running in userMode: default-user.

The is that all the possible permissions would look like effectively giving the default user super-admin access:

defaultUserPermissions:
  - { name: 'ManageUsers' }
  - { name: 'ConfigureLookAndFeel' }
  - { name: 'ManageConnections' }
  - { name: 'ManageDatasets' }
  - { name: 'AdministerDataCubes' }
  - { name: 'AdministerDashboards' }
  - { name: 'ChangeDataCubes' }
  - { name: 'ChangeDashboards' }
  - { name: 'SeeOtherUsers' }
  - { name: 'AccessSQL' }
  - { name: 'AccessVisualization' }
  - { name: 'AccessDatasets' }
  - { name: 'QueryRawData' }

# headerSubsetFilters

Possible values are: disable (default), allow, require In userMode: header-user enforce an extra set of headers passed in via a header

# headerSubsetFiltersInExport

Possible values are: normal (default), pack-in-token In userMode: header-user pack the header filters into the export token

# ldapOptions

The options to pass to the LDAP server (only used when userMode: ldap-authentication). For a detailed explanation of all the possible configurations see the node-ldapauth options.

An extra options (that are not part of the ldapauth options) are:

The values of the rolesKey parameter (falling back to defaultRole) will be looked up and mapped to Imply UI roles by the External ID which can be configured in the role edit UI.

Example with roles taken from a memberOf attribute:

ldapOptions:
  url: 'ldap://ldap_host:389' # The URL of the LDAP
  bindDN: 'cn=admin,dc=imply,dc=io'
  bindCredentials: 'JonSn0w'
  searchBase: 'ou=people,dc=imply,dc=io'
  searchFilter: '(uid={{username}})'
  rolesKey: 'memberOf'

Example with roles taken a separate group search:

ldapOptions:
  url: 'ldap://ldap_host:389'
  bindDN: 'cn=admin,dc=imply,dc=io'
  bindCredentials: 'JonSn0w'
  searchBase: 'dc=imply,dc=io'
  searchFilter: '(uid={{username}})'
  groupSearchBase: 'ou=groups,dc=imply,dc=io'
  groupSearchFilter: '(member={{dn}})'
  groupSearchAttributes: ['dn', 'cn']
  groupKeyAttribute: 'dn'

Before setting these options in the config please confirm that they work using the ldapsearch command.

ldapsearch -x -h ldap_host -p 389 -b "ou=people,dc=imply,dc=io" -D "cn=admin,dc=imply,dc=io" -w "JonSn0w" "(uid=some_username_that_exists)"

Update the parameters as necessary. If ran from the same machine that will run the Imply UI process this should authenticate and return a list of users.

# superAdminUser

The username of one LDAP user that will be granted super admin access. This property is useful for bootstrapping a server with LDAP users. The user configured here can go in and set up all the roles and permissions as needed.

# defaultRole

Set this role is no role was attached to the user from LDAP.

# roleAuthority

Determines weather Imply or LDAP is in charge of setting the user roles. Can have values of native and ldap. Default: native.

When a user logs into Imply (via LDAP) for the first time their role is determined and registered in Imply by reading the rolesKey key (as specified in the ldapOptions) from the returned LDAP record. If the role is not set then the role defaults to the defaultRole.

On subsequent logins the role calculation behavior differs based on the setting of the roleAuthority:

# appName (string)

Changes the name on the 'app' on the login screen.

# userNameLabel

Set the user name label in the login route (default: "Email"). Set this if you are using native-users or ldap-authentication user mode and the users are meant to login with something other than their email.

# mailTransportOptions

If configured will enable the ability to email newly created users an onboarding link. For all possible configurations see nodemailer's options for SMTP and other transports

Basic SMTP options:

port: defaults to 587 if is secure is false or 465 if true host: defaults to ‘localhost’ auth: defines authentication data (see authentication section below) authMethod: defaults to ‘PLAIN’

# defaultSender

An email address that will appear on the Sender: field (always prefer from if you’re not sure which one to use)

# suppressUserIcon (boolean)

Suppress the user icon and menu in the top right corner of every view.

# queryCache

Sets the server side query cache options.

The possible types are:

# purePivot

You can set purePivot: true to get the server to direct users straight into the Visualize mode (bypassing the home screen)

# latestUrl

A URL for checking the latest version. Defaults to https://static.imply.io/release/LATEST.txt. The file should contain a plain version text like 2.6.7. Update checks can be disabled by setting latestUrl to none

# decorators

A set of key-value pairs defining the Druid decorator modules by name.

Example:

decorators:
  basicAuth: './basicAuthDecorator.js'
  union: './unionDecorator.js'
Overview

Tutorial

Deploy

Manage Data

Query Data

Visualize

Configure

Special UI Features

Imply Manager

Misc