Anapaya Appliance¶

This section will guide you through the steps to get the Anapaya Appliance (henceforth only called appliance) up and running - from the initial power-on all the way to establishing SCION connectivity.

Note

This guide assumes you are using the Anapaya S-Type physical appliance that already comes with a pre-installed appliance base image. If you need instructions for how to install the appliance base image on your target platform, please refer to Base Image Installation.

Note

If you require support with provisioning the appliance, do not hesitate to contact us at cse@anapaya.net.

Connecting to the Appliance¶

Most interactions with the appliance are done via its management API or the appliance-cli. However, on a fresh installation, these components first need to be configured and activated from within the appliance host.

Connect to the appliance using the credentials that have been provided to you alongside the installation instructions. The default credentials are anapaya for the user and anapaya for the password.

By default the appliance attempts to lease an IP via DHCP on each of its interfaces. If you have a DHCP server in your network, you can connect to the appliance using SSH.

ssh anapaya@<ip address>

Note

The default password is only valid for the first login. You will be prompted to change the password on first login.

If SSH is not an option, you can also use the serial console to connect to the appliance. Please check your platform documentation for instructions on how to connect to the serial console (or GUI). You can use the same default credentials as above to log in.

Configuring the Management Interface¶

If you connected to the appliance via the serial console or want to configure a different interface for the management connection you can use the standard Linux ip tool set. For example, to configure the IP address 192.168.1.1 on interface eno1, you can run the following command:

sudo ip address add 192.168.1.1/24 dev eno1
sudo ip link set eno1 up

Changing User Authentication¶

If you want to change the default password of the anapaya user you can simply run

passwd

enter the current password and then enter a new password.

Configure the appliance-cli¶

The appliance-cli is a command line tool that allows you to interact with the appliance management API. It is installed on the appliance by default. However, it needs to be configured before it can be used.

To configure the appliance-cli, you need to run the following command:

appliance-cli context configure localhost --insecure

Then use https://localhost:443 as base URI and configure authentication with the same default credentials as above.

Updating a SCION release¶

Your appliance comes with a release of the anapaya-scion and anapaya-system packages installed. However, we recommend upgrading to the latest release containing all the latest features, bug fixes, and improvements.

To update the anapaya-scion or anapaya-system release, follow the instructions in Appliance Update Guide.

Provisioning an Initial Configuration¶

Now that the initial installation is complete, you can use the appliance management API to provision an initial configuration.

The entire appliance configuration can be stored in a single JSON file - we will refer to this file as appliance.json in the following. It contains all the configuration - the networking interfaces on the appliance host, the SCION and IP-in-SCION tunneling configuration, authentication, and other system configuration. In this guide, we assume that you already have an initial appliance configuration, e.g., from your service provider or from the Anapaya Customer Success Engineering team, that contains the main network interface and SCION configurations.

Tip

For more information on the contents of the appliance configuration, please refer to Appliance Configuration section and the Management API specification.

You can interact with the configuration by using the appliance-cli:

# Retrieve the current configuration
appliance-cli get config > appliance.json

# Update the configuration
appliance-cli put config <appliance.json

# Directly edit the configuration in your favorite text editor
EDITOR=vim appliance-cli edit config -i

Configuring Authentication of the Management API¶

Now, that you have provisioned the initial configuration, we will look at how to configure authentication for the management API.

To do that, use the appliance-cli to edit the configuration and add the following configuration (for more information refer to Appliance Management Configuration):

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

This configures the management API to be available on 127.0.0.1:443 and enables HTTP basic auth for user admin and password password. The password_hashed value can be derived using the interactive appliance-cli command on an appliance or by using the Apache htpasswd command:

appliance-cli crypto kdf hash

htpasswd -nB -C 12 admin

If you need to add more users, you can simply extend the users list in the basic_auth section.

Exit your editor and the configuration will automatically be validated and applied. The new configuration will be printed to the console.

Note

If you don’t feel comfortable editing the configuration in place, you can also edit it in your favorite text editor and then apply it using the appliance-cli:

appliance-cli get config > appliance.json
# edit appliance.json in your favorite text editor
appliance-cli put config <appliance.json

Tip

You can also configure the management API to listen on an IP address other than 127.0.0.1 to make it accessible from outside the appliance host.

Note

The initial anapaya user is now no longer usable because the configuration only contains the admin user. Make sure to update the authentication configuration of the appliance-cli.

Provisioning the TRC and AS Certificate¶

As the final step before being able to establish SCION connectivity, you need to provision at least the Trust Root Configuration (TRC) of your SCION ISD as well as a SCION AS certificate issued by a certificate authority (CA) of your SCION ISD.

Tip

This guide only covers the basics of provisioning the TRC and AS certificate. For more in-depth information please refer to Certificate/TRC Provisioning.

TRC Provisioning¶

Assume that you have a TRC called ISD1-B1-S1.trc which would be the TRC of SCION ISD 1. To install this TRC, you need to run the following command:

appliance-cli post cppki/trcs <ISD1-B1-S1.trc

The given TRC is first validated before it is added to the trust store. Only valid TRCs are added to the trust store.

To verify that the TRC has been added, you can run the following command:

appliance-cli get cppki/trcs

Tip

When your appliance does not have any TRCs installed, you can use the Add TRC bundle endpoint to install the full chain of TRCs at once. Download the TRC bundles from Isolation Domains overview.

appliance-cli post cppki/trcs/bundle <ISD1.bundle

AS Certificate Provisioning¶

To create an initial AS certificate, you need to instruct the appliance to create a Certificate Signing Request (CSR). This CSR then needs to be signed by a local CA AS. The result is a certificate chain consisting of the issued SCION CPPKI AS certificate and the issuing SCION CPPKI CA certificate. This certificate chain then needs to be installed on the appliance.

To generate a CSR, you need to first create a file cp-as.json with the following content:

{
   "subject": {
      "isd_as": "1-ff00:0:110",
      "common_name": "Anapaya Switzerland AS",
      "country": "CH",
      "locality": "Zurich",
      "organization": "Anapaya Systems AG",
      "organizational_unit": "Anapaya Systems Engineering Department",
      "postal_code": "8005",
      "province": "Zurich",
      "serial_number": "CHE 123.456.789",
      "street_address": "Hardturmstrasse 253, 8005 Zurich"
   }
}

Note

You should adapt the values to your needs.

Note

Generally, only the isd_as value is required and everything else is optional. We do recommend that you at least specify a common_name. Some CAs might have different requirements on these fields. Please refer to the CA of your ISD for more information.

To generate a fresh CSR and store it in a file cp-as.csr you can run

appliance-cli post cppki/csrs <cp-as.json --raw > cp-as.csr

The resulting CSR is a PEM-encoded file that needs to be signed by a CA. This is an out-of-band mechanism and is defined by the CA that is responsible for issuing your initial AS certificate.

After you have received back the SCION CPPKI AS certificate as part of a full SCION CPPKI certificate chain, you can install it on the appliance:

appliance-cli post cppki/certificates <cp-as.pem

This first verifies the certificate chain against the active TRC of the local ISD before it is added. Only verifiable certificate chains are added.

To verify that the certificate has been added, you can run:

appliance-cli get cppki/certificates

From this point on, the AS certificate gets automatically renewed by the appliance and you do not have to manually provision it anymore.

Note

This only works assuming that the appliance has SCION connectivity to the CA. If you are not able to establish SCION connectivity within the validity period of the provisioned AS certificate, you will have to repeat the process above to request and provision a new AS certificate.

Verifying SCION Connectivity¶

You are now at the stage where you can verify that SCION connectivity is established. Showpaths is the primary tool available to do this.

Showpaths will show all paths that are available to a given remote AS. Furthermore, it also automatically probes all paths to verify their health. Having showpaths report a set of available paths that are healthy, indicates that the SCION control plane and data plane are working properly.

The basic command to show all the available paths to a remote AS is

scion showpaths <remote_isd_as>

where <remote_isd_as> is the ISD-AS of the remote AS you want to probe. In a first step, it makes sense to probe a direct neighbor, e.g., your upstream AS or a peering AS. You should already know the ISD-AS identifier from the configuration file, where the links to neighboring ASes are configured.

A further sensible choice is to probe all paths to the issuing AS for your AS certificates. You can get its ISD-AS identifier by either inspecting the appliance configuration (cppki.issuers section) or the AS certificate chain that you installed on the appliance in a previous step.

Finally, if you are connected to the public SCION Internet, you can use one of Anapaya’s SCION ASes 64-2:0:1a for probing.

scion showpaths 64-2:0:1a

Next Steps¶

You now have a fully configured appliance that is connected to a SCION network. A likely next step is to configure IP-in-SCION tunneling to enable legacy IP applications to use the SCION network for communication. You might also want to upgrade the appliance operating system to the latest version. Refer to Appliance Software Updates for documentation on how to do this.