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