Skip to main content

Pivot server config

This information applies to on-prem Pivot instances only.

You can configure the Pivot server by modifying the Pivot configuration file config.yaml. The location of the file depends on the details of your implementation. For example:

$IMPLY_HOME/conf/pivot/config.yaml

$IMPLY_HOME/conf-quickstart/pivot/config.yaml

where $IMPLY_HOME is the location of your Imply installation.

Pivot reads the configuration when it starts up. If you modify any properties in the file you must restart Pivot in order for the changes to take effect.

Command line overrides​

You can run Pivot directly and use the --config option to specify an alternative config file.

You can also override the following Pivot properties at the command line:

PropertyCommand line option
licenseFile--license
port--port
serverHost--server-host
serverRoot--server-root
userMode--user-mode
verbose--verbose

Example:

dist/pivot/bin/pivot --config conf/pivot/config-test.yaml --port 9096

See the following sections for more information on configuration options:

Pivot server configuration reference​

You can specify the following configuration options in the config.yaml file.

appName​

Determines the name of the app on the login screen.

  • Type: String
  • Default: Imply

decorators​

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

  • Type: Object

Example:

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

defaultRole​

Default role to attach to LDAP users. See ldapOptions for more information.

defaultUserPermissions​

The default roles Pivot assigns to users when userMode is set to default-user. See userMode for more information.

  • Type: Array of objects
  • Value: One or more of the following user roles:
    • ManageUsers
    • ConfigureLookAndFeel
    • ManageConnections
    • ManageDatasets
    • AdministerDataCubes
    • AdministerDashboards
    • ChangeDataCubes
    • ChangeDashboards
    • SeeOtherUsers
    • AccessSQL
    • AccessVisualization
    • AccessDatasets
    • QueryRawData

See User roles for information on the individual roles.

The following example assigns all of the above roles, which is the same as enabling 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' }

disableXsrfLoginCheck​

Disables the extra header used for cross-site request forgery (XSRF) protection in the Pivot login screen. You should only set this property to true if you're doing a rolling deployment from 2.9.8 or below to 2.9.9 or above.

  • Type: Boolean
  • Default: false

enableApiEndpoint​

Allows access via the Pivot API. This flag also enables the token configuration view in the Pivot UI. The token is persistent—it doesn't time out or roll over.

  • Type: Boolean

featureFlagsAvailabilityThreshold​

Determines the level of preview features that appear in the Feature flags tab, where features can be enabled in the Pivot UI. Use in conjunction with featureFlagsDefault.

  • Type: String
    • alpha: Alpha and beta features appears.
    • beta: Only beta features appear.
    • none: No preview features appear.
  • Default: alpha

See Feature flags for more information.

featureFlagsDefault​

Determines whether to enable preview features in the Pivot UI. Use in conjunction with featureFlagsAvailabilityThreshold.

  • Type: String
  • Value: enabled or disabled
  • Default: disabled

See Feature flags for more information.

healthRoute​

The health route that returns a 200 OK status code. You can use this property in a load balancer to check that the instance is healthy.

  • Type: String
  • Default: health

helpCenterHref​

Pivot link to the help center. If not set, the help centre link does not display in Pivot.

  • Type: String

iFrame​

Specifies whether Pivot allows embedding within an iFrame.

  • Type: String
  • Value: allow or deny

If set to deny, the Pivot server sets the following headers:

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

This helps to prevent Clickjacking. Learn more about X-Frame-Options on MDN.

For more information, see the imply-iframe-examples repository.

initialSettings​

A free form object that you can use to define Pivot's initial state on startup. Once the state store is populated, Pivot ignores this object.

  • Type: Object

keepAlivePingInterval​

Defines how often to ping long-running queries to ensure the connection stays open.

It can be useful to set this property with certain types of gateways and browsers that could otherwise time out and close the connection. Note that once the first keep alive is sent the status code is set to 200 OK, even if the request eventually fails.

  • Type: Number (milliseconds)
  • Default: 5000

keepAliveTimeout​

Sets the keep alive timeout on HTTP connections.

  • Type: Number

ldapOptions​

The options to pass to the LDAP server. Only applies when userMode is set to ldap-authentication. See userMode and Manage users with LDAP for more information.

  • Type: Object
  • Value: You can provide any of the LdapAuth configuration options plus the following options:
    • rolesKey: LDAP key from which to receive role information. The key value can be a string or an array of strings—strings split on (,). The value is mapped to Pivot roles by the External ID which can be configured in the role edit UI. Defaults to defaultRole.
    • groupKeyAttribute: LDAP key of the group to map to the external role name of the Imply user role. Defaults to dn.

Example with roles taken from a memberOf attribute:

ldapOptions:
  url: 'ldap://ldap_host:389'
  bindDN: 'cn=admin,dc=imply,dc=io'
  bindCredentials: 'my-password'
  searchBase: 'ou=people,dc=imply,dc=io'
  searchFilter: '(uid={{username}})'
  rolesKey: 'memberOf'

Example with roles taken from a separate group search:

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

Before you configure this property, use the LDAP search tool to confirm that your configuration works. For example:

ldapsearch -x -h ldap_host -p 389 -b "ou=people,dc=imply,dc=io" -D "cn=admin,dc=imply,dc=io" -w "my-password" "(uid=example-username)"

licenseFile​

The license file Pivot uses.

  • Type: String

linkHostName​

The hostname in links that appear to users in Pivot alerts and reports. Populates the link token that may appear in scheduled report and alert templates.

  • Type: String

loginDisclaimerContent​

Text to display on the Pivot login screen, below the username and password fields. You can use this property to add privacy or liability disclaimers.

  • Type: String

maxAlertOccurrenceEntries​

The maximum number of alert occurrences to store. Once the limit is reached, Pivot purges the oldest alerts.

  • Type: Number
  • Default: 500000

maxReportInstanceEntries​

The maximum number of reports to store. Once the limit is reached, Pivot purges the oldest reports.

  • Type: Number
  • Default: 500000

maxTotalQueriesForExports​

Specifies the maximum number of queries for a single download or export request. For a fast or iterative query download in a multi-tenant application, you might need to increase this number if your data has more than 10 columns. See Configuring aggregated data download limits for more information.

  • Type: Number
  • Default: 5000

maxUrlEntries​

The maximum number of saved URL states to store. Once the limit is reached, Pivot purges the oldest URLs.

  • Type: Number
  • Default: 5000

oidcOptions​

The options to pass to the OIDC server. Only applies when userMode is set to oidc-authentication. See userMode and Manage users with OIDC for more information.

  • Type: Object

ownHostname​

For rolling updates to work, the hostname must be routable. If the OS-reported hostname is not routable, you can use this property to override it.

  • Type: String
  • Default: OS-reported hostname

port​

The port the Pivot server runs on.

  • Type: Number
  • Default: 9095

queryCache​

Determines the server-side query cache options.

  • Type: Object

Object properties:

  • type:
    • none: No query cache.
    • local: (default) Cache queries locally, per node.
    • memcached: Memcached server details. Use if you are running more than one query server.
      • servers: Memcached server or servers to connect to.
      • options: Connection options for the memcached server fallbacks.
      • lifetime: Time period, in seconds, that the cache entry persists for.
      • prefix: Key prefix to be used if the memcached server is shared with other services.

Examples:

queryCache:
  type: 'none'
queryCache:
  type: memcached
  servers:
    - my.memcached1.internal:11211
    - my.memcached2.internal:11211
    - my.memcached3.internal:11211

requestLogFormat​

A morgan string representing Pivot formats request logs. For more information see the Morgan API docs.

  • Type: String

roleAuthority​

Determines whether Pivot (native) or LDAP sets user roles.

  • Type: String
  • Value: native or ldap
  • Default: native

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

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

  • native: The user's role is set to the same role that was previously registered in Pivot. Any changes to the user's rolesKey in the LDAP record are ignored.
  • ldap: The user's role is taken from the LDAP record as described above (defaulting to defaultRole) and registered on every login.

secureCookie​

Instructs the Pivot 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 a TLS terminator in use.

  • Type: Boolean

serverHost​

The host the Pivot server binds to.

  • Type: String
  • Default: All hosts

serverHttpsOptions​

A custom object to pass to the node's tls.createSecureContext property. Instructs the Pivot server to listen on an HTTPS port. Use this option to enable TLS-based serving.

  • Type: Object

Example object:

serverHttpsOptions:
  cert: $read_text(../cert.pem)
  key: $read_text(../key.pem)

You can also define certificates inline, for 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 write out a PEM encoded certificate inline you must use the | multiline starter to preserve the newlines the PEM format requires.

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

serverRoot​

A custom path to act as the server string. Set to ui to tell the Pivot server to serve content from http://example-host/ui.

  • Type: String
  • Default: ''

servingMode​

Indicates whether the Pivot server is running in standalone mode (single) or clustered mode (clustered).

Set to clustered to ensure that no other options are set in a way that would not work in a clustered setup, such as using a local state store.

  • Value: single or clustered
  • Default: clustered

sessionStore​

Defines where Pivot stores session information for logged-in users. Only applies when # userMode is set to native-users, external-users, or ldap-authentication.

  • Type: Object

The object must include the storageType property set to either redis, mysql, pg, or sqlite.

The rest of the object defines properties to pass to connect-redis (for storageType Redis) or connect-session-knex (for the other storage types).

MySQL example:

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

PostgreSQL example:

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

SQLite example:

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

MySQL + TLS example:

sessionStore:
  storageType: 'mysql'
  tablename: 'imply_sessions'
  connection:
    host: 'exampleco.3242452413.us-east-1.rds.amazonaws.com'
    user: 'root'
    password: 'example-secret-1234'
    database: 'my_db'
    ssl:
      ca: $read_text(../cert.pem)

Provide the ssl key in the same format as tls.createSecureContext. If you're connecting to an AWS RDS you can set ssl: "Amazon RDS".

settingsExportLimit​

Sets the maximum number of data cubes and dashboards a user can export using the Export option. Set to zero to disable the limit.

  • Type: Number
  • Default: 100

showHeader​

Controls visibility of data cube and dashboard headers.

  • Type: String
  • Value: One of:
    • show: Always display headers.
    • hide: Never display headers.
    • show-if-top-level: Hide headers if Pivot is embedded in an iFrame. Headers still show in the Pivot UI.
  • Default: show

stateStore​

Defines state store properties including location and format.

  • Type: Object

Object properties:

  • type: Store type. One of: mysql, pg, sqlite.
  • connection: Connection string or filename (SQLite).
  • tablePrefix: Optional prefix string for table names. Defaults to pivot-store-.
  • pool: Optional min and max number of connections in the pool. Defaults to { min: 2, max: 10 }.
  • acquireConnectionTimeout: Optional connection timeout in milliseconds. Defaults to 60000. The most common cause of connection timeouts is using up all of the pool for transaction connections and then attempting to run queries outside of transactions while the pool is still full.

Example:

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

Example with a secure connection to the database instance:

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

Provide the ssl key in the same format as tls.createSecureContext. If you're connecting to an AWS RDS you can set ssl: "Amazon RDS".

strictTransportSecurity​

Specifies whether the Pivot server sets the Strict-Transport-Security response header.

  • Value: none or always

superAdminUser​

An LDAP user to grant super admin access. This property is useful for bootstrapping a server with LDAP users. This user can log in to Pivot and set up all required roles and permissions.

  • Type: String

suppressUserIcon​

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

  • Type: Boolean
  • Default: false

trustProxy​

Specifies whether the Pivot server trusts X-Forwarded-* headers.

  • Value: none or always

userMode​

Pivot's user access mode.

  • Type: String
  • Default: all-admin
  • Value: One of the following:
    • default-user: No login screen. Provides all users with privileges defined by defaultUserPermissions.
    • all-users: No login screen. Provides all users with user privileges—they have no access to the settings view and they can't modify clusters. Users can create, modify, and delete data cubes and dashboards.
    • all-dashboard-only-users: No login screen. Provides all users with dashboard-only-user privileges—they have no access to the settings view and can't modify clusters or data cubes. Users can create, modify, and delete dashboards.
    • all-admin: No login screen. Provides all users with admin privileges—they can access the settings view and can modify clusters, data cubes, and dashboards.
    • native-users: Login screen. All users must log in with a username and password. If you activate this user mode and no users exist, Pivot creates a default Super Admin user with User ID admin@admin.com and password password. Log in with this user and navigate to the Users tab in the settings view to create additional users. You can generate an invitation link for a user to set their own password. Super Admin users can create, modify, and delete users. Note that in native-users mode all users have access to the same data. Schema editing privileges differentiate admin users from non-admin users.
    • ldap-authentication: You can define an LDAP server for external user authentication. Set the ldapOptions accordingly.
    • oidc-authentication: Configure Pivot for single sign-on using an external OIDC identity provider. See oidcOptions for more information.

userNameAuthority​

Determines whether Pivot (native) or OIDC (external) populates name fields in Pivot. Only applies when userMode is set to oidc-authentication. Set to native when you want to obtain name details from Pivot instead of OIDC.

See userMode and Manage users with OIDC for more information.

  • Type: String
  • Value: native or external
  • Default: external

userNameLabel​

Determines the username label on the login screen. You can change the default label if you've set userMode to native-users or ldap-authentication and users log in with credentials other than email address.

  • Type: String
  • Default: Email:

verbose​

Instructs Pivot to run in verbose mode, which logs all database queries Pivot performs.

  • Type: Boolean

varDir​

The var directory Pivot uses.

  • Type: String

zookeeperConnection​

A standard Zookeeper connection string. Only applies when servingMode is set to clustered.

  • Type: String

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

zookeeperPath​

Path to the location for Zookeeper objects.

  • Type: String
  • Default: /pivot

Configure email options​

You can configure the following properties to enable Pivot to send email.

You must specify both mailTransportOptions and defaultSender.

mailTransportOptions​

For all possible configurations see nodemailer's options for SMTP and other transports.

You can also specify one of nodemailer's well-known SMTP services in the service field which will automatically set host and other SMTP fields depending on the service value.

Mailtrap example:

mailTransportOptions:
  host: 'smtp.mailtrap.io'
  port: 587
  secure: false
  auth:
    user: example-username
    pass: example-password

Amazon SES example—make sure you set the correct region:

mailTransportOptions:
  transportType: ses
  region: eu-central-1

Additional account configuration may be required to use Gmail as your provider. For more information, see using Gmail with nodemailer.

Gmail example:

mailTransportOptions:
  service: 'gmail'
  auth:
    user: example-username
    pass: example-password

defaultSender​

The email address that appears in the Sender: field.

Example: 

defaultSender: '"Imply (testing)" <no-reply@imply.io>'

emailTemplates​

Defines a custom email template.

Example:

emailTemplates:
  - name: 'alert'
    headers:
       X-Auto-Response-Suppress: All
       X-Priority: High
    subject: '[${severity}] ${title} has triggered'
    html: |
      <h2>Alert: ${title}</h2>
      <p>
        ${summary}
      </p>
      <p>
        Learn more: http://localhost:9095${link}
      </p>

All Pivot emails contain the X-Auto-Response-Suppress: All header by default. If you configure a custom email template, you must include this header if you want to suppress responses to Pivot emails.

See Configure an alert email for more information on the default template.

Reference environment variables​

You can reference environment variables inside the Pivot server configuration file.

Using the following example stateStore object, Pivot resolves %{MYSQL_CONNECTION}% to the value of the MYSQL_CONNECTION environment variable.

stateStore:
  type: 'mysql'
  connection: 'mysql://%{MYSQL_CONNECTION}%:3306/pivot'
  tablePrefix: 'pivot-'

Reference files​

You can reference files in the Pivot server configuration file.

For example, the following emailTemplates specification resolves the html value to the contents of invite.html.

emailTemplates:
  - name: invite
    subject: Create your pivot account
    html: $read_text(../templates/invite.html)

Pivot resolves file paths relative to the location of the configuration file. You can also use $read_json and $read_yaml for files containing JSON and YAML respectively.

Override configuration​

You can override previously specified Pivot server configuration values. Specify overrides as JSON or YAML.

For example, specifying the following two configuration files:

fixedConnections:
  - name: druid
    title: Local Druid
    type: druid
    host: localhost:8888
    timeout: 40000
fixedConnections.0.timeout: 50000

results in the following configuration:

fixedConnections:
  - name: druid
    title: Local Druid
    type: druid
    host: localhost:8888
    timeout: 50000