Getting started with the 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 Installing the Appliance Base Image.

Note

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

Connecting to the Appliance¶

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

To connect to the appliance, you can use SSH. To do that, you first need to know the IP address of the appliance. The appliance attempts to lease an IP via DHCP on each of its interfaces.

ssh anapaya@<ip address>

Then, you can authenticate with the default password that has been given to you alongside the installation instructions.

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.

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. Ask your Anapaya Customer Success Engineer for the most suitable release for your platform.

Note

The ${mgmt_address} in the curl commands below needs to be replaced with the actual management address of the appliance. This can either be an IP address or a DNS name.

Note

The -k option on the curl commands in the following steps is required to skip verification of the TLS certificate. The appliance management API uses a self-signed certificate. This will be configurable in the future.

Note

The -u <user>:<password> option on the curl commands in the following steps is required to pass the user and password to the API. The anapaya user is a default user that is configured in the base image. The password should have been provided to you. If that is not the case, ask your Anapaya Customer Success Engineer for it.

To update the anapaya-scion or anapaya-system release, follow the instructions in Updating an Appliance.

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 enact the configuration by using the /config endpoint of the management API:

curl -X PUT -k -u <user>:<password> https://${mgmt_address}/api/v1/config -d @appliance.json

Similarly, you can always retrieve the active configuration and store it to a file:

curl -k -u <user>:<password> https://${mgmt_address}/api/v1/config > appliance.json

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, open the appliance.json file in your favorite text editor and add the following configuration (for more information refer to Appliance Management Configuration):

{
   "management": {
      "api": {
         "listeners": [
            {
               "description": "Management API",
               "address": "192.168.1.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 192.168.1.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 admin

Note

Adjust the address value to the address of the appliance host in your setup. Here we assume that the appliance host is reachable on 192.168.1.1.

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

Save the changes to appliance.json and apply the configuration by using the /config endpoint of the management API:

curl -X PUT -k -u <user>:<password> https://${mgmt_address}/api/v1/config -d @appliance.json

You should now be able to access the management API from outside the appliance and only if you authenticated with the correct username and password. You can verify this by running the following command from outside the appliance host:

curl -k https://192.168.1.1/api/v1/config -u admin:<your-password>

Note

The initial anapaya user is now no longer usable because the configuration only contains the admin user.

Tip

The appliance comes with a web-ui that can be used to view and update the appliance configuration, inspect other system information, and use a range of tools to do network troubleshooting. The web-ui can be accessed by navigating your browser to https://192.168.1.1/.

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:

curl -k https://192.68.1.1/api/v1/cppki/trcs -X POST --data-binary "@ISD1-B1-S1.trc" -u admin:<your-password>

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:

curl -k https://192.68.1.1/api/v1/cppki/trcs -u admin:<your-password>

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.

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

curl -k https://192.68.1.1/api/v1/cppki/csrs -X POST --data '@cp-as.json' -u admin:<your-password> > 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:

curl -k https://192.68.1.1/api/v1/cppki/certificates -X POST --data-binary "@cp-as.pem" -u admin:<your-password>

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:

curl -k https://192.68.1.1/api/v1/cppki/certificates -u admin:<your-password>

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.

Tip

The scion tool is installed on your appliance. Alternatively, you can also access it from the web-ui that is available on your appliance by navigating your browser to https://192.168.1.1/ or use the management API directly (see here).

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 Software Updates for documentation on how to do this.