Skip to content
LogScale Self-Hosted
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

### Manage root access

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 and 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

    $ /app/humio/humio/jdk/bin/java -cp humio.jar com.humio.main.TokenHashing TOKEN

Or using Docker

shell

    $ docker container run humio/humio-core /app/humio/humio/jdk/bin/java -cp "/app/humio/humio/libs/*" \
                 com.humio.main.TokenHashing TOKEN

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

shell

    $ /app/humio/humio/jdk/bin/java -cp humio.jar com.humio.main.TokenHashing --json TOKEN

LogScale recommends 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 a 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, for example: `localroot~SECRET_TOKEN`.

This is typically provided in the HTTP Authorization header:

http

    Authorization: Bearer localroot~SECRET_TOKEN

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

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

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

#### Create 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.

#### Enter search term