Registering a server

In this tutorial, you’ll learn how to manually register a SSH server to allow Operous run tests against it.

Please note that the recommended way to register SSH servers currently is through the Registration script. This documented process is presented here for educational purposes. If you want to inspect what the script is doing and what it should be doing, this is where you should look.

Check if the server is supported

The first step is to check if your SSH server is supported. Right now there are two requirements:

  1. A running SSH server

  2. The server operating system must be in the support matrix

Table 1. Operating System Support Matrix
Operating System Version Supported

Ubuntu

18.04

20.04

Create the Operous Test Runner user

The second step is to create a user that the Operous Test Runner uses to authenticate in the server. To create this user run the following command:

adduser \
    --ingroup sudo \
    --disabled-password \
    --gecos 'Operous Test Runner' \
    operous-test-runner

Configure your SSH server

The third step is to configure the SSH server (SSHD) to allow the Test Runner to connect to your server and test it. To connect with the server, a signed key is used.

That means instead of inserting a public key at the authorized_keys to allow the access you need to download a public key from a CA (Certificate Authority) and configure the TrustedUserCAKeys option to read this CA public key. After this option is configured the SSHD service must be restarted to apply the configuration change.

This CA private key is heavily protected, even from Operous developers. When you start a test run with Operous, the Test Runner generates a new SSH key pair and requests a public key signature. This signature is short-lived with the required time to run the tests against your server.

To obtain your CA public key you’ll need to perform a request to the Operous GraphQL API. Only a curl client is required. This request has 3 parameters. Next, see how to determine each of the parameters.

How to get the registration token

Only users authenticated at the Operous Web App can be able to retrieve a registration token. Therefore the easiest way to obtain one is to copy it from the registration script shortcut presented at the Web App.

One of those shortcuts is available on the servers list page. Click the btn:[Register a server] button at the right corner of the page.

server
Figure 1: Servers list

The copied command should look like this:

curl -fsS https://app.operous.dev/i/installer.sh | sudo sh -s WBw98UVdPrN2

The parameter after the -s flag is a registration token. In the preceding example, the string WBw98UVdPrN2.

You may insert this value at a variable to use it later in the API request:

OPEROUS_TOKEN=WBw98UVdPrN2

How to get the SSH server port

If you already know which port the SSH services is running, just fill it to use later:

SSHPORT=22

If you don’t known which port the SSH service is running you can run:

sudo ss -ltnp | grep sshd

The ss shows the listening TCP sockets with their numeric port values and which process is using the socket. The grep filters the results with the string sshd to search for the sshd process.

You’ll probably get an output like this:

LISTEN    0         128                0.0.0.0:22               0.0.0.0:*        users:(("sshd",pid=66523,fd=3))

The number you’re looking for is in the fourth column after the colon, which is 22.

How to get the server public IP address

Operous API automatically attempts to connect at the origin IP address. If you’re not sure what IP address is this, check it with one service that returns your server public IP:

curl https://ipinfo.io/ip

The registration script sends IP addresses from the network interfaces, while the Test Runner attempts to connect at one of those addresses.

If you’re connected at your server with SSH simply inform the IP address you used to connect at the server:

ADDRESS=127.0.0.1

Obtain your public CA key

With the registration token, SSH port, and public IP address request to the Operous API to discover your server public CA key:

QUERY='mutation RegisterServer($token: String!, $ssh: Int!, $ips: String!) { registerServer(input: { token: $token, sshPort: $ssh, ssvIps: $ips }) { ca } }'

curl -s \
  -X POST \
  -H "Content-Type: application/json" \
  --data "{
    \"query\": \"$QUERY\",
    \"variables\": {
      \"token\": \"$OPEROUS_TOKEN\",
      \"ssh\": $SSHPORT,
      \"ips\": \"$ADDRESS\"
    }
  }" \
  https://app.operous.dev/graphql

You should receive a response with a JSON that contains a SSH ED25519 public key:

{"data":{"registerServer":{"ca":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEFUhjRNZfRqnbVUgPxi2bdhhPUQwL+K/bLrrpQXvSc6 Operous Test Runner"}}}

The value at the "ca" key is your public CA key.

Create a file close to the SSHD configuration files called /etc/ssh/operous-ca.pem with its value. Using the preceding example value, the file should look like this:

/etc/ssh/operous-ca.pem
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEFUhjRNZfRqnbVUgPxi2bdhhPUQwL+K/bLrrpQXvSc6 Operous Test Runner

Edit the SSH server configuration TrustedUserCAKeys

Now the instructions may differ with the operating system you’re using. Follow the adequate instructions below.

Ubuntu 18.04

Edit the /etc/ssh/sshd_config file with your favorite editor and include the following line:

/etc/ssh/sshd_config
TrustedUserCAKeys /etc/ssh/operous-ca.pem

Ubuntu 20.04

Using your favorite text editor create a file at

/etc/ssh/sshd_config.d/operous.conf with the following content:

/etc/ssh/sshd_config.d/operous.conf
TrustedUserCAKeys /etc/ssh/operous-ca.pem

Restart the SSH server

To apply the preceding configuration changes, restart the SSH server:

sudo systemctl restart sshd.service
Please note that the service to restart is sshd, with a "d" at the end, not the ssh service.

Validate the server connection

Now you need to validate if the Test Runner was able to connect to the server.

You can confirm if the registration process was successful making the following request to the GraphQL API:

QUERY='mutation ConfirmRegistration($token: String!) { confirmRegistration(input: { token: $token }) }'

curl -s \
  -X POST \
  -H "Content-Type: application/json" \
  --data "{
    \"query\": \"$QUERY\",
    \"variables\": {
      \"token\": \"$OPEROUS_TOKEN\"
    }
  }" \
  https://app.operous.dev/graphql

If everything worked fine you’ll should receive a response with a JSON that contains a generated name for the registered server:

{"data":{"confirmRegistration":"stiff-authority-9065"}}

And you’ll see your server available at the Operous Web App.

If it didn’t worked you’ll receive a null instead of the server name:

{"data":{"confirmRegistration":null}}

Since the Test Runner tries to connect as soon as the API receives the public IP address and SSH port, you may need to retry the step Obtain your public CA key now that your SSHD is configured with the public CA key. Execute the same request to the API, then after a few seconds try to confirm the registration again with the request from this step.

If you’re still unable to confirm the registration, make sure that you’re sending the correct public IP address and SSH port. If you’ve connected to the server through a VPN or bastion host the public IP address informed may be wrong.

Operous currently does not support testing servers behind a bastion host.

Feedback

If you followed this tutorial but was unable to achieve the desired result or you think you’ve detected a divergence between the instructions here and what is executed at the Registration script please make contact!