Managing Root Access

Security Requirements and Controls

Root users are users with the privileges required to act as systems administrators for the LogScale 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 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.

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

Or using Docker

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

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

shell
$ 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:

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

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

shell
$ 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:

shell
$ java -cp humio.jar com.humio.main.TokenHashing --json
{
  "secret": "WOiXOqiXG5kSfP4xHNGJMYMIUUQqlZNxscOAi2LzcRX7",
  "hashedToken": "P2HS9.20.S4fPBkfM0vmMMyNsrJP+cILFOdawl4//lsL6KbKIiOaHpeH4O23NXh6s93UxESa5NxPJmpEwv5RmXPQFlICdRw"
}

The hashed token from a secret is created as follows:

  • On the server, add this configuration value:

    ini
    BOOTSTRAP_ROOT_TOKEN_HASHED=P2HS9.20.S4fPBkfM0vmMMyNsrJP+cILFOdawl4//lsL6KbKIiOaHpeH4O23NXh6s93UxESa5NxPJmpEwv5RmXPQFlICdRw

  • In the client, supply this header in the request:

    http
    Authorization: Bearer localroot~WOiXOqiXG5kSfP4xHNGJMYMIUUQqlZNxscOAi2LzcRX7

Root Access Token

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.

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_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.