It is possible to create a root token and use that token when starting LogScale. 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 LogScale. To create the hashed root token you need to use the LogScale jar file. This can be done in two ways: use the jar file directly or, if using Docker, use the jar file in the docker image.

$ /app/humio/humio/jdk/bin/java -cp humio.jar com.humio.main.TokenHashing <optional-long-secret-token>

Or using Docker

$ docker container run humio/humio-core /app/humio/humio/jdk/bin/java -cp "/app/humio/humio/libs/*" \
             com.humio.main.TokenHashing <optional-long-secret-token>

If you want the output as JSON you can add --json before the secret. For example:

$ /app/humio/humio/jdk/bin/java -cp humio.jar com.humio.main.TokenHashing --json 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 LogScale's configuration using BOOTSTRAP_ROOT_TOKEN_HASHED like this:

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 LogScale 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:

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.

The below example creates a hashed token from a secret:

$ /app/humio/humio/jdk/bin/java -cp humio.jar com.humio.main.TokenHashing
Secret: WOiXOqiXG5kSfP4xHNGJMYMIUUQqlZNxscOAi2LzcRX7
Hashed token: P2HS9.20.S4fPBkfM0vmMMyNsrJP+cILFOdawl4//lsL6KbKIiOaHpeH4O23NXh6s93UxESa5NxPJmpEwv5RmXPQFlICdRw

Here is another example with the --json option:

The hashed token from a secret is created as follows:

If you have SSH access to the machine running LogScale, you can always perform API requests through 127.0.0.1:8080 or any other way of getting HTTP requests to the LogScale 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.

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

$ TOKEN=`cat /data/humio-data/local-admin-token.txt`
curl $YOUR_LOGSCALE_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.