Skip to main content

Setup

This section guides you through the steps to get the Anapaya appliance (henceforth only called appliance) up and running - from the initial power-on to a minimal configuration to establish SCION connectivity. For advanced configurations, follow the Next steps

Base image required

This guide requires that the appliance base image pre-installed on the appliance in hand. To install the appliance base image on your target platform, please refer to installation.

Help

We are always at your disposal at support@anapaya.net.

Connect 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 Anapaya 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 Anapaya 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 Anapaya 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 Anapaya 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.

tip

To use the latest features, upgrade the appliance to the latest appliance and system packages by following the instructions in Software update. Note that this likely requires network connectivity and management to be configured properly first.

Configure the appliance​

Get familiar with configuration model​

The entire appliance configuration can be expressed in a single file. Head to the configuration documentation to learn more about the configuration, its schema, and how to push it to the appliance. To understand the following steps, you are required to have a basic understanding of the Anapaya appliance configuration model.

note

Interfaces might be assigned IP addresses via DHCP or cloud-init. As soon as interfaces are managed through the appliance configuration, DHCP is disabled and cloud-init-generated network configuration is removed.

Configure user authentication​

To log into the appliance later, configure the management SSH keys. Add your public SSH key to the management section by modifying the current configuration.

appliance-cli edit config 'config.management.ssh.users[]:{
   "username": "anapaya",
   "ssh_keys": [
      {
         "key": "AAAAB3NzaC1yc2EAAAADAQABAAABgQC3...",
         "description": "anapaya-key1"
      }
   ]
}'

Change the default password of the anapaya user by running

passwd

Enter the current password and then enter a new password.

Configure interfaces​

To establish network connectivity, configure the appliance interfaces by following the Network interfaces configuration.

Configure license​

Starting with release v0.38, the Anapaya appliance supports Anapaya's license management. Licenses can now be installed, but enforcement is not yet active. See Software license for more details.

Configure SCION AS​

Configure the SCION ASes on your appliance by following the SCION configuration. In case you do not have an AS number yet, follow the AS registration process to obtain one.

Refer to the deployment examples for some EDGE and CORE configuration examples to get you started.

Provision cryptographic material​

For 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.

Provision TRCs​

tip

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

Copy the install command for the TRC bundles from Isolation Domains overview. You can use the (copy button) in the popup to add it to your clipboard.

Install the full chain of TRCs at once using the command.

cat <<EOF | appliance-cli post cppki/trcs/bundle
-----BEGIN TRC-----
MIIf4wYJKoZIhvcNAQcCo...

Provision AS certificate​

For SCION connectivity, you need to provision 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. For more in-depth information please refer to Provision SCION AS certificate and TRC.

To create an initial AS certificate, first create a Certificate Signing Request (CSR). The CSR then needs to be signed by a CA AS in the ISD. The result is a certificate chain consisting of the issued SCION CP-PKI AS certificate and the issuing SCION CP-PKI 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"
    }
}

Adapt the values to your needs.

Mandatory fields

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.

Generate a fresh CSR and store it in a file cp-as.csr:

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 CP-PKI AS certificate as part of a full SCION CP-PKI 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 is automatically renewed by the appliance and you do not have to manually provision it anymore.

warning

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.

Verify configuration​

Verify that the appliance is configured correctly and has SCION connectivity.

Verify SCION configuration​

To verify that SCION is configured, run the following command:

appliance-cli info scion

A successfully configured SCION AS results in an output like below:

SCION ASes

- 1-ff00:0:110 (1-ff00:0:110)
  Crypto:
    - TRC for local ISD ✅
      ISD: 1 Base: 1 Serial: 1
      Daemon ✅
    - AS certificate ✅

Verify SCION connectivity​

To verify the establishment of SCION connectivity, use scion showpaths, which is the primary tool for this purpose.

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 them from the AS certificate chain, which you installed on the appliance in a previous step, using the following command:

appliance-cli get cppki/certificates | jq -r .certificate_chains[0].issuer
tip

If your AS is part of the public SCION Internet, you must be able to probe one of Anapaya's SCION ASes, e.g., 64-2:0:1a.

scion showpaths 64-2:0:1a

Next steps​

The appliance is now connected to the SCION network.

  • To enable the management API, configure Management.
  • To connect to the Anapaya Console, refer to Console.
  • To enable IP applications to use the SCION network, configure IP-in-SCION tunneling.