Root Access

Root users are users with the privileges required to act as systems administrators for the Humio cluster. They have the access rights to add and remove other users to the system and manage aspects that affect all repositories. By default, root users are also members of all repositories. This is controlled by the ENFORCE_AUDITABLE setting (see Audit Logging |–| Permissions & Enforce Auditable Mode).

Hashed Root Access Token

It is possible to create a root token and use that token when starting Humio. This can be useful for provisioning tools setting up a cluster and performing operations requiring root privileges. To make it hard to expose this token, the token must be hashed when provided in the configuration for Humio. To create the hashed root token you need to use the Humio jar file. This can be done in 2 ways: Use the jar file directly or if using Docker, use the jar file in the docker image.

humio
java -cp humio.jar com.humio.main.TokenHashing <optional-long-secret-token>

Or using Docker

humio
docker container run humio/humio-core java -cp humio-assembly.jar com.humio.main.TokenHashing <optional-long-secret-token>

We recommend not adding any secret to the command, then the tool will create a random secret and output both the secret and the hashed token. It is possible to decide what the secret should be by providing the secret as parameter to the command. The salt for the hashed token when using this command is localroot The hashed token can then be specified in Humio’s configuration. like this:

humio
BOOTSTRAP_ROOT_TOKEN_HASHED=<hashed-token>

It is then possible to use the secret token in a client, for example a provisioning tool setting up a Humio cluster and calling API endpoints. The client should provide the original secret long with the salt when providing the token for authentication localroot~<secret-token>. This is typically provided in the HTTP Authorization header:

humio
Authorization: Bearer localroot~<secret-token>

We recommend using this approach when provisioning tools or operators needs root privileges. It is typically a better and safer approach than using the local-admin-token.txt described below.

Below example creates a hashed token from a secret:

humio
java -cp humio.jar com.humio.main.TokenHashing
Secret: WOiXOqiXG5kSfP4xHNGJMYMIUUQqlZNxscOAi2LzcRX7
Hashed token: P2HS9.20.S4fPBkfM0vmMMyNsrJP+cILFOdawl4//lsL6KbKIiOaHpeH4O23NXh6s93UxESa5NxPJmpEwv5RmXPQFlICdRw
Using this:
  * On the server, add this config to the env: BOOTSTRAP_ROOT_TOKEN_HASHED=P2HS9.20.S4fPBkfM0vmMMyNsrJP+cILFOdawl4//lsL6KbKIiOaHpeH4O23NXh6s93UxESa5NxPJmpEwv5RmXPQFlICdRw
  * In the client, supply this header in the request: 'Authorization: Bearer localroot~WOiXOqiXG5kSfP4xHNGJMYMIUUQqlZNxscOAi2LzcRX7'

Root Access Token

If you have SSH access to the machine running Humio, you can always perform API requests through 127.0.0.1:8080 or any other way of getting HTTP requests to the Humio server using the special API token for root access. The token is re-created every time the server starts, and placed in the file /data/humio-data/local-admin-token.txt. The token allows root access on the API for anyone able to read this file.

The root token can be used for creating initial setup and configuration such as setting up users and repositories. It’s also useful for running scripts/integrations on the local server, for provisioning or daily maintenance purposes, in particular for scripts running on the same server with read-access to the token file.

Note

Since the token is re-generated on every server startup, it is not suitable as a long-term API token. For long-term API tokens, add a user with root privileges and use the API token for that user. Different nodes in the cluster will have different tokens.

Creating Root Users

You can use the root token to create root users. To create a user with root privileges on the server, run:

shell
TOKEN=`cat /data/humio-data/local-admin-token.txt`
curl $YOUR_HUMIO_URL/api/v1/users \
     -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d "{\"email\": \"$EMAIL\", \"isRoot\": true}"

When using LDAP $EMAIL is the username the user must enter to login, and need not be an actual email address.

Once that user has been added, you can log on using that user and see your own API token, as described in API Authentication.