Log into the SlapOS Master Dashboard at:

[master-instance-IPv4]/erp5/web_site_module/hostingjs/

Adding new nodes to a network requires access tokens. These are X509 security tokens, that identify your new node with a SlapOS Master and enable it to manage it within a network. To get such a token, in the subheader, click Token.

Note, these are single use tokens. Should the installation of SlapOS fail due to some reasons, you need to request a new token.

Click Proceed to request a token. Once it's generated, copy the token for later.

Head to the terminal and access your server. As COMP-0 will later provide Re6st and IPv6 to the SlapOS network, there likely is no IPv6 available at this point. You need to add a temporary IPv6 address range as shown in the code above.

Rationale: SlapOS requires IPv6 internally and uses Re6st, which will be installed later to enable IPv6 in heterogeneous environments (distributed machines, different types).

You will later deploy and instantiate a Re6st registry on COMP-0 to provide IPv6 and Re6st access tokens. However, in order to deploy it, SlapOS needs to be installed and to install SlapOS, IPv6 is required. Thus, we use a temporary IPv6 address range until the Registry is available, at which point it will be removed again before correctly installing Re6st with IPv6 automatically being added.

Continue and use the single line installer. You will be asked several questions during the installation. You are connecting to your own master, so on the first question, please point to port 5443 of your master's IPv4 adress (https://[IPv4]:5443), or you can use the integrated Apache from your master (the ERP5 zope IPv6 URL, such as https://[ipv6_addr]:2152) and on the second question, please add your SlapOS Master dashboard url https://[IPv4]:443/erp5/web_site_module/hostingjs/

Choose a name for your computer to identify it in your network and finally enter the association token you have received earlier. The installation can be repeated in case something goes wrong or you would like to change some of the entered parameters.

Once the installation has finishes without errors, you should see:

...
PLAY RECAP *********************************************************************
127.0.0.1                  : ok=12   changed=4   unreachable=0   failed=0

In case installation fails and you want to start over, you need to request a new token as mentioned above and, depending on whether already created, remove any existing configuration in /etc/opt/slapos/slapos.cfg before restarting.

You can verify that SlapOS was installed by trying:

# slapos node
watchdog                   RUNNING   pid 13270, uptime 0:00:03

And (re)formatting the SlapOS node:

# slapos node format --now
2018-04-21 13:07:29 slapos[13279] INFO Updating Computer
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart0
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart1
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart2
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart3
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart4
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart5
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart6
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart7
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart8
2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart9
2018-04-21 13:07:30 slapos[13279] INFO Posting information to 'https://54.37.31.108:
  5443/'
2018-04-21 13:07:30 slapos[13279] INFO slapos successfully prepared the computer.

Head back to your SlapOS Dashboard's server list and it now includes your new node which was associated to the network using the token you created. You may have to refresh the page for the server to show up.

Note, the server entry has three clickable areas:

• The line itself (click server name for example). It points to the server configuration
• The computer button. It will open the monitor - the green color indicates the server is active and contacting the Master.
• The partition button. As there are no partitions used yet, the button is still inactive.

Regarding the colored indicators:

• Green - server/partitions is contacting the SlapOS Master regularly
• Yellow - one of the server/partition processes is experiencing problems
• Red - server no longer connects to the SlapOS Master

Pick any of the available Slave nodes and click on the server (not the green 'computer' or 'partitions' buttons). In our example we currently only have a single node registered without any active partitions, so select this node to open it's configuration. You can see in the bottom table Supplied Software that this node does currently not have any software installed.

To continue, click the Supply button in the subheader to open the list of available software (releases) that can be installed on this node.

Select the Frontend (Caddy) software release, which is preinstalled on SlapOS (see how to add a software to SlapOS Master for more info).

Select the latest version.

The following dialog summarizes the software release to be installed including the computer it will be installed on. Click Proceed to continue.

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 the installation status directly by either going to your Servers list and selecting the machine you chose during installation or clicking directly on Computer Reference.

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

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

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. This node can now provide Frontend (Caddy) instances.

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 softwares currently installed!). To create an instance of an installed software, click the Add button in the subheader.

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

As during installation, please choose the latest version.

You will reach the Frontend configuration menu. It contains a form of software-specific parameters as well as a generic XML configuration field (hidden by default - click the "Show Parameter XML" button to display).

Select Software-Type custom personal, then fill the form. Don't forget to give the Frontend a title 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 (not relevant in this case as there is only one computer).

Fill the form like this :

• Title: FRONTEND
• Software type: Custom Personal
• Public IPv4: [IP_OF_YOUR_SERVER]
• IPReadLimit: 40
• Test Verification URL: https://www.erp5.com/getId
• Apache Key:[AAA]
• Apache Certificate: [BBB]
• Apache CA Certificate: [CCC]
• Domain: [domain]
• Computer: [COMP-XXXX]

Alternatively, you can choose to click on the "Show parameter XML" button and fill 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">[domain]</parameter>
    <parameter id="-frontend-quantity">1</parameter>
    <parameter id="-frontend-type">custom-personal</parameter>
    <parameter id="-sla-1-computer_guid">[COMP-XXXX]</parameter>
</instance>

using:

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

Click Proceed to start instantiation.

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-instance.log using:

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

The Frontend will be installed inside a computer partition and will listen on ports 8080 and 4443. Since permissions in Linux systems prevent users from accessing ports smaller 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
# sudo apt-get install socat

Find the IPv6 addresses used by the Frontend in its configuration folder:

root@slapostest2:/# cat /srv/slapgrid/slappart*/etc/apache_frontend.conf | grep "Listen"
Listen 10.0.176.4:8080
Listen 10.0.176.4:4443
Listen [fc01::xxxx]:8080
Listen [fc01::xxxx]:4443


Use the IPv6 adresses for ports 8080 and 4443.

Listen [fc01::e5d4]:8080
Listen [fc01::e5d4]:4443

Then call socat:

root@slapostest2:/# socat  TCP4-LISTEN:80,fork TCP6:[fc01::xxxx]:8080 &
socat TCP4-LISTEN:443,fork TCP6:[fc01::xxxx]:4443 &

To see whether your bindings are active, you can

root@slapostest2:/# 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:[fc01::xxxx]:8080
root     24674  0.0  0.0  19644  2604 ?        S    Mar20   0:00 socat 
  TCP4-LISTEN:443,fork TCP6:[fc01::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 Frontend is listening on and you should see the following:

This instance has not been found.

If this error persists, please check your instance URL and status on SlapOS Master.

In case the Frontend is not or no longer accessible, you can check on your node by:

sudo su
# slapos node
slappart8:bootstrap-monitor                EXITED    May 22 04:16 PM
slappart8:certificate_authority-on-watch   RUNNING   pid 891, uptime 16:51:03
slappart8:crond-on-watch                   RUNNING   pid 883, uptime 16:51:03
slappart8:frontend-apache-safe-graceful    EXITED    May 22 04:16 PM
slappart8:frontend-nginx-safe-graceful     EXITED    May 22 04:16 PM
slappart8:frontend_apache-on-watch         RUNNING   pid 887, uptime 16:51:03
slappart8:frontend_nginx-on-watch          RUNNING   pid 889, uptime 16:51:03
slappart8:monitor-httpd-graceful           EXITED    May 22 04:16 PM
slappart8:monitor-httpd-on-watch           RUNNING   pid 885, uptime 16:51:03
slappart8:trafficserver-on-watch           RUNNING   pid 888, uptime 16:51:03
slappart8:trafficserver-reload             EXITED    May 22 04:16 PM
slappart9:bootstrap-monitor                EXITED    May 22 04:15 PM
slappart9:certificate_authority-on-watch   RUNNING   pid 681, uptime 16:52:02
slappart9:crond                            RUNNING   pid 684, uptime 16:52:02
slappart9:monitor-httpd-graceful           EXITED    May 22 04:15 PM
slappart9:monitor-httpd-on-watch           RUNNING   pid 680, uptime 16:52:02
watchdog                                   RUNNING   pid 26276, uptime 17:53:03

If the Frontend is running check if socat is working:

# ps aux | grep "socat"
root      3234  0.0  0.0  12728  2180 pts/0    S+   09:02   0:00 grep socat

If socat is not running anymore, redo the socat binding to reach the Frontend again.

After setting up port forwarding on your Dashboard, click on the Services menu and select the Frontend entry to re-open its configuration page.

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

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. Click on the monitor-setup-url and then Save.

Click on Hosting Subscriptions to see the list of all instances that you are monitoring. Click on Synchronize to refresh the list and the status of all your monitored instances.

If you click on your instance, you will land on this instance detail. Please note that a "SlapOS instance" (that you see on "Hosting Subscriptions" list) is an instance of a SlapOS service and can be made of several smaller instances that we can call "software instances".

If you click on a software instance, you will see all the available information for this instance. You need to click on "Synchronize" in order to have the latest status. When you click on "Synchronize", the monitor will fetch the latest information for all the subscribed instances. When you have many subscribed instances, that can take a long time.

Next, we will create a second instance of the Frontend to create an easier to use url to access the SlapOS Dashboard. Head back to the Services menu and click Add another time.

Select Frontend again.

Please choose the latest version.

Select Software-Type Custom Personal (Slave) and give your Frontend slave a recognizable name. Add the Backend Url you want this Frontend to connect to. In the screenshot pictured, this is the url to a SlapOS Master Dashboard. The backend url

https://54.37.31.10/erp5/web_site_module/hostingjs/

points to this Dashboard. Set Custom Domain AND Server Alias to the wildcard domain you want to use

master.slaptest.erp5.net

then scroll down to the bottom of the page and (don't forget) to select the computer to provide the Frontend slave.

Click Proceed to continue and request instantiation.

You will be forwarded back to the list of deployed services. You might have to refresh the page for your new instance to appear. Once you can see it, click on entry to open the connection parameters.

It might take a few minutes for the instance to become available. Refresh the page from time to time until the connection parameter table shows parameters. Once the Secure Access entry shows the url, you are waiting for, the Frontend Slave is setup and working.

If you go to your requested URL (master.slaptest.erp5.net) you can see that it points to the selected backend URL.

Should you have problems in loading the page, try restarting the Frontend by ssh-ing into your node, locating the frontend_apache-on-watch process and restarting it.

sudo su
# slapos node 
slappart8:bootstrap-monitor                EXITED    Mar 20 02:28 PM
slappart8:certificate_authority-on-watch   RUNNING   pid 12137, uptime 0:33:54
slappart8:crond-on-watch                   RUNNING   pid 12125, uptime 0:33:54
slappart8:frontend-apache-safe-graceful    EXITED    Mar 20 02:28 PM
slappart8:frontend-nginx-safe-graceful     EXITED    Mar 20 02:28 PM
slappart8:frontend_apache-on-watch         EXITED    Mar 20 02:28 PM
slappart8:frontend_nginx-on-watch          RUNNING   pid 12136, uptime 0:33:54
slappart8:monitor-httpd-graceful           EXITED    Mar 20 02:28 PM
slappart8:monitor-httpd-on-watch           RUNNING   pid 12128, uptime 0:33:54
slappart8:trafficserver-on-watch           RUNNING   pid 12134, uptime 0:33:54
slappart8:trafficserver-reload             EXITED    Mar 20 02:28 PM
slappart9:bootstrap-monitor                EXITED    Mar 20 02:29 PM
slappart9:certificate_authority-on-watch   RUNNING   pid 11866, uptime 0:36:16
slappart9:crond                            RUNNING   pid 11867, uptime 0:36:16
slappart9:monitor-httpd-graceful           EXITED    Mar 20 02:29 PM
slappart9:monitor-httpd-on-watch           RUNNING   pid 11865, uptime 0:36:16
watchdog                                   RUNNING   pid 24426, uptime 7 days,...

To restart a service you can use slapos node restart slappart8:frontend_apache-on-watch.

Pick any of the available Slave nodes. You can see in the bottom table Supplied Software that this node now has the Frontend (Caddy) software release installed. We will add Re6st in the same way.

Click the Supply button.

Select the Re6st software release.

Select the latest version.

The following dialog summarizes the software release to be installed as well as the computer it will be installed on. Click Proceed to launch instantiation.

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

You can see the installed service now includes Re6st. 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.

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 or calling slapos node software directly.

Once installed, head to the list of services by clicking on Services in the side menu. Then click add.

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

As during installation, please choose the latest version.

After adding a recognizable name, select the software-type Default, then provide the following parameters:

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 instantiation. This will forward you to the list of current services.

Refresh the page to show your instance and installation status.

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

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

As the Registry is listening on port 19201 and permissions in Linux systems prevent users from accessing ports below 1024, traffic must be forwarded.

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 required, head to your terminal and:

sudo su
# apt-get install socat

Still in your terminal, start to see whether the Registry has finished installing (use # slapos node instance to follow installation):

# 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

Find the IP using:

# ifconfig eth0 | grep inet
            inet addr:167.114.246.26  Bcast:167.114.246.26  Mask:255.255.255.255

Then call Socat with the listening tcp entry and the inet addr:

# socat TCP4-LISTEN:9201,fork,bind=167.114.246.26 TCP4:10.0.27.44:9201 &

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

To verify whether port forwarding works, you can:

# ps aux | grep socat

root 1954  0.0  0.0  19648  1748 pts/1 S  12:46 0:00 socat TCP4-LISTEN
  :9201,fork,bind=167.114.246.26 TCP4:10.0.232.26:9201
root 1963  0.0  0.0  12728  2224 pts/1 S+ 12:46 0:00 grep socat
root 3309  0.0  0.0  19648  2688 pts/0 S  09:03 0:00 socat TCP4-LISTEN
  :80,fork TCP6:[fc01::b566]:8080
root 3310  0.0  0.0  19648  2740 pts/0 S  09:03 0:00 socat TCP4-LISTEN
  :443,fork TCP6:[fc01::b566]:4443

Before finishing make sure that any temporary IPv6 address space added during installation of the SlapOS node itself 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.

Once port forwarding is setup, try accessing the registry over the Registry master-url 167.114.246.26:9201. Note down this URL, it needs to be provided every time Re6st is installed on a new server to be added to the network.

Head to the list of services by clicking on the Services button on the side menu, then click the Add button in the subheader.

Select Re6st as this is the service we want to provide. The differentiation between Registry and Token will be made via the configuration parameter Software-Type.

As during installation, please choose the latest version.

Select Software Type Re6st Token which will load a form with instance-specific parameters. As mentioned, the token is actually a slave instance of the Registry (and in case of COMP-0 a first gateway node).

Every new node will require a token, so give this token a recognizable name (Re6st-COMP-0 for example).

Select the Computer on which the Registry of your SlapOS Master is to be installed on 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.

Click Proceed to instantiate a new token. Refresh the list of instantiated services to make the token appear. Click on it to access the connection parameters.

Locate the token in the Connection Parameters. It might require a few minutes to show up. Refresh the page to see whether the token has been instantiated.

You can now install Re6st on this machine. It will add back actual IPv6 after the temporary IPv6 has been removed again.

Verify that the configuration files were created.

You need to add the master_url IPv4 adress to the Re6st configuraiton file as it is the first gateway node. In this example, add:

# added the following to the end of the file first node
ip 167.114.246.26
gateway

Then restart Re6st afterwards using service re6stnet restart.

You can use the above command to see whether Re6st is working. The output should be similar to:

● re6stnet.service - (null)
   Loaded: loaded (/etc/init.d/re6stnet)
   Active: active (running) since Fri 2018-03-09 16:43:23 UTC; 6min ago
   Process: 26395 ExecStop=/etc/init.d/re6stnet stop (code=exited, status=0/SUCCESS)
   Process: 26423 ExecStart=/etc/init.d/re6stnet start (code=exited, status=0/SUCCESS)
   CGroup: /system.slice/re6stnet.service
           ├─26431 /opt/re6st/parts/python2.7/bin/python2.7 /usr/sbin/re6stnet 
@re6stnet.conf
           ├─26437 openvpn --dev-type tap --dev re6stnet-tcp --persist-tun --per
sist-key --script-security 2 --up /opt/re6st/eggs/re6stnet-0.485-py2.7.egg/re6st
/ovpn-client --tls-server --mode server --clien...
           ├─26444 babeld -h 15 -H 15 -L /var/log/re6stnet/babeld.log -S /var/li
b/re6stnet/babeld.state -I /var/run/re6stnet/babeld.pid -s -C ipv6-subtrees true
-C default max-rtt-penalty 5000 rtt-max 500 rt...
           ├─26537 openvpn --dev-type tap --dev re6stnet1 --persist-tun --persis
t-key --script-security 2 --up /opt/re6st/eggs/re6stnet-0.485-py2.7.egg/re6st/ov
pn-client --nobind --client --remote 163.172.45...
           └─26862 openvpn --dev-type tap --dev re6stnet2 --persist-tun --persis
t-key --script-security 2 --up /opt/re6st/eggs/re6stnet-0.485-py2.7.egg/re6st/ov
pn-client --nobind --client --remote 52.36.124....

  Mar 09 16:43:23 slapostest2 systemd[1]: Started (null).

At this point the COMP-0 node is completely setup and working. You can now continue to add additional nodes to the network.