Configure SlapOS Slave Node

Configure SlapOS Slave Node

Configuring A SlapOS Slave Node

SlapOS - Configure SlapOS Node

This tutorial will guide you through the process of configuring a SlapOS slave node to provide software services. The type of services are determined by which software releases are available on the SlapOS Master. While supplying a service is straightforward and the same for services, the configuration required during instantiation can be different and will therefore be described in more detail.

The tutorial applies to configuration of both COMP-0 and COMP-1,2,3.... In case of required follow-up steps, like on installation of the Re6st Registry on COMP-0, these will also be pointed out and linked to.

This tutorial requires you to have a computer with a SlapOS (slave) node installed and ready to use as well as an account on a SlapOS Master. This can be Vifib (how to register on vifib) or a any other master (tutorial to create a SlapOS Master).

In case the SlapOS node was installed without the recommended single line installer, the node is still unformatted without computer partitions. Follow formatting a SlapOS node before continuing.

Should you run into problems during configuration make sure to check how to debug a SlapOS node for the most common commands and debugging info.

Table of Content

  • Supplying a Service
  • Instantiating A Service
  • Configure Apache Frontend Instance
  • Configure Re6st Registry
  • Configure Re6st Access Token
  • Configure eNodeB
  • Configure ERP5
  • XXX split into separate documents? XXX...

Supplying A Service

The SlapOS architecture describes how SlapOS nodes are used to provide software instances to users in a network.

To do this, the SlapOS Master is used to install the designated software on a manually or autonomously selected Slave node. In this tutorial, a node will be manually selected and configured to provide the services - a Frontend (Apache) and a Re6st Registry. It could as well be any other service such as ENodeB, MariaDB, KVMs or custom services (how to create a software release) that should be available for users on a network.

The node in this tutorial will configured as COMP-0 in a SlapOS network. Installing other software on other network nodes is done in the same way as described here.

Choose Server in SlapOS Dashboard

SlapOS Interface - Server list

Log in to your SlapOS Master Dashboard and click on Servers in your side menu to open the list of servers in your network. Pick any of the available Slave nodes and click on the server (NOT the green buttons for monitoring the computer or it's partitions). In our example we currently only have a single node registered without an partitions, so select this node to open it's configuration.

Server Configuration

SlapOS Interface - Unconfigured server

You can see in the bottom table Supplied Software that this node does currently not provide any software. It is also not associated with any network (see grouping servers in a network) and the allocation scope defines this server as "in use". It is open, but only on personal level, meaning for the owner of the computer (see setting Slave node access permissions to learn how to enable certain groups of users to request instances of the software provided on this node).

To continue, click the Supply button in the subheader to open the list of available software (releases) that can be installed on this node. Note, the following process of installing and supplying a software is the the same for all softwares provided.

Supplying a Service

SlapOS Interface - List of available software release to install on a Slave node

The list of software releases depends on the type of releases available on the SlapOS master. In the example a number of different softwares are available (see the tutorial to create a software release how you can provide different types of software in your network).

To continue, please select the Frontend entry.

Selecting Software Release Version

SlapOS Interface - List of available software release versions to install on a Slave node

Select the latest version.

Confirm Software Installation

SlapOS Interface - Confirm Software Installation

The subsequent dialog summarizes the software release to be installed as well as the computer it will be installed on. To continue, click Proceed in the header. Note, as mentioned before, this process is the same for all software installations.

Installing Software Release

SlapOS Interface - Software Release Installation Status

After clicking Proceed you will be forwarded to the installation status page.

Installation will take some time depending on the software you are installing, so either refresh the current page or check installation status directly by either going to your Servers list and selecting the machine you chose during installation or clicking directly on Computer (FIRST-NODE in the screenshot).

Server Configuration Update

SlapOS Interface - Server Configuration

You can see the installed service is now available in the bottom list. The indicator will stay red until the software has finished compiling and installing. Once the installation status bar changes to green on a refresh of the page, the installation has finished. The node can then provide Frontend (Apache) or whichever software you supplied instead to authorized users.

You can follow the compilation by looking at the slapos-node-software.log using:

# tail opt/slapos/log/slapos-node-software.log -f
in your terminal (other log options, see how to debug a SlapOS node).

To see whether the service is actually available and can be used, the next part of the tutorial will cover requesting an instance of the installed service. Note, that aside from software-specific instanatiation parameters, this is also a standardized process for all softwares.

Instantiating a Service

Once a service is installed on a computer, it is possible to create and provide instances of this service to users.

List of Instantiated Services

Vifib Interface - Services List

Head to the list of services by clicking on the Services button on the side menu. The list will show all services currently instantiated (not the software currently installed!). To create an instance of an installed software, click the Add button in the subheader.

Create New Service Instance

SlapOS Interface - Services List

The list of available services is the same as the list of installable software releases used earlier when installing the service. Select Frontend (Apache) as this is the service we want to provide.

Select Service Version

SlapOS Interface - Service Instantiatin Version List

As during installation, please choose the latest version.

Note, that this is an easy case, as there is only a single version installed on one node. More complex networks will likely have multiple versions of a software installed on different nodes.

Also note that, as mentioned before, software available on SlapOS can be configured on every instantiation. Because the configuration parameters differ from software to software they will be described in more detail in the following section.

For extending existing software or creating custom software to be provided over SlapOS have a look at how to create a software release and how to extend SlapOS with custom services.

Configuring Frontend (Apache)

The process of installing (supplying) a software and providing it as a service (instantiation) are the same for all softwares. However each instance can be configured differently.

This section will cover the specific configuration parameters used for Frontend (Apache) during instantiation and the necessary steps to get the Frontend up and running. Note, that if you are configuring COMP-0 it is a required step.

Frontends are available in SlapOS because they:

  • prevent end users from having to use IPv6
  • provide secure https connections with valid certificate
  • route access through a central, auditable entry point
  • give meaningful urls internally instead of only displaying IPv6 addresses

Frontend Configuration

SlapOS Interface - Frontend Instance Configuration

Once you are on the Frontend configuration menu, you can see it contains a form of software-specific parameters as well as a generic XML configuration field (hidden by default - click the button to display). NOTE: at point of writing, please ONLY USE THE XML PARAMETERS to pass instance configuration in case you want to request a FRONTEND.

Note that running a Frontend on SlapOS will require a valid SSL wildcard certificate, which cannot be requested through the interface. In case you don't have a certificate, follow the steps in how to setup a wildcard SSL certificate before continuing.

Once you have a certificate, click the button to display the XML configuration. Give the Frontend an optional name and make sure you select the computer you created at the end of the form. Otherwise the SlapOS Master will look by itself on which node the instance should be created.

Then add the following XML configuration parameters:

<?xml version="1.0" encoding="utf-8"?>
<instance>
    <parameter id="public-ipv4">[IP_OF_YOUR_SERVER]</parameter>
    <parameter id="ip-read-limit">40</parameter>
    <parameter id="re6st-verification-url"<https://www.erp5.com/getId</parameter>
    <parameter id="apache-key">[AAA]</parameter>
    <parameter id="apache-certificate">[BBB]</parameter>
    <parameter id="apache-ca-certificate">[CCC]</parameter>
    <parameter id="domain">[slaptest.erp5.net]</parameter>
    <parameter id="-frontend-quantity">1</parameter>
    <parameter id="-frontend-type">custom-personal</parameter>
    <parameter id="-sla-1-computer_guid">[COMP-XXXX]</parameter>
</instance>

with:

  • [IP_OF_YOUR_SERVER]: IPv4 address of your server (debian@xxx.this.one.xxx)
  • [AAA]: ssl key (privkey.pem)
  • [BBB]: ssl certificate (cert.pem)
  • [CCC]: ssl ca certificate (chain.pem)
  • [COMP-XXXX]: computer where the partition for this Frontend will be created.

Proceed to start instantitation.

Frontend Instantiation and Port Forwarding

SlapOS Frontend - Socat Port Forwarding

Refresh the list of current services to show the new service and status.

You can follow the compilation progress by looking at the slapos-node-software.log using:

# tail opt/slapos/log/slapos-node-software.log -f

The Frontend will be installed inside a computer partition (see SlapOS system requirements) and will listen on ports 8080 and 4443. As user permissions in Linux systems prevent accessing ports larger than 1024, incoming traffic on public ports 80 and 443 has to be forwarded to the correct ports the Frontend is listening on.

This can be done using a Firewall with NAT traversal or using Socat. We will use Socat, a relay for bidirectional data transfer between two independent data channels. Data channels can be files, pipes, devices (terminal or modem, etc.), or sockets (Unix, IP4, IP6 - raw, UDP, TCP), etc. For more information, please refer to the Free Software Directory).

To install socat, head to your terminal and:

sudo su
root@svenslapostest2:/# sudo apt-get install socat

Find the IPv6 adresses used by the Frontend which is in its configuration folder:

root@svenslapostest2:/# cat /srv/slapgrid/slappart8/etc/apache_frontend.conf
Listen 10.0.176.4:8080
Listen 10.0.176.4:4443
Listen [2401:5180:0:42::xxxx]:8080
Listen [2401:5180:0:42::xxxx]:4443
ServerAdmin admin@example.com
DefaultType text/plain

Use the IPv6 adresses for ports 8080 and 4443.

Listen [2401:5180:0:42::d62a]:8080
Listen [2401:5180:0:42::d62a]:4443

Then call socat:

root@svenslapostest2:/# socat  TCP4-LISTEN:80,fork TCP6:[2401:5180:0:42::xxxx]:8080 &
socat TCP4-LISTEN:443,fork TCP6:[2401:5180:0:42::xxxx]:4443 &

To see whether your bindings are active, you can

root@svenslapostest2:/# ps aux | grep socat
debian    4299  0.0  0.0  12728  2208 pts/0    S+   11:04   0:00 grep socat
root     24449  0.0  0.0  19644  2696 ?        S    Mar20   0:00 socat TCP4-LISTEN:80,fork TCP6:[2401:5180:0:42::xxxx]:8080
root     24674  0.0  0.0  19644  2604 ?        S    Mar20   0:00 socat TCP4-LISTEN:443,fork TCP6:[2401:5180:0:42::xxxx]:4443

You can also verify that the port forwarding is working by accessing your frontend URL (in our case) foobar.slaptest.erp5.net in a browser. If successful, the listener should forward to the IPv6 address the Apache frontend is listening on.

Monitor Url Connection Parameter

SlapOS Dashboard - Service Frontend Apache Configuration Connection Parameters

After setting up port forwarding on your Dashboard, click on the Services menu and select the Frontend entry to re-open the configuration page (same as before click the service name, don't click the red/green computer status icon but the service name directly).

If port forwarding is set correctly, your instance should now have a green status.

Note, that after instantiation, the configuration page will contain additional sections at the bottom. Once the status turns green and instantiation finished successfully, there should be a number of connection parameters available when you scroll down beyond the configuration form. Open the monitor url to see if the frontend is accessible.

Verify Frontend Is Accessible

SlapOS Frontend Service Accessability

If the Frontend is accessible you should get an XML output similar to the one being pictured. As mentioned you can try any wildcard-url based on the one declared before (slaptest.erp5.net) for which the ssl certificate was issued such as foobar.slaptest.erp5.net.

Configuring Re6st Registry

The process of installing (supplying) a software and providing it as a service (instantiation) are the same for all softwares. However each instance can be configured differently.

This section will cover the specific configuration parameters used for Re6st Registry instantiation and the steps required to get Re6st to work.

Re6st is used in SlapOS to create a mesh network and route traffic through available nodes. To setup Re6st while configuring COMP-0, it is first required to instantiate a Re6st Registry - a register which manages Re6st nodes in a network and issues tokens for new nodes to join the network. The Registry is handled in this chapter.

A second step for COMP-0 and the only step for COMP-1,2,3... is to request a Re6st token which is covered in the next chapter.

Registry Configuration

SlapOS Interface - Re6st Registry Instance Configuration

Once on the configuration screen of the Registry, select Software Type Default (denotes the Registry why not Registry?) which will load a form with software-specific parameters. Then set:

IPv6 prefix: fc01::/7
Default length of allocated prefix: 16

Don't forget to select your computer at the end of the form to prevent the SlapOS Master allocating the Registry on a computer of its choice.

Click Proceed to start instantitation. This will forward you to the list of current services.

Registry Instantiation and Port Forwarding

SlapOS Interface - Re6st Service Instantiation

Refresh the page to show your instance and installation status.

You can follow the compilation by looking at the slapos-node-software.log using:

# tail opt/slapos/log/slapos-node-software.log -f

Since the Registry is listening on port 19201XXX or 9201? XXX (see system requirements) and user permissions in Linux systems prevent accessing ports above 1024, traffic must be forwarded using NAT traversal or Socat.

This can be done using a Firewall with NAT traversal or using Socat. We will use Socat, a relay for bidirectional data transfer between two independent data channels. Data channels can be files, pipes, devices (terminal or modem, etc.), or sockets (Unix, IP4, IP6 - raw, UDP, TCP), etc. For more information, please refer to the Free Software Directory).

To install socat in case needed, head to your terminal and:

sudo su
root@svenslapostest2:/# sudo apt-get install socat

Still in your terminal, start by finding the IP adress to bind to:

root@localhost:~# netstat -natp | grep 9201
tcp         0       0 10.0.27.44:9201       0.0.0.0:*          LISTEN       26027/python2.7
tcp         0       0 10.0.27.44:40706      10.0.27.44:9201    TIME_WAIT    -
tcp         0       0 10.0.27.44:40699      10.0.27.44:9201    TIME_WAIT    -
tcp         0       0 10.0.27.44.9201       10.0.27.44.:40655  TIME_WAIT    -
tcp         0       0 :::9201               :::*               LISTEN       26027/python2.7

Continue with:XXX Explain what we see means XXX

root@localhost:~# ifconifg eth0 | grep inet\
            inet addr:167.114.246.26  Bcast:167.114.246.26  Mask:255.255.255.255

Then call Socat:

root@localhost:~# socat TCP4-LISTEN:9201,fork,bind=167.114.246.26 TCP4:10.0.27.44:9201 & [3] 13443

Note, that your Registry master-url in the example is 167.114.246.26:9201. You will need to provide this url whenever you want to connect a new node to the network.

To verify whether port forwarding works, you can:

root@svenslapostest2:/# ps aux | grep socat
    

XXX add output XXX

Before finishing make sure that any temporary IPv6 adress space added during installation of the SlapOS node itself (when installing the COMP-0 node) is removed. On your terminal, run:

sudo su
ip -6 addr del fc01::1/32 dev lo

IPv6 will be reset when the first (gateway) node is being created. XXX EXPLAIN XXX.

Verify Re6st Is Accessible

SlapOS Re6st Registry Service Accessability

Once port forwarding is setup, try accessing the registry over the url 167.114.246.26:9201.

Configuring Re6st Access Token

The process of installing (supplying) a software and providing it as a service (instantiation) are the same for all softwares.

However each instance can be configured differently. This section will cover the specific configuration parameters used for a Re6st Access Token, which is required during installation of Re6st on a node to associate it with a Registry and SlapOS Master.

Token Configuration

SlapOS Interface - Re6st Token Configuration

Once you reach the configuration screen, set Software Type to Re6st Token. The token is actually a slave instance of the Registry (and in case of COMP-0 a first gateway node) with connection parameters including the actual token being created by the Registry XXX REALLY? XXX.

Select the Computer providing the Registry of your SlapOS Master at the bottom of the page, then click Proceed to instantiate the service and be forwarded to the list of current services. Refresh the page, it may take a few minute for the node to be instantiated and the token to appear. It is a single use token to connect one other node to the network.

Token Instantiation

SlapOS Interface - Re6st Token Instantiation

Once the token is instantiantiated, click on it to open it's configuration and connection parameters.

Token Connection Parameters

SlapOS Interface - Re6st Token Connection Parameters

Locate the token in the Connection Parameters. It might require a few minutes to show up.

With the Registry token, you can now install a Re6st node on your machine. Head back to the terminal and follow the steps in how to add Re6st IPv6 to a node before continuing.

Configuring eNodeB

The process of installing (supplying) a software and providing it as a service (instantiation) are the same for all softwares.

However each instance can be configured differently. This section will cover the specific configuration parameters used for a eNodeB, XXX

Configuring ERP5

The process of installing (supplying) a software and providing it as a service (instantiation) are the same for all softwares.

However each instance can be configured differently. This section will cover the specific configuration parameters used for a ERP5, XXX

Updated Server List

SlapOS Interface - Server List with Partitions

If you click on the Servers menu to head back to the list of servers, you can see that the computer now has partitions (the instances provided from the softwares we installed).

After having setup and configured a Slave and Master you could now use Re6st tokens to add additional computers to the network or look into providing custom services on your network.

Thank You

Image Nexedi Office
  • Nexedi GmbH
  • 147 Rue du Ballon
  • 59110 La Madeleine
  • France