Management¶

The management section of the configuration contains the appliance management-related configuration items.

Management API¶

The appliance management API is configured in the api section.

listeners: A list of listeners where each listener specifies a management API endpoint. A listener consists of an address and a description. The address is a combination of an IP address and a fixed port. The address must be specified as ip:port for IPv4 and [ip]:port for IPv6 addresses. Both IP and port must be set and cannot be left empty. To expose the management API on port 443 on all interfaces, bind it to 0.0.0.0:443. There must be at least one listener specified.

Note

By default, the management API is configured to listen on :443 for initial provisioning.

Connections to the management API are secured using HTTPS. The certificate used is self-signed and generated on the first boot-up of the appliance. You will need to manually trust the certificate to use the management API.

unprotected: By default, the management API is required to be protected by at least one of basic auth or OAuth2. If you want to expose the management API without any authentication, you need to explicitly set the unprotected property to true.

basic_auth

The management API supports basic user authentication using HTTP Basic Auth.

enabled

To enable basic authentication, set the enabled property to true

users

The list of users and their hashed passwords that are authorized to access the management API. The password_hashed value can be derived using the interactive appliance-cli or the htpasswd command::

appliance-cli crypto kdf hash

htpasswd -nB -C 12 admin

oauth

The management API supports user authentication via OAuth2. It supports the authorization code flow to authenticate users and the client credentials flow to authenticate machines, for example, a periodic job. The management API distinguishes between two roles:

appliance/reader a reader that has read-only access.

appliance/writer a writer that has read-write access.

The roles must be specified in the JSON Web Token (JWT) provided to the API. The roles can be specified either in the roles field or in the https://anapaya.net/roles field.

enabled

To enable OAuth2 authentication, set the enabled property to true

identity_providers

The list of identity providers. This is needed for the authorization code flow that provides a seamless experience for users of the appliance UI. Each identity provider has the following properties:

id

An identifier to identify the provider. This ID must be unique amongst the other providers.

type

The type of identity provider. The following two types are supported:

GENERIC: A generic identity provider. This should be used if no specific type exist for the identity provider of your choice. In this case the base_auth_url and the metadata_url field must be set.
AZURE_AD: The Azure active directory (AD) identity provider. When selecting this you likely need to specify the tenant_id field.

client_id and client_secret

The credentials to authenticate the appliance at the identity provider. These two fields always need to be set. The values should be retrieved from the configuration in the identity provider.

base_auth_url

The base URL for the identity provider. For example https://anapaya.eu.auth0.com/ for Auth0. This field only needs to be set for the GENERIC provider type.

metadata_url

The URL where the well-known OpenID configuration is hosted. This usually has the following path in the URL: /.well-known/openid-configuration .

tenant_id

The tenant ID of the Azure AD. This field only needs to be set if the type is AZURE_AD, otherwise it is ignored.

token_verification_keys

The token verification keys list specifies the keys that are used to verify the JWTs passed to the API. This is needed for the authorization code flow, where the client provides the JWT directly to the management API.

id: The unique identifier for this key set. This can be a descriptive name, like: anapaya-auth0.
jwks_url: The URL where the key set can be fetched. The appliance will periodically get the keys from this URL and update the API Gateway to accept tokens which can be verified with the given key set.

roles

The roles list contains custom configuration for the roles available on the appliance API (currently only reader and writer).

role: The name of the role. Currently, only reader and writer are supported.
aliases: The list of aliases for the role. This is useful for mapping different role names from different identity providers to the same role in the appliance. If no aliases are configured for a role, the default aliases are appliance.<role>, appliance/<role>, and appliance:<role>.

Management API Configuration

This example configures the management API to be available on 192.168.1.1:443 and enables HTTP basic auth for user admin and password password. The password_hashed value is created with the appliance-cli crypto kdf hash command.

{
   "management": {
      "api": {
         "listeners": [
            {
               "description": "LAN",
               "address": "192.168.1.1:443"
            }
         ],
         "basic_auth": {
            "enabled": true,
            "users": [
               {
                  "username": "admin",
                  "password_hashed": "$2y$05$9j6jB0DORgxVir0QerURDO669uiuMlbZSfz8F0t/Ty/GsjanBZlfW"
               }
            ]
         }
      }
   }
}

Telemetry¶

To enable telemetry of the appliance, the telemetry scraping endpoint needs to be configured in the telemetry section.

address: The endpoint on which the telemetry is exposed. The address is a combination of an IP address and a fixed port. The address must be specified as host:port, where the host can be empty. An empty address indicates a wildcard address. If the port is 0, it will be automatically allocated.

labels List of static labels that are added to all the telemetry data.

logging

Besides telemetry, appliance logs can be centrally collected.

logging_type

The type of log export. Currently, only Grafana Loki ("LOKI") is supported.

loki

The configuration for the Loki log export.

url: The URL of the Loki server. This is where the log records are being pushed to.
basic_auth: The basic auth configuration for the Loki log export. To configure it username and a password need to be provided.
tls_config: To disable server certificate verification, set the insecure_skip_verify to true.

flow_metrics

Configuration for the flow-metrics feature. The gateway collects information about outgoing flows, such as the source and destination ISD-AS and IP address, in order to export the number of IP-in-SCION tunneling users. The flow information is sent to a collector for storage and processing.

enabled: To enable the flow-metrics feature, set the enabled property to true. By default, the feature is disabled.
collector_url: The URL of the collector. Supports HTTP, HTTPS, and gRPC transports.
proxy_url: URL of the optional HTTP(s) proxy. If set, the flow metric information is sent to the collector via the proxy.
flow_expiration_interval: Time interval after which inactive flows are considered expired and are marked for cleanup.

Telemetry Configuration

This example configures telemetry to be exported on 192.168.1.1:42001. Furthermore, appliance logs are exported to a Loki server at https://loki.example.org:3100/api/v1/push, using admin:password to authenticate to the server and add a label appliance: s01.chzrh.anapaya to each log record.

{
   "telemetry": {
      "address": "192.168.1.1:42001",
      "labels": [
          {
          "label": "appliance",
          "value": "s01.chzrh.anapaya"
          }
      ]
      "logging": {
         "logging_type": "LOKI",
         "loki": {
            "url": "https://loki.example.org:3100/api/v1/push",
            "basic_auth": {
               "username": "admin",
               "password": "password"
            },
         }
      }

Hostname¶

The appliance hostname can be configured using the hostname property. The hostname is used to identify the host in the telemetry data, thus each appliance should have a unique hostname. The hostname must be a valid hostname according to the RFC 1123 specification.

hostname: The hostname of the appliance.

Hostname Configuration

This example configures the hostname to be s01.chzrh.anapaya.

{
   "management": {
      "hostname": "s01.chzrh.anapaya"
   }
}

Note

By default, the appliance API disallows changing the hostname, except when it is still unset. If the hostname is already set, the API will return a validation error. This is a safety measure to prevent accidental deployment of a configuration meant for a different appliance. If you want to change the hostname after it has been set, you need to set the allow_hostname_change query parameter to true.

SSH Configuration¶

The management.ssh section can be used to configure SSH keys for the appliance users via the appliance configuration. It contains the following fields:

users: A list of users and their SSH public keys. The SSH keys have a key and a description field. The key must be a base64-encoded key as used in the authorized_keys file. The description field is optional. If it is set it is used as comment in the authorized_keys file.
enable_password_login: To enable password-based SSH login, set the enable_password_login property to true. By default, password-based login is disabled. If enabled, all users can log in using their password.

Note

Currently, only the anapaya and root user can be configured via the appliance configuration.

Note

The ~/.ssh/authorized_keys2 file will be left untouched by the appliance configuration. If you do not want to use the appliance configuration for SSH key management, you can manually list the suitable keys in ~/.ssh/authorized_keys2.

Example SSH Configuration

This example configures the anapaya user with two SSH keys and enables password-based login.

{
   "management": {
      "ssh": {
         "users": [
            {
               "username": "anapaya",
               "ssh_keys": [
                  {
                     "key": "AAAAB3NzaC1yc2EAAAADAQABAAABgQC3...",
                     "description": "anapaya key1"
                  },
                  {
                     "key": "AAAAB3NzaC1yc2EAAAADAQABAAABgQC4...",
                     "description": "anapaya key2"
                  }
               ]
            },
         ],
         "enable_password_login": true
      }
   }
}