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

### Enable emergency access

LogScale provides emergency access capabilities through locally-created emergency users as a fallback mechanism when the primary identity provider is unavailable. The feature, enabled via the `EMERGENCY_USERS` environment variable, allows root users to create time-limited emergency accounts through an API endpoint, with support for both basic authentication and bearer tokens, and includes functionality to list and remove emergency users as needed.

If there are issues with the identity provider that LogScale is configured to use, then you might not be able to log in to LogScale. To mitigate this, LogScale provides emergency users that can be created locally within the LogScale cluster.

To enable emergency users, the environment variable `EMERGENCY_USERS` must be set to `true`. This enables the emergency API endpoint found at `/api/v1/emergency`. This API can be used by any user with root access on the LogScale instance to create and manage emergency users.

Emergency users expire automatically after a configurable timeout.

Once an emergency user is created, the emergency user can be used to log in to LogScale. To access local login, add the `locallogin=true` query parameter to your LogScale url. For example, `humio.example.com?locallogin=true`.

#### Emergency access API

The following examples assume the emergency API is accessed from the same machine running LogScale and therefore uses the local admin token. An API token of a root user can also be used.

`POST` to `/api/v1/emergency` creates a new emergency user. The payload is a JSON object with the following fields:

- `isRoot`: Whether the created user should be root. Must be `true` or `false`. Defaults to `false`.

- `groups`: An array of the groups the user should be members of. These groups must exist when the user is created. Optional.

- `expireIn`: A string containing the amount of time before the emergency user expires. The unit may be either `m`, `h`, or `d` for either minute, hour, or day, respectively. (For LogScale up to 1.14.0 `expireIn` must be less than or equal to 48 hours. This limit does not apply to 1.14.1+)

The response then returns a generated username and password of the emergency user as a JSON object. Below is an example:

shell

    $ curl localhost:8080/api/v1/emergency \
         -X POST \
         -H "Authorization: Bearer $(cat /data/humio-data/local-admin-token.txt)" \
         -H "Content-Type: application/json" \
         -d '{"isRoot":false, "groups":["foo","bar"], "expireIn": "48h"}'

This returns the following:

json

    {
      "password": "kM3mA2FW6f5CoLOL5OtpzvWs",
      "username": "emergency-GVyrVm0oyhNqPL6XXbdvIQAq"
    }

`GET` to `/api/v1/emergency` lists all emergency users. Below is an example:

shell

    $ curl localhost:8080/api/v1/emergency \
         -X GET \
         -H "Authorization: Bearer $(cat /data/humio-data/local-admin-token.txt)"

It returns the following:

json

    {
      "users": [
        {
          "expires": "2020-05-08T13:22:49.269Z",
          "groups": ["foo", "bar"],
          "isRoot": false,
          "username": "emergency-GVyrVm0oyhNqPL6XXbdvIQAq"
        }
      ]
    }

`DELETE` to `/api/v1/emergency/$USERNAME` removes an emergency user. Here's an example:

shell

    $ curl localhost:8080/api/v1/emergency/emergency-GVyrVm0oyhNqPL6XXbdvIQAq \
         -X DELETE \
         -H "Authorization: Bearer $(cat /data/humio-data/local-admin-token.txt)"

#### Basic authentication

An emergency user can authenticate using basic authentication instead of bearer tokens. This allows adding the emergency credentials to a proxy in front of LogScale.

shell

    $ USERNAME=emergency-GVyrVm0oyhNqPL6XXbdvIQAq
    $ PASSWORD=kM3mA2FW6f5CoLOL5OtpzvWs

    $ curl localhost:8080/api/v1/repositories \
        -H "Authorization: basic $(printf "$USERNAME:$PASSWORD" | base64 -w0)"

#### Enter search term