Configuration

Hawtio consists of two main components: the server runtime and client console. The server runtime is the Java backend that runs on the server side, and the client console is the JavaScript frontend that is deployed and runs on the browser.

Therefore, two types of configuration are provided for Hawtio:

Configuration properties - The server runtime configuration
hawtconfig.json - The client console configuration

Configuration properties

The Hawtio server runtime and its plugins can configure their behaviours through System properties.

The following table lists the configuration properties for the Hawtio core system and various plugins.

For the configuration properties related to security and authentication, refer to Security.

Table 1. Configuration properties
System property	Default	Description
`hawtio.disableProxy`	`false`	With this property set to `true`, `ProxyServlet` (`/hawtio/proxy/*`) can be disabled. This makes Connect plugin unavailable, which means Hawtio can no longer connect to remote JVMs, but sometimes users might want to do so because of security if Connect plugin is not used.
`hawtio.localAddressProbing`	`true`	Whether local address probing for proxy allowlist is enabled or not upon startup. Set this property to `false` to disable it.
`hawtio.proxyAllowlist`	`localhost, 127.0.0.1`	Comma-separated allowlist for target hosts that Connect plugin can connect to via `ProxyServlet`. All hosts that are not listed in this allowlist are denied to connect for security reasons. This option can be set to `*` to allow all hosts. Prefixing an element of the list with `"r:"` allows to define a regexp (example: `localhost,r:myserver[0-9]+.mydomain.com`)
`hawtio.redirect.scheme`	-	The scheme of the redirect URL to login page when authentication is required.
`hawtio.sessionTimeout`	-	The maximum time interval, in seconds, that the servlet container will keep this session open between client accesses. If this option is not configured, then Hawtio uses the default session timeout of the servlet container.

Quarkus

For Quarkus, all those properties are configurable in application.properties or application.yaml with the quarkus.hawtio. prefix. For example:

application.properties

quarkus.hawtio.disableProxy = true

Spring Boot

For Spring Boot, all those properties are configurable in application.properties or application.yaml as is. For example:

application.properties

hawtio.disableProxy = true

Configuring Jolokia through System properties

The Jolokia agent is deployed automatically with io.hawt.web.JolokiaConfiguredAgentServlet that extends Jolokia native org.jolokia.http.AgentServlet class, defined in hawtio-war/WEB-INF/web.xml.

If you want to customize the Jolokia Servlet with the configuration parameters that are defined in the Jolokia documentation, you can pass them as System properties prefixed with jolokia.. For example:

jolokia.policyLocation = file:///opt/hawtio/my-jolokia-access.xml

RBAC Restrictor

For some runtimes that support Hawtio RBAC (role-based access control) ^[1], Hawtio provides a custom Jolokia restrictor implementation that provides an additional layer of protection over JMX operations based on the ACL (access control list) policy.

You cannot use Hawtio RBAC with Quarkus and Spring Boot yet. Enabling the RBAC restrictor on those runtimes only imposes additional load without any gains.

To activate the Hawtio RBAC restrictor, configure the Jolokia parameter restrictorClass via System property to use io.hawt.web.RBACRestrictor as follows:

jolokia.restrictorClass = io.hawt.system.RBACRestrictor

hawtconfig.json

hawtconfig.json is the entrypoint JSON file for configuring the frontend console of Hawtio. It can be used to customise the various parts of the console: the branding, styles and basic UI parts such as the login page and about modal, as well as the console-specific behaviours of some of the Hawtio plugins.

Here is an example file of hawtconfig.json:

Example hawtconfig.json

{
  "branding": {
    "appName": "Hawtio Management Console",
    "showAppName": false,
    "appLogoUrl": "hawtio-logo.svg",
    "companyLogoUrl": "hawtio-logo.svg",
    "css": "",
    "favicon": "favicon.ico"
  },
  "login": {
    "description": "Login page for Hawtio Management Console.",
    "links": [
      { "url": "#terms", "text": "Terms of Use" },
      { "url": "#help", "text": "Help" },
      { "url": "#privacy", "text": "Privacy Policy" }
    ]
  },
  "about": {
    "title": "Hawtio Management Console",
    "description": "A Hawtio reimplementation based on TypeScript + React.",
    "imgSrc": "hawtio-logo.svg",
    "productInfo": [
      { "name": "ABC", "value": "1.2.3" },
      { "name": "XYZ", "value": "7.8.9" }
    ],
    "copyright": "© Hawtio project"
  },
  "disabledRoutes": [
    "/disabled"
  ]
}

Configuration options in `hawtconfig.json`

At the top level of hawtconfig.json, the following options are currently provided:

Table 2. Top-level configuration options
Option	Description
`branding`	The branding options for the console.
`login`	The login page configuration.
`about`	The about modal configuration.
`disabledRoutes`	The list of plugins that should be hidden from the console.
`jmx`	The JMX plugin configuration.
`online`	The Hawtio Online configuration.

Branding

The branding configuration provides the options to customise the console’s branding, such as the application name, logos, styles and favicon.

Table 3. Branding configuration options
Option	Default	Description
`appName`	`Hawtio Management Console`	Customise the application name of the console. The name is used in the browser title header and optionally in the header of the console page.
`showAppName`	`false`	Show the application name in the header of the console page.
`appLogoUrl`	`img/hawtio-logo.svg`	Use the URL to substitute the application logo.
`companyLogoUrl`	`img/hawtio-logo.svg`	Use the URL to substitute the company logo.
`css`		Provide the custom CSS to apply to the console.
`favicon`		Use the URL to substitute the favicon.

Here is how the branding configuration looks in hawtconfig.json:

hawtconfig.json

  "branding": {
    "appName": "Hawtio Management Console",
    "showAppName": false,
    "appLogoUrl": "hawtio-logo.svg",
    "companyLogoUrl": "hawtio-logo.svg",
    "css": "",
    "favicon": "favicon.ico"
  }

Login

The login configuration provides the options to customise the information displayed in the Hawtio login page.

Table 4. Login configuration options
Option	Default	Description
`description`		Set the text displayed in the login page.
`links`	`[]`	Provide the links at the bottom of the login page. The value should be an array of objects with `url` and `text` properties.

Here is how the login configuration looks in hawtconfig.json:

hawtconfig.json

  "login": {
    "description": "Login page for Hawtio Management Console.",
    "links": [
      { "url": "#terms", "text": "Terms of Use" },
      { "url": "#help", "text": "Help" },
      { "url": "#privacy", "text": "Privacy Policy" }
    ]
  }

About

The about configuration provides the options to customise the information displayed in the Hawtio About modal.

Table 5. About configuration options
Option	Default	Description
`title`	`Hawtio Management Console`	Customise the title of the About modal.
`description`		Provide the description text to the About modal.
`imgSrc`	`img/hawtio-logo.svg`	Use the URL to substitute the logo image in the About modal.
`productInfo`	`[]`	Provide the information of names and versions about the additional components used in the console. The value should be an array of objects with `name` and `value` properties.
`copyright`		Set the copyright information in the About modal.

Here is how the about configuration looks in hawtconfig.json:

hawtconfig.json

  "about": {
    "title": "Hawtio Management Console",
    "description": "A Hawtio reimplementation based on TypeScript + React.",
    "imgSrc": "hawtio-logo.svg",
    "productInfo": [
      { "name": "ABC", "value": "1.2.3" },
      { "name": "XYZ", "value": "7.8.9" }
    ],
    "copyright": "© Hawtio project"
  }

Disabled routes

The disabledRoutes configuration provides the option to hide the plugins from the console.

The value of the option should be an array of strings that represent the paths of the plugins that should be hidden.

Here is how the disabledRoutes configuration looks in hawtconfig.json:

hawtconfig.json

  "disabledRoutes": [
    "/disabled"
  ]

JMX plugin

The JMX plugin is customisable via the jmx configuration in hawtconfig.json.

By default Hawtio loads all MBeans into the workspace via the JMX plugin. Sometimes your custom Hawtio console might want to load only a portion of MBeans to reduce the load on the application. The jmx configuration provides an option to limit the MBeans to be loaded into the workspace.

Option Default Description

workspace

Specify the list of MBean domains and object names that should be loaded to the JMX plugin workspace. This option can either disable workspace completely by setting false, or specify an array of MBean paths in the form of:

<domain>/<prop1>=<value1>,<prop2>=<value2>,...

to fine-tune which MBeans to load into workspace.

Disabling workspace should also deactivate all the plugins that depend on MBeans provided by workspace.

Here is how the jmx configuration looks in hawtconfig.json:

hawtconfig.json

  "jmx": {
    "workspace": [
      "hawtio",
      "java.lang/type=Memory",
      "org.apache.camel",
      "no.such.domain"
    ]
  }

Hawtio Online

The frontend aspects of Hawtio Online can be configured via the online configuration in hawtconfig.json.

Table 7. Hawtio Online configuration options
Option	Default	Description
`projectSelector`		Set the selector used to watch for projects. It is only applicable when the `Hawtio` deployment type is equal to `cluster`. By default, all the projects the logged in user has access to are watched. The string representation of the selector must be provided, as mandated by the `--selector`, or `-l`, options from the `kubectl get` command. See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
`consoleLink`		Configure the OpenShift Web console link. A link is added to the application menu when the `Hawtio` deployment is equal to `cluster`. Otherwise, a link is added to the Hawtio project dashboard. The value should be an object with the following properties: `text`, `section`, and `imageRelativePath`.

Table 8. ConsoleLink configuration options
Option	Default	Description
`text`		Set the text display for the link.
`section`		Set the section of the application menu in which the link should appear. It is only applicable when the Hawtio deployment type is equal to `cluster`.
`imageRelativePath`		Set the path, relative to the Hawtio status URL, for the icon used in front of the link in the application menu. It is only applicable when the `Hawtio` deployment type is equal to `cluster`. The image should be square and will be shown at 24x24 pixels.

Here is how the online configuration looks in hawtconfig.json:

hawtconfig.json

  "online": {
    "projectSelector": "myproject",
    "consoleLink": {
        "text": "Hawtio Management Console",
        "section": "Hawtio",
        "imageRelativePath": "/online/img/favicon.ico"
    }
  }

Deploying `hawtconfig.json`

Quarkus

For a Quarkus application, the hawtconfig.json file, as well as the other companion static resources such as CSS files and images, should be placed under META-INF/resources/hawtio in the src/main/resources directory of the project.

You can find an example Quarkus project at:

https://github.com/hawtio/hawtio/tree/4.x/examples/quarkus

Spring Boot

For a Spring Boot application, the hawtconfig.json file, as well as the other companion static resources such as CSS files and images, should be placed under hawtio-static in the src/main/resources directory of the project.

You can find an example Spring Boot project at:

https://github.com/hawtio/hawtio/tree/4.x/examples/springboot-authentication

Customising from plugins

While plugins cannot directly provide the hawtconfig.json file itself for the console, they can customise the configuration after the file is loaded from the main console application.

The @hawtio/react NPM package provides the configManager API. You can use this API in the plugin’s index.ts to customise the configuration of hawtconfig.json during the loading of the plugin.

Here is an example of how you can customise the hawtconfig.json configuration from a plugin:

import { HawtioPlugin, configManager } from '@hawtio/react'
...

/**
 * The entry function of your plugin.
 */
export const plugin: HawtioPlugin = () => {
  ...
}

// Register the custom plugin version to Hawtio
// See package.json "replace-version" script for how to replace the version placeholder with a real version
configManager.addProductInfo('Hawtio Sample Plugin', '__PACKAGE_VERSION_PLACEHOLDER__')

/*
 * This example also demonstrates how branding and styles can be customised from a WAR plugin.
 *
 * The Plugin API `configManager` provides `configure(configurer: (config: Hawtconfig) => void)` method
 * and you can customise the `Hawtconfig` by invoking it from the plugin's `index.ts`.
 */
configManager.configure(config => {
  // Branding & styles
  config.branding = {
    appName: 'Hawtio Sample WAR Plugin',
    showAppName: true,
    appLogoUrl: '/sample-plugin/branding/Logo-RedHat-A-Reverse-RGB.png',
    css: '/sample-plugin/branding/app.css',
    favicon: '/sample-plugin/branding/favicon.ico',
  }
  // Login page
  config.login = {
    description: 'Login page for Hawtio Sample WAR Plugin application.',
    links: [
      { url: '#terms', text: 'Terms of use' },
      { url: '#help', text: 'Help' },
      { url: '#privacy', text: 'Privacy policy' },
    ],
  }
  // About modal
  if (!config.about) {
    config.about = {}
  }
  config.about.title = 'Hawtio Sample WAR Plugin'
  config.about.description = 'About page for Hawtio Sample WAR Plugin application.'
  config.about.imgSrc = '/sample-plugin/branding/Logo-RedHat-A-Reverse-RGB.png'
  if (!config.about.productInfo) {
    config.about.productInfo = []
  }
  config.about.productInfo.push(
    { name: 'Hawtio Sample Plugin - simple-plugin', value: '1.0.0' },
    { name: 'Hawtio Sample Plugin - custom-tree', value: '1.0.0' },
  )
  // If you want to disable specific plugins, you can specify the paths to disable them.
  //config.disabledRoutes = ['/simple-plugin']
})

You can find an example WAR plugin project at:

https://github.com/hawtio/hawtio-sample-war-plugin-ts

1. Apache Karaf and Apache ActiveMQ Artemis provide Hawtio RBAC support.

Configuration

Configuration properties

Quarkus

Spring Boot

Configuring Jolokia through System properties

RBAC Restrictor

hawtconfig.json

Configuration options in hawtconfig.json

Branding

Login

About

Disabled routes

JMX plugin

Hawtio Online

Deploying hawtconfig.json

Quarkus

Spring Boot

Customising from plugins

Configuration options in `hawtconfig.json`

Deploying `hawtconfig.json`