A JBoss Project
Red Hat

Configuration

Environment Variables

Using Docker containers is increasingly common. We now have a docker container for running hawtio for example.

When using docker then environment variables are a preferred way to configure things with environmental values.

So when using hawtio-base or hawtio-default you can use environment variables to override any of the properties on this page.

To override property “hawtio.foo” just set an environment variable (using _ for dots).

export hawtio_foo=bar

and if you boot up hawtio in that shell (or you pass that variable into a docker container) then you will override the system property hawtio.foo

Configuring Security

hawtio enables security out of the box depending on the container it is running within. Basically there is two types of containers:

  • Karaf based containers
  • Web containers

Default Security Settings for Karaf containers

By default the security in hawtio uses these system properties when running in Apache Karaf containers (Karaf, ServiceMix, JBoss Fuse) which you can override:

Name Default Description
hawtio.authenticationEnabled true Whether or not security is enabled
hawtio.realm karaf The security realm used to login
hawtio.role or hawtio.roles admin,viewer The user role or roles required to be able to login to the console. Multiple roles to allow can be separated by a comma. Set to * or an empty value to disable role checking when hawtio authenticates a user.
hawtio.rolePrincipalClasses Principal fully qualified classname(s). Multiple classes can be separated by a comma. Leave unset or set to an empty value to disable role checking when hawtio authenticates a user.
hawtio.noCredentials401 false Whether to return HTTP status 401 when authentication is enabled, but no credentials has been provided. Returning 401 will cause the browser popup window to prompt for credentails. By default this option is false, returning HTTP status 403 instead.
hawtio.authenticationContainerDiscoveryClasses io.hawt.web.tomcat.TomcatAuthenticationContainerDiscovery List of used AuthenticationContainerDiscovery implementations separated by comma. By default there is just TomcatAuthenticationContainerDiscovery, which is used to authenticate users on Tomcat from tomcat-users.xml file. Feel free to remove it if you want to authenticate users on Tomcat from configured jaas login module or feel free to add more classes of your own.
hawtio.authenticationContainerTomcatDigestAlgorithm NONE When using the tomcat tomcat-users.xml file, passwords can be hashed instead of plain text. Use this to specify the digest algorithm; valid values are NONE MD5 SHA SHA-256 SHA-384 SHA-512.
hawtio.tomcatUserFileLocation conf/tomcat-users.xml Specify an alternative location for the tomcat-users.xml file. eg -Dhawtio.tomcatUserFileLocation=/production/userlocation/

Changing these values is often application server specific. Usually the easiest way to get hawtio working in your container is to just ensure you have a new user with the required role (by default its the 'admin' role).

Example: customize the allowed roles in Fabric8

Hawtio reads its values in form of system properties. To define them in Fabric8:

dev:system-property hawtio.roles my_organization_admin
# restart hawtio bundle
restart io.hawt.hawtio-web

Now only users with the my_organization_admin role will be allowed to login in Hawtio.

To add the my_organization_admin role to the admin user in Fabric8:

jaas:manage --realm karaf
jaas:roleadd admin my_organization_admin
jaas:update

Default Security Settings for web containers

By default the security in hawtio uses these system properties when running in any other container which you can override:

Name Default Description
hawtio.authenticationEnabled false Whether or not security is enabled
hawtio.realm * The security realm used to login
hawtio.role or hawtio.roles The user role or roles required to be able to login to the console. Multiple roles to allow can be separated by a comma. Set to * or an empty value to disable role checking when hawtio authenticates a user.
hawtio.rolePrincipalClasses Principal fully qualified classname(s). Multiple classes can be separated by comma.
hawtio.noCredentials401 Whether to return HTTP status 401 when authentication is enabled, but no credentials has been provided. Returning 401 will cause the browser popup window to prompt for credentails. By default this option is false, returning HTTP status 403 instead.
hawtio.authenticationContainerDiscoveryClasses io.hawt.web.tomcat.TomcatAuthenticationContainerDiscovery List of used AuthenticationContainerDiscovery implementations separated by comma. By default there is just TomcatAuthenticationContainerDiscovery, which is used to authenticate users on Tomcat from tomcat-users.xml file. Feel free to remove it if you want to authenticate users on Tomcat from configured jaas login module or feel free to add more classes of your own.

Configuring or disabling security in web containers

Set the following JVM system property to enable security:

hawtio.authenticationEnabled=true

Or adjust the web.xml file and configure the <env-entry> element, accordingly.

Configuring security in Apache Tomcat

From hawt 1.2.2 onwards we made it much easier to use Apache Tomcats userdata file (conf/tomcat-users.xml) for security. All you have to do is to set the following CATALINA_OPTS environment variable:

export CATALINA_OPTS=-Dhawtio.authenticationEnabled=true

Then hawtio will auto detect that its running in Apache Tomcat, and use its userdata file (conf/tomcat-users.xml) for security.

For example to setup a new user named scott with password tiger, then edit the file '''conf/tomcat-users.xml''' to include:

<user username="scott" password="tiger" roles="tomcat"/>

Then you can login to hawtio with the username scott and password tiger.

If you only want users of a special role to be able to login hawtio then you can set the role name in the CATALINA_OPTS environment variable as shown:

export CATALINA_OPTS='-Dhawtio.authenticationEnabled=true -Dhawtio.role=manager'

Now the user must be in the manager role to be able to login, which we can setup in the '''conf/tomcat-users.xml''' file:

<role rolename="manager"/>
<user username="scott" password="tiger" roles="tomcat,manager"/>

Note that if you still want to use your own login modules instead of conf/tomcat-users.xml file, you can do it by remove TomcatAuthenticationContainerDiscovery from
system properties and point to login.conf file with your login modules configuration. Something like:

export CATALINA_OPTS='-Dhawtio.authenticationEnabled=true -Dhawtio.authenticationContainerDiscoveryClasses= -Dhawtio.realm=hawtio -Djava.security.auth.login.config=$CATALINA_BASE/conf/login.conf'

Then you can configure jaas in file TOMCAT_HOME/conf/login.conf (Example of file below in jetty section).

Configuring security in Jetty

To use security in jetty you first have to setup some users with roles. To do that navigate to the etc folder of your jetty installation and create the following file etc/login.properties and enter something like this:

scott=tiger, user
admin=CRYPT:adpexzg3FUZAk,admin,user

You have added two users. The first one named scott with the password tiger. He has the role user assigned to it. The second user admin with password admin which is obfuscated (see jetty realms for possible encryption methods). This one has the admin and user role assigned.

Now create a second file in the same directory called login.conf. This is the login configuration file.

hawtio {
  org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required 
  debug="true"
  file="${jetty.base}/etc/login.properties";
};

Next you have to change the hawtio configuration:

Name Default Description
hawtio.authenticationEnabled true Whether or not security is enabled
hawtio.realm hawtio The security realm used to login
hawtio.role admin The user role required to be able to login to the console
hawtio.rolePrincipalClasses Principal fully qualified classname(s). Multiple classes can be separated by comma.

You have now enabled security for hawtio. Only users with role “admin” are allowed.

At last enable the jaas module in jetty. This is done by adding the following line to the start.ini which is located in the jetty.base folder:

# Enable security via jaas, and configure it
--module=jaas

Keycloak integration

Hawtio can now be integrated with Keycloak for SSO authentication. See details here .

Configuration Properties

The following table contains the various configuration settings for the various hawtio plugins.

System Property Description
hawtio.offline Whether to run hawtio in offline mode (default false). When in offline mode, then some plugins is not enabled such as Maven and Git.
hawtio.dirname The directory name for the hawtio home. Is by default /.hawtio. This complete home directory for hawtio is the hawtio.config.dirhawtio.dirname, so remember to have leading / in this option. The out of the box options translates as the: user.home/.hawtio directory.
hawtio.config.dir The directory on the file system used to keep a copy of the configuration for hawtio; for all user settings, the dashboard configurations, the wiki etc. Typically you will push this configuration to some remote git server (maybe even github itself) so if not specified this directory will be a temporary created directory. However if you are only running one hawtio server then set this somewhere safe and you probably want to back this up!. See also the hawtio.dirname option.
hawtio.config.repo The URL of the remote git repository used to clone for the dashboard and wiki configuration. This defaults to git@github.com:hawtio/hawtio-config.git but if you forked the hawtio-config repository then you would use your own user name; e.g. git@github.com:myUserName/hawtio-config.git
hawtio.config.cloneOnStartup If set to the value of false then there will be no attempt to clone the remote repo
hawtio.config.importURLs The URLs (comman separated) of jar/zip contents that should be downloaded and imported into the wiki on startup. This supports the mvn:group/artifact/version[/extension/classifier] syntax so you can refer to jars/zips from maven repos
hawtio.config.pullOnStartup If set to the value of false then there will be no attempt to pull from the remote config repo on startup
hawtio.maven.index.dir The directory where the maven indexer will use to store its cache and index files
hawtio.sessionTimeout hawtio 1.2.2 - 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.
hawtio.activemq.verbose.tree hawtio 1.4.59 - Is default false to filter out verbose ActiveMQ details from the tree in hawtio. This ensures situations when ActiveMQ will constantly add/remove same set of mbeans for a client connection because the client is not using pooled connections or using XA transactions without caching the consumer. In situations like these ActiveMQ keeps changing the mbeans which would cause the hawtio web console to trigger an update in the tree, which makes using the web console more sluggish. Therefore this is filtered out by default. This option can be set to true to restore old behavior.
hawtio.proxyWhitelist hawtio 1.5.0 - Comma-separated whitelist for target hosts that the remote JVM connect plugin ProxyServlet can connect to (default localhost, 127.0.0.1). All hosts that are not listed in this whitelist are denied to connect for security reasons. This option can be set to * to restore old behavior and whitelist all hosts. Prefixing an element of the list with "r:" allows to define a regexp (example: localhost,r:myservers[0-9]+.mydomain.com)

Web Application configuration

If you are using a web container, the easiest way to change the web app configuration values is:

OSGi configuration

Just update the blueprint configuration values in OSGi config admim as you would any OSGi blueprint bundles. On OSGi all the hawtio Java modules use OSGi blueprint.

Jolokia configuration

Jolokia agent is deployed automatically with io.hawt.web.JolokiaConfiguredAgentServlet that extends Jolokia native org.jolokia.http.AgentServlet class, defined in hawtio-web/WEB-INF/web.xml.
To customize Jolokia Servlet configuration, according to the parameters that it supports and that are defined here:
https://jolokia.org/reference/html/agents.html#agent-war-init-params

You have to pass them as java system properties, prefixed with jolokia..

EX.

-Djolokia.policyLocation=file:///home/fuse/my-access.xml

NOTE The parameter restrictorClass is already used in hawtio-web/WEB-INF/web.xml to implement role-based access control (RBAC) for Jolokia invocations. If you want to use your own Jolokia restrictor, make sure to extend io.hawt.web.RBACRestrictor to implement your own restrictor class. Otherwise, part of Hawtio's RBAC functions will be lost.

More information

In the articles colleciton you may find links to blog posts how to setup authentication with hawtio in various other containers.