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.

Note

Access to the management API can be protected by basic authentication or OAuth2. Users are assigned a role that determines the level of access they have to the API. The following roles are currently supported:

reader: The reader role has access to all GET endpoints of the management API.
writer: The writer role has access to all endpoints of the management API.
observer: The observer role has access to all GET endpoints and a subset of POST endpoints that are required for the Anapaya Console functionality. observer role can access POST /debug/scion-tunneling/paths/search and any endpoint with the prefix POST /tools/scion

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.
disable_local_unix_socket`: By default, the management API is exposed on a local UNIX socket, that can only be accessed by a privileged user (the user needs to be part of the caddy group) locally on the appliance. Setting this property to true disables the local UNIX socket. Note this might lock you out of the management API if you have not configured any other listeners or those listeners are not reachable.

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, including their hashed passwords and roles, 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 three roles:

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

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

appliance/observer an obserer that has read access and write access to some endpoints.

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_ref

The client_secret_ref contains the secret reference to the client secret. The client_id and client_secret are used 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.

Please see Secret Management for information on how to provision a secret and then reference it in the configuration.

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, writer and observer 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_ref need to be provided.

Please see Secret Management for information on how to provision a secret and then reference it in the configuration.

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

radius

The management.ssh.radius section can be used to configure RADIUS authentication for SSH. The section contains the following fields:

servers

A list of RADIUS servers. Each server has the following properties:

address: The IP address of the RADIUS server.
secret_id_ref: The shared secret used to authenticate the appliance at the RADIUS server.
description: A description of the RADIUS server.

Example RADIUS Configuration

This example configures the appliance to use RADIUS authentication for SSH with a RADIUS server at 10.0.0.1.

{
"config": {
   "management": {
      "ssh": {
            "enable_password_login": true,
            "radius": {
               "servers": [
                  {
                        "description": "Radius Server",
                        "secret_id_ref": "radius-secret@1",
                        "address": "10.0.0.1"
                  }
               ]
            }
      }
   }
}

Note

To enable RADIUS authentication for SSH, both the RADIUS server and the PAM section need to be configured.

PAM Configuration¶

The management.pam section can be used to configure the Pluggable Authentication Module (PAM) for the appliance. The PAM configuration allows the user to configure custom PAM rules for the SSH service.

services

A list of PAM services. Each service has the following properties:

service: The name of the service. Currently, only sshd is supported.
enabled: To enable the service, set the enabled property to true.
description: A description of the service.
auth_modules: A list of authentication modules.
account_modules: A list of account modules.
password_modules: A list of password modules.
session_modules: A list of session modules.

Each module is a string that specifies the module and its configuration. The module string must be a valid PAM configuration line.

Example PAM Configuration

This example configures the SSH service to use the pam_radius_auth.so module for RADIUS authentication. The configuration requires that users logging into the appliance already exist on the appliance.

{
   "management": {
      "pam": {
         "services": [
            {
               "service": "sshd",
               "enabled": true,
               "description": "SSH Login Customization",
               "auth_modules": ["auth sufficient pam_radius_auth.so conf=/etc/pam_radius_auth.conf"]
            }
         ]
      }
   }
}