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 to0.0.0.0:443
. There must be at least one listener specified.
Note
By default, the management API is configured to listen on 127.0.0.1:443
for
initial provisioning.
Note
Appliances prior to version v0.33 only specify a single management API address
address
of the same format as the listener address e.g. "address": "127.0.0.1:443"
.
This field is has been removed and listeners
must be used.
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 totrue
.
basic_auth
The management API supports basic user authentication using HTTP Basic Auth.
enabled
To enable basic authentication, set the
enabled
property totrue
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 interactiveappliance-cli
or thehtpasswd
command::appliance-cli crypto kdf hash htpasswd -nB 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 thehttps://anapaya.net/roles
field.enabled
To enable OAuth2 authentication, set the
enabled
property totrue
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 thebase_auth_url
and themetadata_url
field must be set.AZURE_AD
: The Azure active directory (AD) identity provider. When selecting this you likely need to specify thetenant_id
field.
client_id
andclient_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 theGENERIC
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
isAZURE_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
andwriter
).role
The name of the role. Currently, only
reader
andwriter
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>
, andappliance:<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 apassword
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 totrue
. 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.
export_task_interval
Time interval at which flow metrics are exported to the collector.
flow_expiration_interval
Time interval after which inactive flows are considered expired and are marked for cleanup.
cleanup_task_interval
Time interval at which expired flows are cleaned up.
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.
hostname
The hostname of the appliance.
Hostname Configuration
This example configures the hostname to be s01.chzrh.anapaya
.
{
"management": {
"hostname": "s01.chzrh.anapaya"
}
}
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 adescription
field. Thekey
must be a base64-encoded key as used in the authorized_keys file. Thedescription
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 totrue
. 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
}
}
}