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": {
"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 bundle
for ISD 64 here
.
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.