Configuration
The Anapaya appliance uses a unified configuration model. It stores all important settings, such as SCION connectivity, network interfaces, and management access, in one place. Instead of using multiple tools or scattered files, you manage everything through a single, structured configuration.
The configuration uses a declarative style: you describe the desired state, and the appliance applies it. Its clear, hierarchical layout makes it easy to read, understand, and maintain.
How to read the docs
Before diving into the configuration and schema itself, it's important to understand how to navigate
this documentation. The configuration is organized into top-level sections. Each top-level section
has its own page that explains how to configure that part of the appliance. Each page includes a
trimmed schema showing only the relevant fields. For instance, the Network interfaces configuration
reference lists all available options for the interfaces
section. Examples focus only on the relevant parts of the overall configuration. They do not
represent a complete configuration.
All configuration snippets and examples shown in the sub-pages are partial configurations. They are intended to be read and understood as part of the overall structure defined on this page.
Examples are available in both YAML and JSON encoding. As of release v0.40 the appliance supports both formats natively. In earlier releases, you had to push JSON-encoded configurations to the appliance. Use the tabs in the documentation to switch between the encodings. When using the appliance-cli to interact with the appliance, you can specify your desired output format.
If you are looking for a full example of a configuration, head to the deployment examples. These examples provide concrete configurations for different deployment scenarios.
Single EDGE deployment: Complete configuration
The single EDGE deployment showcases a configuration for a very basic single EDGE appliance deployment.
Configuration structure
The configuration contains top-level sections, each responsible for a specific part of the appliance (for example, networking or management). See the full schema and all available options in the Configuration reference below.
The following top-level sections of the appliance configuration are commonly used:
bgp: Configure local BGP peerscluster: Configure appliance clusteringfirewall: Configure the firewallinterfaces: Configure network interfacesmanagement: Configure appliance managementnat: Configure NATscion: Configure SCION connectivityscion_tunneling: Configure IP-in-SCION tunnelingsystem: Configure system settings
The following sections are less common. Configure them only with guidance from Anapaya support, or at your own risk:
advanced: Advanced configuration options (not commonly used)experiments: Experimental features and configurations
Each top-level section has its own page with detailed guidance and examples.
Configuration reference
Anapaya appliance configuration
advanced object
The necessary configuration data for the advanced section of the Anapaya appliance.
service_customizations object[]
The list of service-customizations on the Anapaya appliance.
Whether the service customization should be disabled.
falseThe service type for which the customized template is provided.
Possible values: [CA_FRONTEND, CONTROL, CRON, DAEMON, DATAPLANE, DATAPLANE_CONTROL, DISPATCHER, FRR, FRR_EXPORTER, GATEWAY, MOLE, NODE_EXPORTER, PROMTAIL, ROUTER, TELEMETRY, SHUTTLE, SHUTTLE_SERVER]
Whether the customized template should be skipped during configuration validation. This is particularly useful if the template is known to be valid, but the input data during validation is not sufficient.
falseThe actual customized template for the service.
bgp object
Top-level configuration and state for the BGP router.
global object
Global configuration for the BGP router
Local BGP autonomous system number of the router. Uses the 32-bit as-number type from the model in RFC 6991.
The list of network prefixes this BGP instance advertises.
Router id of the router - an unsigned 32-bit integer expressed in dotted quad notation.
Set the preferred source address when installing routes in the kernel.
neighbors object[]
Configuration for BGP neighbors
Reference to the MD5 authentication password for use with the neighboring device.
bfd object
BFD configuration parameters relating to the BGP neighbor
Minimum desired control packet transmission interval in milliseconds
Possible values: >= 10 and <= 60000
300Local session detection multiplier
Possible values: >= 2
3Enable BFD for the BGP neighbor
falseLocal address to use for BFD
For multihop sessions only: configure the minimum expected TTL for an incoming BFD control packet.
Possible values: >= 1 and <= 254
254Enable BFD multihop
falseMinimum required control packet receive interval in milliseconds
Possible values: >= 10 and <= 60000
300An optional textual description of the neighbor.
Specifying ebgp-multihop allows sessions with eBGP neighbors to establish when they are multiple hops away. When the neighbor is not directly connected and this setting is not enabled, the session will not establish.
Whether the BGP peer is enabled. In cases where the enabled leaf is set to false, the local system will not initiate connections to the neighbor, and will not respond to TCP connections attempts from the neighbor. If the BGP session is established at the time that this property is set to false, the session will be ceased.
trueThe local BGP autonomous system number that is to be used when establishing sessions with the remote peer or peer group, if this differs from the global BGP router autonomous system number.
Address of the BGP peer, either IPv4 or IPv6.
BGP autonomous system number of the peer.
timers object
Timers related to a BGP neighbor
Time interval in seconds between attempts to establish a session with the peer.
30Time interval in seconds that a BGP session will be considered active in the absence of keepalive or other messages from the peer. The hold-time is typically set to 3x the keepalive-interval.
30Time interval in seconds between transmission of keepalive messages to the neighbor. Typically set to 1/3 the hold-time.
10Minimum time in seconds which must elapse between subsequent UPDATE messages relating to a common set of NLRI being transmitted to a peer. This timer is referred to as MinRouteAdvertisementIntervalTimer by RFC 4721 and serves to reduce the number of UPDATE messages transmitted when a particular set of NLRI exhibit instability.
30transport object
Transport session parameters for the BGP neighbor
Set the local IPv4 address to be used for the session when sending BGP update messages. This may be expressed as either an IP address or the name of an interface.
BGP Time To Live (TTL) security check. Reference: RFC 5082: The Generalized TTL Security Mechanism (GTSM), RFC 7454: BGP Operations and Security.
cluster object
The configuration for the appliance cluster.
features object
The list of feature that are announced to the peers. Note that the actually announced value can depend on whether what features is locally enabled and configured.
Option to enable the announcement of support for the SCION RSS feature to the peers. If the local host does not support the SCION RSS feature, this option does not have any effect.
truepeers object[]
The list of peers in this cluster. This is used to configure the topology or the discovery of the topology of peer appliances in an organization.
Textual description for this peer.
features object
Configures the feature options of the peer. This field can not be set together with the synchronization field.
Option to statically enable the SCION RSS feature. If set to true, the local router enables UDP source port entropy on the underlay for SCION packets forwarded to the peer, such that the peer can leverage RSS for SCION traffic. This can greatly improve throughput performance. This must only be set to true if the peer supports the SCION RSS feature.
falseThe name of this peer used to identify the peer. This can be any string but must be unique among all peers.
scion object
The relevant SCION configuration of the peer. This can be used to define the relevant SCION components on the peer appliance so that paths via the peer appliance can also be used.
ases object[]
The list of SCION ASes on the peer.
control object
Configuration and state data for the control service in the peer.
The address of the control service. The address must be specified as host:port.
192.168.1.1:30100ISD-AS number of the AS.
1-ff00:0:110neighbors object[]
The neighbors for the SCION AS in the peer.
interfaces object[]
The list of interfaces on the peer for this neighbor AS.
SCION interface identifier. It must be unique in the SCION AS.
Possible values: >= 1 and <= 65535
Internal address of the peer router that owns the interface.
169.254.0.1:30100The maximum transmission unit in bytes for SCION packets. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as maximum Ethernet payload - IP Header - UDP Header.
14721472ISD-AS number of the neighbor AS.
2-ff00:0:210The relationship to the neighbor AS. If the local AS is core, this value must either be CORE or CHILD. If the local is non-core, this value must either be PARENT, CHILD or PEER.
Possible values: [CORE, CHILD, PARENT, PEER]
The shard ID of the peers in the AS.
scion_tunneling object
The relevant SCION tunneling configuration of the peer. This is used so that all appliances can announce the full list of SCION tunneling endpoints in the AS to other ASes.
endpoint object
The SCION tunneling endpoint on the peer appliance.
allowed_interfaces object[]
The SCION interfaces for each SCION AS that is configured on the peer, that are allowed to be used by this IP-in-SCION tunneling endpoint. This can be used to control incoming traffic, e.g., if a tunnel endpoint should only be reachable via SCION interfaces 1 and 2, allowed-interfaces should list them explicitly. Remote tunnel endpoints will then only choose paths entering the respective local AS via SCION interface 1 or 2. If the IP-in-SCION tunneling endpoint on the peer appliance should be reachable via a SCION interface of another appliance, the allowed-interfaces list must be configured with the respective SCION interfaces. By default the list is empty, in this case the appliance will automatically configure the SCION interfaces that are configured on the peer as allowed-interfaces. Automatic configuration can be disabled by setting disable_auto_allowed_interfaces.
List of allowed interfaces for this SCION AS
[2,3]The SCION AS where the list of allowed interfaces applies. Packets to this IP-in-SCION tunnel endpoint in this SCION AS will only arrive on the listed interfaces.
Port number for control traffic. The control address is constructed from the IP address and this control port. The control address is used to exchange IP routing information as part of SGRP. If not set, or zero, the control port will be dynamically allocated.
40201Port number for data traffic. The data address is constructed from the IP address and this control port. The data address is used for the IP-in-SCION encapsulated traffic stream. If not set, or zero, the data port will be dynamically allocated.
40200Whether the automatic configuration of allowed interfaces should be disabled. When disabled, the IP-in-SCION tunneling endpoint of the peer will be reached by remote endpoints on all SCION interfaces of the locally configured AS. When enabled (default), the peer IP-in-SCION tunneling endpoint will only be reached by remote endpoints on the SCION interfaces that are configured on the peer appliance.
IP address of the peer IP-in-SCION endpoint.
192.168.1.100Port number for probing traffic. The probe address is constructed from the IP address and this probe port. The probe address is used by remote tunnel endpoints in their health probing. If not set, or zero, the probe port will be dynamically allocated.
40202synchronization object
The synchronization configuration for this peer. This can be used to configure the automatic synchronization of topology information and supported features. Automatic synchronization of topology and supported features is not recommended for EDGE deployments. Instead static configuration is recommended. This field can not be set together with the scion, scion-tunneling, and features field.
The gRPC address of this peer, used for synchronization of appliance information
192.168.1.1:30100synchronization object
The configuration data necessary for the anapaya cluster synchronization. This determines how frequently this appliance synchronizes its local data with its peers, if synchronization is enabled.
The address where peers can fetch topology information. If this is not set, topology information is not exposed to peers and should be statically configured on the peers.
192.0.2.3:40000The interval between two consecutive topology synchronizations attempts to the cluster peers. Must only be set if dynamic topology discovery is enabled. It requires a unit suffix out of ['d', 'h', 'm', 's']. The encoding consists of a decimal number concatenated with a suffix; for example, '5s', '10m', '12h', and '1d'.
1mexperiments object
Section for experimental options.
features object[]
The list of features.
The name of the feature
The value of the feature
firewall object
The necessary configuration data for firewalling the Anapaya appliance.
The firewall mode declares how the appliance handles firewall rules. Depending on the mode, the appliance either generates a default set of rules, prepends some custom rules, or uses only the specified custom rules.
Possible values: [AUTO, PREPEND, CUSTOM, UNMANAGED]
tables object[]
The list of nftables tables on the Anapaya appliance. The usage of the list depends on the firewall mode.
chains object[]
Chains defined within the nftables table.
The type and usage of the chain. This must be set for base chains and unset for regular chains.
Possible values: [FILTER, ROUTE, NAT]
The packet processing step during which the chain should be executed. This must be set for base chains and unset for regular chains. For more information on the chain hooks, please refer to https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_hooks.
Possible values: [PREROUTING, INPUT, FORWARD, OUTPUT, POSTROUTING]
The name of the chain.
The default policy that will be applied to packets that reach the end of the chain. For more information on chain policies, please refer to https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_policy.
Possible values: [ACCEPT, DROP]
The priority of the chain. This must be set for base chains and unset for regular chains.
rules object[]
Rules defined as part of a chain within a firewall table.
Description, or comment, for the firewall rule.
The rule definition consists of expressions and statements in string format. The expressions are evaluated from left to right and if the packet matches the expressions the statement is executed. For information on the supported syntax for expressions and statements, please refer to https://wiki.nftables.org/wiki-nftables/index.php/Main_Page#Expressions:_Matching_packets and https://wiki.nftables.org/wiki-nftables/index.php/Main_Page#Statements:_Acting_on_packet_matches.
The sequence ID determines the order in which sequence the firewall rules are applied. The sequence ID must be unique for each entry. Target devices apply the rules in order of ascending sequence ID (low to high).
1counters object[]
Optional named counters defined within the nftables table.
The name of the counter.
The family type of the nftables. For more information on table families, please refer to https://wiki.nftables.org/wiki-nftables/index.php/Nftables_families.
Possible values: [IP, IP6, INET]
Name of the nftables table.
interfaces object
Top-level configuration and state for interfaces.
bonds object[]
Top-level configuration and state for the bond interfaces.
Whether to accept the route advertisements for the corresponding interface. (This is currently supported only for the interfaces that are using the Linux driver.)
falseThe addresses configured on this interface. Each address must be a valid IP prefix in CIDR notation.
gateway object
The gateway for the network interface.
The gateway address for the IPv4 networking stack. Note that there must only be one IPv4 gateway configured across all the interfaces.
The gateway address for the IPv6 networking stack. Note that there must only be one IPv6 gateway configured across all the interfaces.
The list of interfaces that are part of this bond.
Possible values: >= 1
The MAC address to use on this interface.
It is of the form XX:XX:XX:XX:XX:XX.
The MTU (Maximum Transmission Unit) to be used on this interface.
15001472The name of the network interface.
neighbors object[]
The static neighbors configured on this network interface.
The IP address.
An optional human-readable string to comment on this neighbor.
The MAC address corresponding to the address.
It is of the form XX:XX:XX:XX:XX:XX.
The sequence id determines the order of the neighbor entries.
3routes object[]
The routes which are configured on this network interface.
An optional human-readable string to comment on this route.
The source IP address for traffic going through the route.
The metric for the route. The lower its value, the higher its priority.
10The sequence id determines the order of the route entries.
3The destination prefix in CIDR notation of this route.
The next hop address which should be used for the prefix.
The number of descriptors in the receive queue. (This option is currently supported only for VPP interfaces.)
10242048The number of descriptors in the transmit queue. (This is currently supported only for VPP interfaces.)
10242048vrrp object[]
The VRRP (Virtual Router Redundancy Protocol) configurations for this interface.
The list of virtual IP addresses. It must contain at least one IP address. Each sequence entry is in CIDR notation.
Possible values: >= 1
If set to true, the preempt mode is disabled. This means that the router will not preempt the master even if it has a higher priority than the current master. If set to false, the router will preempt the master if it has a higher priority than the current master.
falseOptional list of IP addresses of the VRRP peers. If the list is empty, the router will send VRRP packets to the multicast address. If the list is not empty, the router will send VRRP packets to the unicast addresses specified in the list.
Possible values: >= 1
The priority value to be used by this VRRP router. Higher means higher priority and it ranges between 1 and 255 (decimal).
117The virtual router identifier, which ranges between 1 and 255 (decimal).
3ethernets object[]
Top-level configuration and state for ethernet interfaces.
Whether to accept the route advertisements for the corresponding interface. (This is currently supported only for the interfaces that are using the Linux driver.)
falseThe addresses configured on this interface. Each address must be a valid IP prefix in CIDR notation.
The driver which should be used for the interface.
Possible values: [LINUX, VPP, VPP_DPDK, VPP_VMXNET3, VPP_MEMIF, VPP_RDMA]
gateway object
The gateway for the network interface.
The gateway address for the IPv4 networking stack. Note that there must only be one IPv4 gateway configured across all the interfaces.
The gateway address for the IPv6 networking stack. Note that there must only be one IPv6 gateway configured across all the interfaces.
The MAC address to use on this interface.
It is of the form XX:XX:XX:XX:XX:XX.
The MTU (Maximum Transmission Unit) to be used on this interface.
15001472The name of the network interface.
neighbors object[]
The static neighbors configured on this network interface.
The IP address.
An optional human-readable string to comment on this neighbor.
The MAC address corresponding to the address.
It is of the form XX:XX:XX:XX:XX:XX.
The sequence id determines the order of the neighbor entries.
3routes object[]
The routes which are configured on this network interface.
An optional human-readable string to comment on this route.
The source IP address for traffic going through the route.
The metric for the route. The lower its value, the higher its priority.
10The sequence id determines the order of the route entries.
3The destination prefix in CIDR notation of this route.
The next hop address which should be used for the prefix.
The number of descriptors in the receive queue. (This option is currently supported only for VPP interfaces.)
10242048The number of descriptors in the transmit queue. (This is currently supported only for VPP interfaces.)
10242048vpp object
The VPP driver specific configuration.
The number of receive queues. Automatically configured if the value is 0.
0Whether vlan-strip-offload on should be added to the interface
configuration of the VPP dataplane.
falsevrrp object[]
The VRRP (Virtual Router Redundancy Protocol) configurations for this interface.
The list of virtual IP addresses. It must contain at least one IP address. Each sequence entry is in CIDR notation.
Possible values: >= 1
If set to true, the preempt mode is disabled. This means that the router will not preempt the master even if it has a higher priority than the current master. If set to false, the router will preempt the master if it has a higher priority than the current master.
falseOptional list of IP addresses of the VRRP peers. If the list is empty, the router will send VRRP packets to the multicast address. If the list is not empty, the router will send VRRP packets to the unicast addresses specified in the list.
Possible values: >= 1
The priority value to be used by this VRRP router. Higher means higher priority and it ranges between 1 and 255 (decimal).
117The virtual router identifier, which ranges between 1 and 255 (decimal).
3gres object[]
Generic routing encapsulation (GRE) interfaces.
Whether to accept the route advertisements for the corresponding interface. (This is currently supported only for the interfaces that are using the Linux driver.)
falseThe addresses configured on this interface. Each address must be a valid IP prefix in CIDR notation.
The destination IP address for the GRE tunnel.
gateway object
The gateway for the network interface.
The gateway address for the IPv4 networking stack. Note that there must only be one IPv4 gateway configured across all the interfaces.
The gateway address for the IPv6 networking stack. Note that there must only be one IPv6 gateway configured across all the interfaces.
The MAC address to use on this interface.
It is of the form XX:XX:XX:XX:XX:XX.
The MTU (Maximum Transmission Unit) to be used on this interface.
15001472The name of the network interface.
neighbors object[]
The static neighbors configured on this network interface.
The IP address.
An optional human-readable string to comment on this neighbor.
The MAC address corresponding to the address.
It is of the form XX:XX:XX:XX:XX:XX.
The sequence id determines the order of the neighbor entries.
3routes object[]
The routes which are configured on this network interface.
An optional human-readable string to comment on this route.
The source IP address for traffic going through the route.
The metric for the route. The lower its value, the higher its priority.
10The sequence id determines the order of the route entries.
3The destination prefix in CIDR notation of this route.
The next hop address which should be used for the prefix.
The number of descriptors in the receive queue. (This option is currently supported only for VPP interfaces.)
10242048The source IP address for the GRE tunnel.
The number of descriptors in the transmit queue. (This is currently supported only for VPP interfaces.)
10242048vrrp object[]
The VRRP (Virtual Router Redundancy Protocol) configurations for this interface.
The list of virtual IP addresses. It must contain at least one IP address. Each sequence entry is in CIDR notation.
Possible values: >= 1
If set to true, the preempt mode is disabled. This means that the router will not preempt the master even if it has a higher priority than the current master. If set to false, the router will preempt the master if it has a higher priority than the current master.
falseOptional list of IP addresses of the VRRP peers. If the list is empty, the router will send VRRP packets to the multicast address. If the list is not empty, the router will send VRRP packets to the unicast addresses specified in the list.
Possible values: >= 1
The priority value to be used by this VRRP router. Higher means higher priority and it ranges between 1 and 255 (decimal).
117The virtual router identifier, which ranges between 1 and 255 (decimal).
3loopbacks object[]
Top-level configuration and state for loopback interfaces.
The list of addresses configured on the loopback interface.
The name of the loopback interface, which must have a 'loop' prefix.
shuttles object[]
Top-level configuration and state for Shuttle interfaces.
Disable the Shuttle interface. By default, it is false. If disabled, the Shuttle interface is not created and existing Shuttle interface will be removed. Disabling an existing interface preserves the corresponding certificate and private key, which can be used after re-enabling the interface.
falseLocal endpoint of the Shuttle tunnel. In two alternative forms ISD-AS,IP, or IP,
where ISD-AS is an ISD-AS number, IP is an IPv4/IPv6 address
1-ff00:0:1,127.0.0.1The MTU (Maximum Transmission Unit) to be used on this interface. The user does not need to change this default value. The value is chosen to work in extrem circumstances.
1000The name of the network interface.
servers object[]
The list of Shuttle servers.
Remote endpoint of the Shuttle tunnel. In the form host:port,
where host is a SCION host address, in ISD-AS,IP format, where ISD-AS is the
ISD-AS number and IP is the IPv4 address, and port is a port number
[1-ff00:0:1,127.0.0.1]:443virtual_functions object[]
Top-level configuration and state for VF interfaces.
Whether to accept the route advertisements for the corresponding interface. (This is currently supported only for the interfaces that are using the Linux driver.)
falseThe addresses configured on this interface. Each address must be a valid IP prefix in CIDR notation.
gateway object
The gateway for the network interface.
The gateway address for the IPv4 networking stack. Note that there must only be one IPv4 gateway configured across all the interfaces.
The gateway address for the IPv6 networking stack. Note that there must only be one IPv6 gateway configured across all the interfaces.
The name of the network interface that is used as the parent on which the virtual function will be created.
The MAC address to use on this interface.
It is of the form XX:XX:XX:XX:XX:XX.
The MTU (Maximum Transmission Unit) to be used on this interface.
15001472The name of the network interface.
neighbors object[]
The static neighbors configured on this network interface.
The IP address.
An optional human-readable string to comment on this neighbor.
The MAC address corresponding to the address.
It is of the form XX:XX:XX:XX:XX:XX.
The sequence id determines the order of the neighbor entries.
3The number of receive queues. Automatically configured if the value is 0.
0routes object[]
The routes which are configured on this network interface.
An optional human-readable string to comment on this route.
The source IP address for traffic going through the route.
The metric for the route. The lower its value, the higher its priority.
10The sequence id determines the order of the route entries.
3The destination prefix in CIDR notation of this route.
The next hop address which should be used for the prefix.
The number of descriptors in the receive queue. (This option is currently supported only for VPP interfaces.)
10242048The number of descriptors in the transmit queue. (This is currently supported only for VPP interfaces.)
10242048vrrp object[]
The VRRP (Virtual Router Redundancy Protocol) configurations for this interface.
The list of virtual IP addresses. It must contain at least one IP address. Each sequence entry is in CIDR notation.
Possible values: >= 1
If set to true, the preempt mode is disabled. This means that the router will not preempt the master even if it has a higher priority than the current master. If set to false, the router will preempt the master if it has a higher priority than the current master.
falseOptional list of IP addresses of the VRRP peers. If the list is empty, the router will send VRRP packets to the multicast address. If the list is not empty, the router will send VRRP packets to the unicast addresses specified in the list.
Possible values: >= 1
The priority value to be used by this VRRP router. Higher means higher priority and it ranges between 1 and 255 (decimal).
117The virtual router identifier, which ranges between 1 and 255 (decimal).
3vlans object[]
Top-level configuration and state for VLAN interfaces.
Whether to accept the route advertisements for the corresponding interface. (This is currently supported only for the interfaces that are using the Linux driver.)
falseThe addresses configured on this interface. Each address must be a valid IP prefix in CIDR notation.
gateway object
The gateway for the network interface.
The gateway address for the IPv4 networking stack. Note that there must only be one IPv4 gateway configured across all the interfaces.
The gateway address for the IPv6 networking stack. Note that there must only be one IPv6 gateway configured across all the interfaces.
The VLAN ID of the VLAN interface. It ranges between 0 and 4095.
Possible values: <= 4095
The name of the physical interface used for this VLAN.
The MAC address to use on this interface.
It is of the form XX:XX:XX:XX:XX:XX.
The MTU (Maximum Transmission Unit) to be used on this interface.
15001472The name of the network interface.
neighbors object[]
The static neighbors configured on this network interface.
The IP address.
An optional human-readable string to comment on this neighbor.
The MAC address corresponding to the address.
It is of the form XX:XX:XX:XX:XX:XX.
The sequence id determines the order of the neighbor entries.
3routes object[]
The routes which are configured on this network interface.
An optional human-readable string to comment on this route.
The source IP address for traffic going through the route.
The metric for the route. The lower its value, the higher its priority.
10The sequence id determines the order of the route entries.
3The destination prefix in CIDR notation of this route.
The next hop address which should be used for the prefix.
The number of descriptors in the receive queue. (This option is currently supported only for VPP interfaces.)
10242048The number of descriptors in the transmit queue. (This is currently supported only for VPP interfaces.)
10242048vrrp object[]
The VRRP (Virtual Router Redundancy Protocol) configurations for this interface.
The list of virtual IP addresses. It must contain at least one IP address. Each sequence entry is in CIDR notation.
Possible values: >= 1
If set to true, the preempt mode is disabled. This means that the router will not preempt the master even if it has a higher priority than the current master. If set to false, the router will preempt the master if it has a higher priority than the current master.
falseOptional list of IP addresses of the VRRP peers. If the list is empty, the router will send VRRP packets to the multicast address. If the list is not empty, the router will send VRRP packets to the unicast addresses specified in the list.
Possible values: >= 1
The priority value to be used by this VRRP router. Higher means higher priority and it ranges between 1 and 255 (decimal).
117The virtual router identifier, which ranges between 1 and 255 (decimal).
3wireguards object[]
Top-level configuration and state for Wireguard interfaces.
The addresses configured on this interface. Each address must be a valid IP prefix in CIDR notation.
gateway object
The gateway for the network interface.
The gateway address for the IPv4 networking stack. Note that there must only be one IPv4 gateway configured across all the interfaces.
The gateway address for the IPv6 networking stack. Note that there must only be one IPv6 gateway configured across all the interfaces.
The MTU (Maximum Transmission Unit) to be used on this interface.
1420The name of the network interface.
peers object[]
The list of Wireguard peers.
A list of IPv4/IPv6 addresses with a CIDR mask. The list indicates the addresses from which the peer is allowed to connect. Catch all are expressed as 0.0.0.0/0 (IPv4) and ::/0 (IPv6)
Remote endpoint of the Wireguard tunnel. In the form host:port
where host can be an IPv4/IPv6 address or a hostname,
and port is a port number.
The base64 encoded public key of the Wireguard peer.
This enables the point-to-point mode on the interface, meaning that it is a direct link between two machines with nobody else listening on it.
The port to listen on.
routes object[]
The routes for the network interface.
An optional human-readable string to comment on this route.
The source IP address for traffic going through the route.
The metric for the route. The lower its value, the higher its priority.
10The sequence id determines the order of the route entries.
3The destination prefix in CIDR notation of this route.
The next hop address which should be used for the prefix.
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.
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.
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.
$2y$10$QNodxwKFABMWu4XlFPmZDOSfqxrsqNvrSn487lCi7tJ/4nTsT/f02List 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
Name of the user.
adminBy 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.
falseinterfaces 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.
Description, or comment, for the interface.
Network interface name to listen on.
The TCP or UDP port to listen on.
listeners object[]
List of management API listeners that define where the API is exposed
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.
127.0.0.1:443Description, or comment, for the listener.
oauth object
Open authorization (OAuth) configuration that can authorize users who want to access the Anapaya appliance management API.
Whether the feature is enabled.
falseidentity_providers object[]
The identity providers. Currently only one is supported.
The base URL for the identity provider.
https://anapaya.eu.auth0.com/The client ID for this identity provider.
Reference to the client secret for this identity provider.
The identifier of the provider. Must be unique among all providers.
The URL for fetching the open ID configuration.
https://anapaya.eu.auth0.com/.well-known/openid-configurationThe tenant ID for Azure AD
The type of the provider.
Possible values: [GENERIC, AZURE_AD]
roles object[]
Roles configuration used for OAuth.
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.
Name of the role.
token_verification_keys object[]
Keys to verify JWTs.
The identifier of the key. Must be unique among all keys.
anapaya.auth0URL for fetching JSON Web Key Sets.
https://anapaya.eu.auth0.com/.well-known/jwks.jsonWhether the management API is allowed to be exposed without authentication. Always make sure to properly protect your API.
falseThe 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.
anapaya-applianceedge-geneva-corpbankpam 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.
List of PAM account modules that are used for the service.
List of PAM authentication modules that are used for the service.
Description or comment for the service.
Whether the PAM service is enabled.
falseList of PAM password modules that are used for the service.
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.
sshdList of PAM session modules that are used for the service.
ssh object
Configuration for SSH access to the Anapaya appliance.
Whether password login is enabled for SSH access to the Anapaya appliance.
falseradius 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.
The IP address of the RADIUS server.
Description or comment for the server.
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.
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.
Description or comment for the key.
The SSH public key of the user.
AAAAB3NzaC1yc2The unix username of the user.
anapayatelemetry object
Anapaya appliance telemetry configuration.
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.
:42001flow_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.
URL of the flow-collector where the flow metric information is sent to. Supports 'http', 'https' and 'grpc' transport
Whether the feature is enabled.
falseThe minimum time interval at which flow metrics are exported to the collector.
60sTime interval after which inactive flows are considered expired and are marked for cleanup.
120sURL 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).
Name of the label.
Value of the label.
logging object
Configuration for shipping logs to a remote log aggregation system.
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.
Reference to the password used for basic auth.
The username to use for basic auth.
promtailThe tenant ID used to push logs to Loki. If unset, single tenant mode is assumed.
tls_config object
Configuration for TLS connection.
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.
falseThe url which is used to push logs to Loki.
https://loki.anapaya.net/loki/api/v1/pushnat object
Top-level configuration and state for NAT.
dnats object[]
Top-level configuration and state for the destination NAT.
The IP address that needs to be translated. This is an exact match on the destination IP of packets received from the IP-in-SCION tunnel.
An optional textual description of the destination NAT configuration.
The mapped destination IP address. The destination IP of matched packets is replaced by this IP.
port_mappings object[]
The list of port mappings for the destination NAT. Mandatory when ingress source NAT is enabled as well.
An optional textual description of the port mapping configuration.
The mapped destination port. The destination port of matched packets is replaced by this port.
The destination port that needs to be translated. This is an exact match on the destination port of packets received from the IP-in-SCION tunnel.
Transmission layer protocol. Supported protocols are (tcp, udp).
snat object
Top-level configuration and state for the source NAT.
The list of IP prefixes to use as the source NAT pool.
The list of IP prefixes to exclude from the NAT. The number of IP addresses that can be excluded is limited.
The list of interfaces to do the NAT. These are typically interfaces connected to the local network
scion object
The SCION section contains the configuration of the SCION protocol and AS. It consists of a list of SCION AS configurations. An Anapaya appliance can have configurations for multiple SCION ASes, however, in most cases there will only be a single SCION AS configured. Additionally, the path and beacon synchronization between multiple appliances can be configured in this section.
ases object[]
List of SCION ASes that this device is part of identified by their ISD-AS identifier.
ca_service object
SCION CPPKI (Control Plane Public Key Infrastructure) CA service configuration data. This section defines how the anapaya-scion interacts with the SCION CPPKI CA service backend. It is only required for SCION ASes that act as a CA in their respective ISD.
anapaya_vault object
The configuration data of the Anapaya SCION CPPKI CA service. This section must be provided
when the CA service type is ANAPAYA_VAULT.
The list of addresses where the Anapaya Vault backend can be reached. This list must be non-empty.
credentials object
The necessary credentials to be logged into the Anapaya Vault backend.
The role ID used to authenticate with the Vault backend via the AppRole Authentication Method. See https://www.vaultproject.io/docs/auth/approle for more details.
Reference to the secret ID used to authenticate with the Vault backend via the AppRole Authentication Method. See https://www.vaultproject.io/docs/auth/approle for more details.
validation object
The validation option configures how the Anapaya Vault backend validate CSRs.
The subject option configures how the Anapaya Vault backend validates the subject of the CSRs.
Possible values: [MATCHING_ISD_AS, EXACT_MATCH]
external object
The configuration data for the External SCION CPPKI CA service. This section must be
provided when the CA service is of type EXTERNAL.
The address where the external SCION CPPKI CA service can be reached.
192.0.2.3:5000The client ID that is used to authenticate with the CA service. The client ID is set in the 'sub' and 'iss' claim of the generated JWT. If unset, a generic client ID based on the ISD-AS is used.
Reference to the shared secret used between the appliance and the CA service (used to generate JWTs for authentication).
The type of CA service that is used by the appliance.
EXTERNAL is a generic CA backend not implemented by Anapaya. Note that the external CA
backend must implement the SCION CA
API to be compatible
with the Anapaya appliance. If this service type is used, the external section must be
configured.
ANAPAYA_VAULT is the SCION CA backend provided by Anapaya. It is based on Hashicorp
Vault with a suitable frontend. If this service type is used, the anapaya_vault
section must be configured.
IN_PROCESS is a CA service that is implemented in the Anapaya appliance. It should
only be used for testing purposes and is not suitable for productive use. If this
service type is used, no other section needs to be configured.
Possible values: [EXTERNAL, ANAPAYA_VAULT, IN_PROCESS]
control object
The configuration for the SCION control service.
The address of the control service. Clients connect to this address to request control
plane data, e.g., SCION path segments. The address needs to be specified as a string in the
format
192.168.1.1:30100Whether the service is enabled.
Indicate whether the AS is core in its ISD. The core flag must only be set if the AS is a
core AS in its ISD (as indicated in the TRC of the ISD). A core AS provides connectivity to
other SCION ISDs and operates the main path directories within its ISD. It also regularly
initiates path construction beacons that create path segments to other SCION ASes in the
same ISD or to other core ASes in different ISDs. For most of the ASes this is not the case
and the flag must be set to false or not specified (defaults to false)
falsecppki object
SCION CPPKI configuration for the SCION AS.
Whether automatic renewal of AS certificates should be disabled. Usually, this value should not be set. By disabling certificate renewal, the appliance is set into a manual mode where new AS certificates must be provisioned manually and periodically.
Whether fallback to the certificate authorities listed in the latest TRC should be disabled. By disabling this feature, the appliance will only use the issuers explicitly set in the configuration. If not disabled, the certificate authorities in the latest TRC are tried in the order that their certificate appears in the TRC.
issuers object[]
The SCION CPPKI Issuers that issue certificates for the local SCION AS. The list of issuers is tried in order of their priority. If no issuers are set explicitly, the renewal process will use the issuer of the newest existing SCION CPPKI AS Certificate.
The ISD-AS identifier of the issuing AS.
1-ff00:0:120The priority of the issuing AS. The appliance attempts to get certificates issued from the AS with the highest priority. The value 0 indicates the highest priority, higher numbers are lower priority.
Default indicates whether the respective SCION AS should be used by default as the source
AS by SCION applications, e.g., scion ping or scion showpaths. The configurations with
more than one default ASes will be rejected because there can only be one default AS. If
there is only a single AS configured, it will be the default. Therefore, this setting is
only necessary if multiple ASes are configured on the appliance.
falsedetails object
User-defined details about the SCION AS for informational purpose.
User-defined description, or comment, that describes this SCION AS.
SCION AS name for informational purpose.
Reference to the forwarding key of this AS. The forwarding key secret is used to authenticate the hop field of the SCION path which corresponds to this AS. It is a local secret that only needs to be known to the AS. The forwarding key MUST be identical across all appliances in an AS. The referenced secret must be a base64-encoded string.
The ISD-AS identifier is the tuple that uniquely identifies the AS within a SCION isolation domain (ISD). This number is usually assigned by a numbering authority.
1-ff00:0:110neighbors object[]
List of neighbor SCION ASes that this device is connected to via one or multiple SCION interfaces. Each entry is identified by the remote ISD-AS.
Description, or comment, for the neighbor AS.
interfaces object[]
The local SCION interfaces in the current AS that link to the neighbor AS. The local end of the link is an external SCION interface.
UDP/IP underlay endpoint of the SCION Interface. The data plane traffic is received on this address. The address must be specified as host:port. Both host and port must be specified.
169.254.0.1:30100The administrative state of the interface with one of the following values:
UPThe interface is up and ready to send/receive SCION packets as well as being advertised during beaconing.DATAPLANE_ONLYThe interface is up and ready to send/receive SCION packets, but is not advertised during beaconing.ADMIN_DOWNThe interface is down and neither sends/receives SCION packets nor is it advertised during beaconing.
Experimental: Currently only UP is supported.
Possible values: [UP, ADMIN_DOWN, DATAPLANE_ONLY]
bfd object
Bidrirectional Forwarding Detection (BFD) configuration for the SCION interface. BFD is used to track the healthiness of a SCION link.
The minimum interval between transmission of BFD control packets that the operator desires. This value is advertised to the peer, however the actual interval used is specified by taking the maximum of desired-minimum-tx-interval and the value of the remote required-minimum-receive interval value. This value is specified as an integer number of microseconds.
200000The number of packets that must be missed to declare this session as down. The detection interval for the BFD session is calculated by multiplying the value of the negotiated transmission interval by this value.
Possible values: >= 1 and <= 255
3If set to true, then the BFD session is enabled on the SCION interface - if it is set to false, BFD is disabled on that SCION interface. When disabled, the health of the interface is not tracked and it is assumed to be healthy. Note that the remote side of this SCION interface should have the same setting for enabled.
trueThe minimum interval between received BFD control packets that this system should support. This value is advertised to the remote peer to indicate the maximum frequency (i.e., minimum inter-packet interval) between BFD control packets that is acceptable to the local system.
200000Description, or comment, for the SCION interface.
Flag to activate SCION RSS for this link. If activated, the router utilizes UDP source port entropy on the underlay such that the remote router can leverage RSS for SCION traffic. This can greatly improve throughput performance. For low throughput SCION links (up to 1 Gbps), enabling SCION RSS is not necessary. Before enabling this feature, please ensure that the remote router supports SCION RSS.
falseSCION interface identifier. It must be unique in the SCION AS.
Possible values: >= 1 and <= 65535
remote object
Remote SCION interface endpoint of the link.
UDP/IP underlay endpoint of the remote SCION Interface. The address must be specified as host:port. This information is provided by the neighbor AS.
169.254.0.2:30200The SCION interface identifier of the remote end of the link. This information is provided by the neighbor AS.
Possible values: >= 1 and <= 65535
The maximum transmission unit in bytes for SCION packets on the external interface. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as maximum Ethernet payload - IP Header - UDP Header. Note that the SCION MTU can differ between the various links and also from SCION MTU supported in the internal network of the local AS.
14721472ISD-AS number of the neighbor AS.
2-ff00:0:210The relationship to the neighbor AS. If the local AS is core, this value must either be CORE or CHILD. If the local AS is non-core, this value must either be PARENT, CHILD or PEER.
Possible values: [CORE, CHILD, PARENT, PEER]
router object
The configuration for the SCION router service. The address configures where the router is exposed. AS internal hosts send SCION data plane traffic to this address for forwarding over the local SCION interfaces.
Whether the service is enabled.
The internal SCION interface is where the appliance receives SCION packets from AS internal
hosts/applications for forwarding. It is defined as a UDP/IP network endpoint on which the
SCION packets are received from the internal network. The endpoint must be specified as a
string in the format
192.168.1.1:30100The maximum transmission unit in bytes for SCION packets. This represents the protocol data unit (PDU) of the SCION layer on this interface and is usually calculated as maximum Ethernet payload - IP Header - UDP Header. If the Ethernet MTU is 1500, the SCION MTU is 1472 for an IPv4 underlay network and 1452 for an IPv6 underlay network.
14721472The control and the data plane of a SCION AS is split into multiple shards. Each shard is responsible for processing and disseminating path information only for a subset of links. Shards are units that operate and fail independently from other shards. Usually, each appliance operates as a separate shard to increase the resiliency of the network. This field is the ID of the shard to which the control service and the router on this appliance belong.
synchronization object
The synchronization configuration contains the configuration for SCION path and beacon synchronization.
The interval between two consecutive beacon synchronizations attempts to the cluster peers. It requires a unit suffix out of ['d', 'h', 'm', 's']. The encoding consists of a decimal number concatenated with a suffix; for example, '5s', '10m', '12h', and '1d'.
4sThe interval between two consecutive path segment synchronizations attempts to cluster peers. It requires a unit suffix out of ['d', 'h', 'm', 's']. The encoding consists of a decimal number concatenated with a suffix; for example, '5s', '10m', '12h', and '1d'.
4sscion_tunneling object
Top-level configuration and state for IP-in-SCION tunneling.
domains object[]
List of domains that define the rules by which IP packets are routed. A domain is a subset of the IP space that shares the same policies.
Whether this domain is the default domain. The default domain is assumed to accept the whole IP space that is not covered by other domains. Because of this it may not specify an accept-filter.
Optional description, or comment, for the domain.
The domain. It matches all packets and allows any
path to be used.Whether the domain should be disabled.
falseThe payload encryption mode for the domain.
Possible values: [DISABLED, ENABLED, OPTIONAL]
List of local ISD-AS identifiers that belong to this domain. Traffic towards remote ISD-ASes is guaranteed to only use paths that start at one of these local ISD-ASes.
The name of the domain.
Default Domainprefixes object
List of IP prefix matchers to filter the announced and received prefixes.
accept_filter object[]
List of IP prefix matchers to define which prefixes announced by remotes ISD ASes are accepted. Only the matching subset of a prefix announced by a remote ISD-AS is is accepted for routing.
Specify matchers action.
Possible values: [ACCEPT, REJECT]
Optional description for the prefix matcher.
The list of IP prefixes used for matching. The matcher matches all IP prefixes that are contained in the union of the specified IP prefixes, i.e. it matches all listed prefixes as well as their contained more specific prefixes.
["192.168.1.0/24"]The sequence ID determines the order in which sequence the prefix matchers are applied. The sequence ID must be unique for each entry. Target devices apply the prefix matchers in order of ascending sequence ID (low to high) accepting all IPs that are in accepted matchers and rejecting the ones that are in rejected matchers.
1announce_filter object[]
List of IP prefix matchers to filter prefixes announced to remotes. The prefixes to be announced are configured in the static announcements or BGP. Only the subset of the routes that matches the announce filter is advertised to the remotes.
Specify matchers action.
Possible values: [ACCEPT, REJECT]
Optional description for the prefix matcher.
The list of IP prefixes used for matching. The matcher matches all IP prefixes that are contained in the union of the specified IP prefixes, i.e. it matches all listed prefixes as well as their contained more specific prefixes.
["192.168.1.0/24"]The sequence ID determines the order in which sequence the prefix matchers are applied. The sequence ID must be unique for each entry. Target devices apply the prefix matchers in order of ascending sequence ID (low to high) accepting all IPs that are in accepted matchers and rejecting the ones that are in rejected matchers.
1remote_isd_ases object[]
List of remote ISD-AS identifiers that belong to this domain. Prefix announcements will be accepted from these remote ISD-ASes. All IP traffic will be tunneled over paths that end in one of these remote ISD-ASes.
Specify the matchers action.
Possible values: [ACCEPT, REJECT]
Description for the remote matcher.
The ISD-AS identifier. The matcher matches the ISD-AS identifier of a SCION AS. 0 indicates a wildcard (both for ISD and AS).
0-ff00:0:310The sequence ID determines the order in which sequence the remote matchers are applied. The sequence ID must be unique for each entry. Target devices apply the remote matchers in order of ascending sequence ID (low to high).
1traffic_policies object[]
List of traffic policies that configure the types of traffic that are tunneled via this domain and the tunnel properties. A traffic policy defines a matcher on the IP traffic (the traffic matcher). If the IP traffic matches, it is tunneled to the remote SCION AS. Acceptable paths for the tunnel are defined via the path policy
The optional description of the traffic policy.
Default traffic policyfailover_sequence object[]
A list of failover sequence entries, each of them associated with a path filter. If there's no live path left after applying the first filter the second one is tried and so on.
Name of the path filter associated with the failover sequence entry.
Sequence number of the failover sequence entry. Sequence numbers define the ordering of the items which turn detemines how the failover between different path filters happens.
1The sequence ID determines the order in which sequence the traffic policies are applied. The sequence ID must be unique for each entry. Target devices try to find the first entry with a matching traffic matcher in ascending order determined by the sequence ID (low to high).
1Reference of the traffic matcher that is utilized by this policy. The traffic matcher is a selector for the IP packets covered by this traffic policy.
endpoint object
Local IP-in-SCION tunnel endpoint configuration
allowed_interfaces object[]
The SCION interfaces for each local SCION AS that are allowed to be used by this IP-in-SCION tunneling endpoint. This can be used to control incoming traffic, e.g., if a tunnel endpoint should only be reachable via SCION interfaces 1 and 2, allowed-interfaces should list them explicitly. Remote tunnel endpoints will then only choose paths entering the respective local AS via SCION interface 1 or 2. If the IP-in-SCION tunneling endpoint on this appliance should be reachable via a SCION interface of a peer appliance, the allowed-interfaces list must be configured with the respective SCION interface of the peer appliance. By default the list is empty, in this case the appliance will automatically configure the locally configured SCION interfaces as allowed-interfaces. Automatic configuration is disabled if topology synchronization is enabled or if disable_auto_allowed_interfaces is set.
List of allowed interfaces for this SCION AS
[2,3]The SCION AS where the list of allowed interfaces applies. Packets to this IP-in-SCION tunnel endpoint in this SCION AS will only arrive on the listed interfaces.
Port number for control traffic. The control address is constructed from the ip address and this control port. The control address is used to exchange IP routing information as part of SGRP. If not set, or zero, the control port will be dynamically allocated.
40201Port number for data traffic. The data address is constructed from the ip address and this control port. The data address is used for the IP-in-SCION encapsulated traffic stream. If not set, or zero, the data port will be dynamically allocated.
40200Optional description of the IP-in-SCION tunnel endpoint.
Whether the automatic configuration of allowed interfaces should be disabled. When disabled, the IP-in-SCION tunneling endpoint will be reached by remote endpoints on all SCION interfaces of the locally configured AS. When enabled (default), the local IP-in-SCION tunneling endpoint will only be reached by remote endpoints on the SCION interfaces that are configured on the local appliance.
Flag to disable uRPF. When enabled (default), the gateway performs strict URPF for all the received IP-in-SCION-tunneled traffic, checking that incoming IP packets have a source address that is within the announced prefixes by a remote gateway, and that the SCION packets are sent from a valid remote ISD-AS and are encrypted as configured in the associated domain.
Flag to activate SCION RSS. If activated, the gateway utilizes UDP source port entropy on the underlay such that EDGE and CORE routers can leverage RSS for SCION traffic. This can greatly improve throughput performance.
trueWhether this endpoint is enabled.
encryption object
Payload encryption configuration for the IP-in-SCION tunnel endpoint.
Whether the payload encryption module is enabled. With payload encryption enabled, the IP packets are encrypted and authenticated before being sent to a remote tunnel endpoint for domains that have the payload encryption enabled. Note that this flag only enables the payload encryption system. Each domain for which payload encryption should be used must still explicitly enable it.
The maximum number of Security Associations (SAs) that can be established with a single remote AS. If the limit is reached, new SAs from all endpoints in that AS will be rejected.
10001000Port number for the secure data traffic. The address is constructed from the endpoint IP address and this port. If not set, or zero, the secure data port will be dynamically allocated.
40203The maximum number of Security Associations (SAs) that can be established with remote tunnel endpoints. If the limit is reached, new SAs will be rejected.
100000100000IP address of the local IP-in-SCION endpoint.
192.168.1.100Port number for probing traffic. The probe address is constructed from the ip address and this probe port. The probe address is used by remote tunnel endpoints in their health probing. If not set, or zero, the probe port will be dynamically allocated.
40202path_filters object[]
List of path filters that can be referenced by name from a path policies. A path filter defines a set of paths by applying the filter to all available paths.
The ACL that is applied on the path. An ACL consists of a list of
ACL entries. Each ACL entry has the form action hop-predicate,
where the action can either be accept (+) or deny (-). The hop
predicate is optional and has the form isd-as#interface,
where isd is the ISD identifier, as is the AS identifier,
and interface is the interface identifier of a SCION path hop.
The hop predicate can be fully or partially qualified, i.e., all
entries of the hop predicate are optional or can include
wildcards (0). If no hop predicate is specified the action
matches every hop, i.e., a single '+' is the default accept action
and a single '-' is the default deny action. The ACL is applied
by sequentially applying all ACL entries to paths. If the ACL is
empty, it defaults to accepting all paths.
["+ 64-0"]Description, or comment, for the path filter.
Match only paths in the Swiss Isolation Domain (ID 64).The sequence of hop predicates that a path has to match to be accepted. Each hop predicate can optionally be extended with a modifier '' or '+'. The '' modifier means 0 or more occurrences. The '+' means one or more occurrences.
0* 64+ 0+Name of the path filter. This is value is used by the path policy to reference the path filter.
CH ISD onlyremotes object[]
List of remote ISD-ASes that are connected with the gateway. The remote ISD-ASes can be referenced in the remote matchers of the domains.
Description or Comment on the remote.
The ISD-AS of the remote.
1-ff00:0:310static_announcements object[]
List of static routes that are advertised. The routes are only advertised to the domains with matching announce filters.
Description, or comment, for the target.
next_hop_tracking object
container for next hop tracking
Whether or not this next-hop is tracked.
The routes are only distributed if the address responds to pings. This can be used to implement dynamically retractable routes without having to resort to a dynamic routing protocol.
192.168.0.1The IP prefixes that are statically configured and advertised via SGRP
Possible values: >= 1
["192.168.1.0/24","172.30.100.0/28"]The sequence ID defines the order of the static route entries. The sequence ID must be unique for each entry.
1traffic_matchers object[]
List of traffic matchers that can be referenced by name from a traffic policy. A matcher is used to classify traffic for tunneling. Each packet is classified based on configured traffic matchers and put in a traffic class. A traffic class is used in a traffic policy to map a path policy to a traffic class.
The condition for traffic to match this traffic matcher.
BOOL=trueDescription, or comment, for the traffic matcher
'all packets' matches all packets.Name that identifies the traffic matcher. This is value is used by the traffic policy to reference the traffic matcher.
all packetsshuttle_servers object
The necessary configuration data for Shuttle servers on the Anapaya appliance.
servers object[]
The necessary configuration data for Shuttle servers on the Anapaya appliance.
The IPv4/IPv6 address of the tunnel with a CIDR mask.
A list of IPv4/IPv6 addresses with a CIDR mask. The prefixes in the list are advertised to all connected clients. Subsequently, the clients route all traffic to these prefixes via the shuttle server. Must be in the same family as the tunnel address. If empty, it is by default equal to allowed_destinations. It must not be empty if shuttle traffic is NATed. Catch all are expressed as 0.0.0.0/0 (IPv4) and ::/0 (IPv6)
A list of IPv4/IPv6 addresses with a CIDR mask. The list indicates the networks that are reachable through the Shuttle server. All other destinations are disallowed. Must be in the same family as local tunnel address. The list is used to configure firewall forwarding rules on the appliance. Catch all are expressed as 0.0.0.0/0 (IPv4) and ::/0 (IPv6)
clients object[]
The list of Shuttle clients.
The IPv4/IPv6 address that will be assigned to the client tunnel interface upon successful connection. Without CIDR mask. Must be in the same family as local tunnel address.
A base64 encoded string that is used to authenticate the client.
The endpoint address on which the server is listening for connection requests from Shuttle clients.
In two alternative forms [ISD-AS,IP]:port, or IP:port,
where ISD-AS is an ISD-AS number, IP is an IPv4/IPv6 address
127.0.0.1:443The MTU (Maximum Transmission Unit) to be used on the shuttle interface. The user usually does not need to change this default value. The value is chosen to work in extreme circumstances.
1000The name of the network interface.
system object
The necessary configuration data for the system of the Anapaya appliance.
dns object
Anapaya appliance DNS configuration.
servers object[]
List of DNS servers.
IP address of a DNS server.
kernel object
Anapaya appliance Linux kernel configuration.
Size of hugepages the kernel should allocate at boot time.
2MNumber of hugepages the kernel should allocate at boot time. If not set, a sensible default is used based on the available memory.
Whether the IOMMU subsystem in the Linux kernel is enabled. IOMMU should be enabled on systems that support it for better performance. Note: After changing this option the appliance needs to be rebooted.
falsentp object
Anapaya appliance NTP configuration.
Maximum acceptable root distance, i.e. the maximum estimated time required for a packet to travel to the server we are connected to from the server with the reference clock. If the current server does not satisfy this limit, the appliance will switch to a different server.
5s1sservers object[]
List of NTP servers.
Address of a NTP server. This may be expressed as an IP address or a FQDN.
resources object
Anapaya appliance system resources configuration.
core_dump object
Configuration for core dumps.
The number of core dumps to keep. The appliance periodically deletes the least recent core dumps until this number is met.
3service_limits object[]
Configuration for per service resource limits.
The CPU limit in number of fractional CPU cores that can be used by the service. If not specified, a sensible default is chosen by the system. If set to 0, the service is not limited in terms of CPU usage.
1.5The memory limit in bytes that can be used by the service. The limit can
be specified using a string of the format
2.5GName of the service.
Possible values: [CA_FRONTEND, CONTROL, CRON, DAEMON, DATAPLANE, DATAPLANE_CONTROL, DISPATCHER, FRR, FRR_EXPORTER, GATEWAY, MOLE, NODE_EXPORTER, PROMTAIL, ROUTER, TELEMETRY, SHUTTLE, SHUTTLE_SERVER]
vpp object
Anapaya appliance VPP configuration.
buffers object
Buffers configuration.
The size of VPP internal buffers, in bytes.
9000The number of VPP internal buffers. If set to 0, a 3/4 of the available hugepages are used for buffers.
0connection object
Connection configuration.
health_check object
Health check configuration.
The interval in which a health check probe is sent to the VPP dataplane. It requires a unit suffix out of ['d', 'h', 'm', 's', 'ms', 'us', 'ns']. The encoding consists of a decimal number concatenated with a suffix; for example, '5us', '10m', '12h', and '1d'.
1s1sThe time in which VPP control services expect a reply from the VPP dataplane. It requires a unit suffix out of ['d', 'h', 'm', 's', 'ms', 'us', 'ns']. The encoding consists of a decimal number concatenated with a suffix; for example, '5us', '10m', '12h', and '1d'.
250ms250msThe number of health checks, from VPP control services to the VPP dataplane, that are allowed to time out before the connection is considered dead.
2020The number of connect attempts on start from VPP control services to the VPP dataplane.
1010The interval at which a connection is attempted on start from VPP control services to the VPP dataplane. It requires a unit suffix out of ['d', 'h', 'm', 's', 'ms', 'us', 'ns']. The encoding consists of a decimal number concatenated with a suffix; for example, '5us', '10m', '12h', and '1d'.
1s1scpu object
CPU configuration.
The list of CPU cores to be used by the workers. The cores are pinned to the workers in the order they are listed. The format for the list is A,B1-Bn,C1-Cn. This setting is mutually exclusive with workers and the list must not contain the main-core.
2-3,5The logical CPU core where main thread runs.
1The number of workers to be created for VPP. The workers are pinned to consecutive CPU cores. If set to 0, packet processing is performed by the main-core
The fixed-sleep between main loop polls in the VPP dataplane. It requires a unit suffix out of ['d', 'h', 'm', 's', 'ms', 'us', 'ns']. The encoding consists of a decimal number concatenated with a suffix; for example, '5us', '10m', '12h', and '1d'. Setting it to 0 disables the fixed-sleep.
0sstatseg object
Statseg configuration.
The size of the statseg segment. This can be specified in bytes with a suffix of kilo 'K', mega 'M', or giga 'G'. WARNING: Changing this value causes the dataplane to restart and therefore interrupts traffic.
32M100Mtun object
TUN configuration.
The MTU (Maximum Transmission Unit) to be used on this TUN.
15001500The list of prefixes to route from VPP to Linux.
["192.168.1.0/24"]Secrets
Sensitive information, like passwords or keys, is not stored directly in the configuration. Instead,
the configuration uses references to secrets. Fields that use secrets have names ending in _ref
and use the type string<secret-ref> in the schema. See secrets
management for more information.
Configuration interactions
You can interact with the appliance configuration in several ways:
- appliance-cli: A command-line interface to manage your appliance.
- Appliance API: A REST API to manage your appliance.
- Anapaya Console: A web-based orchestrator to manage your fleet of appliances.
The appliance-cli is the primary tool for managing the appliance. It comes pre-installed and connects to the appliance API over a UNIX socket. It wraps the API endpoints in a convenient CLI and also provides extra commands to inspect appliance information and health.
View current configuration
View the current configuration with:
appliance-cli get config
By default, the appliance-cli outputs a format that is similar to JSON or YAML, but is meant to be
easily consumed by humans. You can change the output format using the --format flag, or by setting
the APPLIANCE_CLI_FORMAT environment variable.
Add the following to your shell configuration file, to always use the yaml format:
export APPLIANCE_CLI_FORMAT=yaml
Modify current configuration
Modify the current configuration with the appliance-cli edit command, which has an interactive and non-interactive mode.
In non-interactive mode, you specify modifications as CLI shorthand, a JSON like syntax to easily create configuration objects. For example, to change the neighbor address of the first BGP peer, you can run:
appliance-cli edit config 'config.bgp.neighbors[0].neighbor_address: "10.10.0.1"'
The appliance-cli edit command fetches the current configuration, applies your changes, asks for
confirmation, and then updates the appliance. The tool leverages the the HTTP ETag header to ensure
the configuration is not modified by another process in the meantime.
Use the -i flag for interactive mode. This opens the configuration in your editor (set in the
VISUAL or EDITOR environment variables). After you save and close, the tool asks for
confirmation and applies the changes.
Prior to release v0.40, the appliance-cli edit command required
to manually set the --edit-format to edit the configuration in YAML, even when the --format was
set. Starting with release v0.40, the appliance-cli edit command
automatically sets the --edit-format based on the output format.
Push full configuration
Sometimes you need to push a complete configuration instead of modifying the current one. Use the appliance-cli put command.
Pass the full configuration via stdin:
appliance-cli put config < appliance-config.yaml
To prevent mistakes, the appliance checks the configured host name before accepting a new
configuration. If you want to change the host name, you have to explicitly allow the change by
passing the allow_hostname_change query parameter:
appliance-cli put config --query allow_hostname_change=true < appliance-config.yaml
Before you push the configuration, you can check the difference to the current configuration:
appliance-cli post config/diff -f body.diff --raw < appliance-config.yaml
You can also validate the configuration without applying it:
appliance-cli post config/validate < appliance-config.yaml
This runs the same validation logic as a push, but does not apply it. Head to configuration validation for more information on how violations are reported.
View configuration history
Configuration history can be retrieved starting with release v0.40. Configurations from previous releases are still available.
When troubleshooting after a change, it helps to see the difference between the current and previous configuration. You can retrieve the diff:
appliance-cli post configs/latest/diff -f body.diff --raw
To compare a specific configuration (e.g., version 42) with its predecessor, replace latest with
the version number:
appliance-cli post configs/42/diff -f body.diff --raw
To compare two specific configurations, even if they are not consecutive, specify both version numbers:
appliance-cli post configs/42/diff/21 -f body.diff --raw
Refer to the appliance API documentation for a comprehensive overview of all available endpoints and instructions on how to use them effectively.
Configuration validation
The Anapaya appliance runs a comprehensive set of validation checks before accepting and applying the configuration. This ensures the configuration is valid and prevents misconfigurations or unexpected behavior.
When you attempt to push an invalid configuration, the appliance rejects it with a HTTP 400 Bad Request error. The error message lists the invalid fields and the reasons for failure.
{
"status": 400,
"title": "The appliance configuration is invalid.",
"type": "https://anapaya.net/probs/validation-error",
"violations": [
{
"detail": "Changing the hostname is not allowed. If you are certain you want to change the hostname, use the 'allow_hostname_change' query parameter.",
"path": "/management/hostname",
"reason": "invalid value"
},
{
"detail": "no interface configured with address 10.0.0.1",
"path": "/management/api/listeners/10.0.0.1:443/address",
"reason": "invalid value"
}
]
}
The violations field contains a list of all the validation errors. Each error includes the path
in the config object, a generic reason, and a detailed explanation.
Configuration migration
The configuration schema evolves between Anapaya appliance releases. We attempt to preserve the existing configuration structure as much as possible. Backwards incompatible changes are documented in the release notes. The appliance automatically migrates the configuration to the new schema, even for most backwards incompatible changes.
If you are using Infrastructure as Code (IaC) tools, make sure to update your source of truth after you have updated the appliance to a new release.
In rare cases, automatic migration may not be possible. For example, if you use a highly customized advanced configuration. In these situations, the appliance will reject the migration and require manual intervention. The appliance will not apply any configurations until you manually provide a valid configuration. During this time, the appliance remains in its pre-upgrade state.