Skip to main content

Management

The Configuration reference section provides the full configuration reference. The sections following after provide descriptions of most relevant management configuration sections with more elaborated examples.

Configuration reference​

v0.40v0.39v0.38next

Anapaya appliance configuration (management only)

management object

The necessary configuration data for the management of the Anapaya appliance.

api object

Anapaya appliance management API configuration.

basic_auth object

Basic auth configuration that restricts the access to the Anapaya appliance management API.

enabledboolean

Enable basic authentication for the Anapaya appliance management API.

users object[]

List of basic auth user credentials that are authorized to access the management API.

  • Array [
    • password_hashedstringrequired

    The user password hashed based on the hash algorithm indicated by the prefix in the string. The string takes the following form based on the Unix crypt function:

    $id[$param=value(,param=value)*][$salt[$hash]]

    Supported hash functions are:

    • $2y$: bcrypt

    The 'appliance-cli' or the 'htpasswd' tool can be used to create a password hash. E.g., 'appliance-cli crypto kdf hash' or 'htpasswd -nB -C 12 admin' prompts for a password.

    Example: $2y$10$QNodxwKFABMWu4XlFPmZDOSfqxrsqNvrSn487lCi7tJ/4nTsT/f02
    rolesstring[]required

    List of roles that a user has. The following standard roles 'reader', 'observer', and 'writer' are supported.

    The 'reader' role is granted access to all GET endpoints on the API.

    The 'observer' role is granted access to all GET endpoints, as well as POST access to '/api/v1/debug/scion-tunneling/paths/search' and '/api/v1/tools/scion.*'

    The 'writer' role is granted access to all endpoints.

    Possible values: >= 1

    usernamestringrequired

    Name of the user.

    Example: admin
  • ]
    • disable_local_unix_socketboolean

    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.

    Default value: false
    interfaces object[]

    List of network interfaces management API listeners that define where the API is exposed. Use this only if the interface address is unknown at configuration time, i.e., it is assigned dynamically.

  • Array [
    • descriptionstring

    Description, or comment, for the interface.

    namestring

    Network interface name to listen on.

    portinteger<uint16>

    The TCP or UDP port to listen on.

  • ]
    • listeners object[]

    List of management API listeners that define where the API is exposed

  • Array [
    • addressstring<scion-port>

    An address that is used to expose the Anapaya appliance management API. This can be either a combination of an IP address and a fixed port, or a SCION address. The address must be specified as ip:port for IPv4, [ip]:port for IPv6 and [ISD-AS,ip]:port for SCION.

    Example: 127.0.0.1:443
    descriptionstring

    Description, or comment, for the listener.

  • ]
    • oauth object

    Open authorization (OAuth) configuration that can authorize users who want to access the Anapaya appliance management API.

    enabledboolean

    Whether the feature is enabled.

    Default value: false
    identity_providers object[]

    The identity providers. Currently only one is supported.

  • Array [
    • base_auth_urlstring

    The base URL for the identity provider.

    Example: https://anapaya.eu.auth0.com/
    client_idstring

    The client ID for this identity provider.

    client_secret_refstring<secret-ref>

    Reference to the client secret for this identity provider.

    idstring

    The identifier of the provider. Must be unique among all providers.

    metadata_urlstring

    The URL for fetching the open ID configuration.

    Example: https://anapaya.eu.auth0.com/.well-known/openid-configuration
    tenant_idstring

    The tenant ID for Azure AD

    typestring

    The type of the provider.

    Possible values: [GENERIC, AZURE_AD]

  • ]
    • roles object[]

    Roles configuration used for OAuth.

  • Array [
    • aliasesstring[]

    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 alias are configured for a role the default aliases are 'appliance.', 'appliance/', and 'appliance:'.

    rolestring

    Name of the role.

  • ]
    • token_verification_keys object[]

    Keys to verify JWTs.

  • Array [
    • idstring

    The identifier of the key. Must be unique among all keys.

    Example: anapaya.auth0
    jwks_urlstring

    URL for fetching JSON Web Key Sets.

    Example: https://anapaya.eu.auth0.com/.well-known/jwks.json
  • ]
    • unprotectedboolean

    Whether the management API is allowed to be exposed without authentication. Always make sure to properly protect your API.

    Default value: false
    hostnamestring

    The hostname of the Anapaya appliance host. It is used to identify the host in the telemetry data; thus, each host should have a unique hostname. The hostname must be a valid hostname according to the RFC 1123 specification. 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.

    Default value: anapaya-appliance
    Example: edge-geneva-corpbank
    pam object

    Configuration for the Pluggable Authentication Module (PAM) of the Anapaya appliance.

    services object[]

    List of services that are configured to use the Pluggable Authentication Module (PAM) of the Anapaya appliance.

  • Array [
    • account_modulesstring[]

    List of PAM account modules that are used for the service.

    auth_modulesstring[]

    List of PAM authentication modules that are used for the service.

    descriptionstring

    Description or comment for the service.

    enabledboolean

    Whether the PAM service is enabled.

    Default value: false
    password_modulesstring[]

    List of PAM password modules that are used for the service.

    servicestring

    The name of the PAM service. The service name must be a valid service name according to the PAM specification. The service name is used to identify the service in the PAM configuration files.

    Example: sshd
    session_modulesstring[]

    List of PAM session modules that are used for the service.

  • ]
    • ssh object

    Configuration for SSH access to the Anapaya appliance.

    enable_password_loginboolean

    Whether password login is enabled for SSH access to the Anapaya appliance.

    Default value: false
    radius object

    Configuration for RADIUS access to the Anapaya appliance. The resulting RADIUS configuration on the appliance is written to /etc/pam_radius_auth.conf, and can be referenced in the PAM configuration.

    servers object[]

    RADIUS server configurations.

  • Array [
    • addressstring

    The IP address of the RADIUS server.

    descriptionstring

    Description or comment for the server.

    secret_id_refstring<secret-ref>

    Reference to the secret ID used to authenticate the Anapaya appliance to the RADIUS server

  • ]
    • users object[]

    Users with SSH access to the Anapaya appliance.

  • Array [
    • ssh_keys object[]

    List of SSH keys that are authorized for the given user. This list is authoritative and overwrites the list of existing SSH keys in the user's authorized_keys file.

  • Array [
    • descriptionstring

    Description or comment for the key.

    keystring

    The SSH public key of the user.

    Example: AAAAB3NzaC1yc2
  • ]
    • usernamestring

    The unix username of the user.

    Example: anapaya
  • ]
    • telemetry object

    Anapaya appliance telemetry configuration.

    addressstring

    The address where the telemetry data is exposed. This is a combination of an IP address and a fixed port. The address must be specified as host:port, where host can be empty. An empty address indicates a wildcard address. If the address is not specified or the IP is empty and the port is zero, only the management API address exposes the telemetry data.

    Example: :42001
    flow_metrics object

    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 then number of gateway users. The flow information is sent to the flow-collector for storage and processing.

    collector_urlstring

    URL of the flow-collector where the flow metric information is sent to. Supports 'http', 'https' and 'grpc' transport

    enabledboolean

    Whether the feature is enabled.

    Default value: false
    export_task_intervalstring<duration-string>

    The minimum time interval at which flow metrics are exported to the collector.

    Default value: 60s
    flow_expiration_intervalstring<duration-string>

    Time interval after which inactive flows are considered expired and are marked for cleanup.

    Default value: 120s
    proxy_urlstring

    URL of the optional HTTP(S) proxy. If set, the flow metric information is sent to the collector via the proxy.

    labels object[]

    List of static labels that are added to all telemetry data (e.g. logs, metrics).

  • Array [
    • labelstring

    Name of the label.

    valuestring

    Value of the label.

  • ]
    • logging object

    Configuration for shipping logs to a remote log aggregation system.

    logging_typestring

    The type of log aggregation system which is used.

    Possible values: [LOKI]

    loki object

    Loki configuration.

    basic_auth object

    Basic auth configuration for sending log lines to Loki.

    password_refstring<secret-ref>

    Reference to the password used for basic auth.

    usernamestring

    The username to use for basic auth.

    Example: promtail
    tenant_idstring

    The tenant ID used to push logs to Loki. If unset, single tenant mode is assumed.

    tls_config object

    Configuration for TLS connection.

    insecure_skip_verifyboolean

    insecure-skip-verify controls whether the client verifies the Loki server's certificate chain and host name. If insecure-skip-verify is true, the appliance accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing.

    Default value: false
    urlstring

    The url which is used to push logs to Loki.

    Example: https://loki.anapaya.net/loki/api/v1/push

    Management API configuration​

    note

    As of release v0.38, the management API listens on a unix socket by default. Unless you want to use the management API over the network, e.g., for the Anapaya Console, you do not need to configure the management.api section.

    Prior to v0.38, the management API is configured to listen on :443 for initial provisioning, until an explicit configuration is applied.

    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.

    The example below configures the management API to be available on Loading... and enables HTTP basic auth for users admin (password anapaya) and anapaya-console (password console). The password_hashed value is created with the appliance-cli crypto kdf hash command.

    Loading...

    Telemetry configuration​

    If you do not configure the management API, you need to configure the telemetry endpoint to expose the metrics. The metrics are by default exposed on the management API endpoint. Please refer to Monitoring for further information on metrics.

    The example below configures telemetry to be exported on Loading.... Furthermore, appliance logs are exported to a Loki server at Loading..., using admin to authenticate to the server and add a label

    Loading...:

    Loading...

    to each log record.

    Loading...

    Hostname configuration​

    The hostname is used to identify the host in the telemetry data, thus it must be unique for each Anapaya appliance. The hostname must be a valid hostname according to the RFC 1123 specification.

    The example below configures the hostname to be Loading....

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

    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.

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

    Loading...

    The example below configures the appliance to use RADIUS authentication for SSH with a RADIUS server at Loading....

    Loading...
    note

    To enable RADIUS authentication for SSH, both the RADIUS server and the PAM configuration must be configured.

    Pluggable authentication module (PAM)​

    The Pluggable Authentication Module (PAM) configuration allows the user to configure custom PAM rules for the SSH service.

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

    The example below 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.

    Loading...