SlapOS Home SlapOS

    How To Instantiate Frontend (Apache)

    FINAL - Document showing how to instantiate a Frontend (Apache) on a SlapOS node.
    • Last Update:2020-05-25
    • Version:001
    • Language:en

    How To Instantiate Frontend (Apache)

    This document explains how to instantiate an Frontend (Apache) to provide urls and access to the service on a SlapOS network.

    It will explain the different instantiation parameters. Please refer to other documents on add a software to the SlapOS Master catalog or supplying/installing a software

    Table of Content

    • Frontend (Apache) Configuration

    Frontend (Apache) Configuration

    The process of installing (supplying) a software and providing it as a service (instantiation) are the same for all software. However during instantiation 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.

    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

    After selecting Services, Adding a new service, selectin Frontend and the latest release, you should reach 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 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. Socat is 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 adresses used by the Frontend which is in its configuration folder:

    # 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:

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

    Thank You

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