Skip to content

Installation of the Edge Gateway Server

Note

As a reminder, switching to root on Debian machines must be done with the following command:

1
su -

Downloading the mirror and necessary tools

The cyberelements Cleanroom 4.6 mirror and the Systancia repository signature key can be downloaded from this link (requires the creation of a client account): Systancia Marketplace

In addition to the mirror and key, third-party tools will be required for the upgrade process:

  • An SSH client (on Windows, you can use PuTTY)
  • An SCP client (on Windows, the WinSCP or FileZilla tools can be used)

Use the SSH client to connect remotely to your server.

Use the SCP client to transfer files to your remote machine.

Preparing for installation

Configuration of the network

It is highly recommended to define a static network address for the Edge Gateway server. To do this, you first need to retrieve the name of your machine's network interface and its MAC address. Run the following command as root:

1
ip -br link | grep -ve "^lo"

This command displays the name of the network interface, its status, its MAC address, and the interface settings.

??? example “Example” After the command is executed, the following output is displayed:

1
2
3
4
5
```
ens192           UP             00:50:56:a1:56:9f <BROADCAST,MULTICAST,UP,LOWER_UP>
```

The name of the network interface is `ens192` and its MAC address is `00:50:56:a1:56:9f`.

Once the network interface name and MAC address have been obtained, it is now possible to edit the machine's network configuration.
Edit the /etc/network/interfaces file to modify it using the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

source /etc/network/interfaces.d/*

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto br0
iface br0 inet static
    bridge_ports INTERFACE_NAME
    bridge_stp off
    bridge_fd 0
    bridge_maxwait 2
    bridge_hw MAC_ADDRESS
    address IP_GW
    netmask NETMASK
    gateway NETWORK_GATEWAY
    dns-nameservers IP_DNS_1 IP_DNS_2
    dns-search DNS_SUFFIX

Where:

  • INTERFACE_NAME must be replaced by the name of the network interface previously retrieved.
  • MAC_ADDRESS must be replaced with the MAC address previously retrieved.
  • IP_GW must be replaced with the server's IP address.
  • NETMASK must be replaced by the network mask associated with the IP address.
  • NETWORK_GATEWAY must be replaced by the default network gateway.
  • IP_DNS must be replaced by the IP address of the DNS server. If several servers need to be configured (3 maximum), separate them with a space.
  • DNS_SUFFIX must be replaced by the DNS suffix to be used. If no suffix needs to be entered, delete the line.

??? example “Example” 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

source /etc/network/interfaces.d/*

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto br0
iface br0 inet static
    bridge_ports ens192
    bridge_stp off
    bridge_fd 0
    bridge_maxwait 2
    bridge_hw 00:50:56:a1:56:9f
    address 172.16.10.10
    netmask 255.255.255.0
    gateway 172.16.10.254
    dns-nameservers 172.16.11.2 172.16.11.3
    dns-search domain.local
Before applying the configuration, there are three more steps to complete.

The first is to install packages resolvconf and bridge-utils so that the DNS configuration specified in the previous file can be applied and the br0 interface can be used:

1
apt install -y resolvconf bridge-utils

The second is to check the configuration of the /etc/hosts file with regard to the machine's primary IP address (IP_GW).
To do this, edit the /etc/hosts file and check that the second line is in the following format:

2
IP_GW   FQDN    MACHINE_NAME

??? example “Example” If the machine is named EDGE-GATEWAY without belonging to a domain and its IP address IP_GW is 172.16.10.10, then the file would be completed as follows:

1
2
3
4
5
6
7
8
9
``` linenums="2"
172.16.10.10  EDGE-GATEWAY
```

If the machine belongs to the `DOMAIN.LOCAL` domain, then the file would be completed as follows:

``` linenums="2"
172.16.10.10  EDGE-GATEWAY.DOMAIN.LOCAL   EDGE-GATEWAY
```

Attention!

An incorrect configuration of the file may cause an error when installing the collectd package.

All that remains is to restart the server: 

1
reboot

Configuring the APT package manager

Upload the files downloaded from the Systancia Marketplace to the /tmp/ directory on the server using an SCP client:

  • systancia.gpg
  • cleanroom-4.6.1-build33.1096.D12-full.tgz

Log in to the server as root, then run the following commands to unzip the Systancia repository, configure its use in APT, and authenticate it.

1
2
3
4
5
mv /tmp/systancia.gpg /etc/apt/trusted.gpg.d/
mkdir -p /opt/systancia/repository/
tar xvzf /tmp/cleanroom-4.6*.tgz -C /opt/systancia/repository/
echo "deb file:///opt/systancia/repository/ bookworm ipdiva" > /etc/apt/sources.list.d/systancia.list
apt update

We strongly recommend disabling the installation of unnecessary packages when running apt commands. To do so, run the following command:

1
echo -e 'APT::Install-Recommends false;\nAPT::Install-Suggests false;' > /etc/apt/apt.conf.d/99norecommends

Installation of the cyberelements Cleanroom Edge Gateway server

Installation of basic components

Start installing the components using the following command as root:

1
apt install -y ipdiva-base

After downloading all dependencies, a window will open asking you to select the server type. Select gateway:

What should I do if there is an error?

If there is an error in the information you entered, continue installing the ipdiva-base package and then use the following command to reconfigure the server:

1
dpkg-reconfigure ipdiva-base

Instalation of Edge Gateway components

Next, start the installation of the Edge Gateway-specific components using the following command:

1
apt install -y ipdiva-safe-gateway ipdiva-gateway-setup

The Edge Gateway server components are now installed. All that remains is to restart the machine so that the newly installed components can initialize:

1
reboot

Installation of HTML5 Gateway components

Use the following command to start installing the HTML5 Gateway components on the Edge Gateway server:

1
apt install -y ipdiva-html5gateway ipdiva-html5-webapp ipdiva-guacamole-server1

Use the following command lines to enable and configure the file transfer and virtual printer features:

1
2
3
apt install -y ghostscript
echo -e "printer=cyberelements HTML5 Printer\nprinterDriver=MS Publisher Imagesetter" > /etc/guacamole/printer-config
mkdir /home/systanciahtml5share

Configuration

Configurations prior to connecting the HTML5 Gateway

In order for HTML5 applications to work, additional settings must be configured on the Mediation Controller server. Log in to the Mediation Controller server as root.

Create or modify the /etc/ipdiva/httpd/commonParameters.extra.conf file to add a section equivalent to the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<Location /URL_HTML5/>
        Order allow,deny
        Allow from all
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-IPdiva-Gateway GW_NAME|
        RequestHeader set X-IPdiva-Orgname ORGANIZATION_NAME
        RequestHeader set X-IPdiva-Service 127.0.0.1:8080

        ProxyPass http://127.0.0.1:9016/systanciaHTML5-6.0/ flushpackets=on
</Location>

<Location /URL_HTML5/websocket-tunnel>
        Order allow,deny
        Allow from all
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-IPdiva-Gateway GW_NAME|
        RequestHeader set X-IPdiva-Orgname ORGANIZATION_NAME
        RequestHeader set X-IPdiva-Service 127.0.0.1:8080

        ProxyPass ws://127.0.0.1:9016/systanciaHTML5-6.0/websocket-tunnel
</Location>

Where:

  • The URL_HTML5 must be replaced with the content of the URL field of the HTML5 Gateway configured in the administration console when generating the pairing token.
  • GW_NAME must be replaced by the name of an Edge Gateway located on the same server as the HTML5 Gateway. The | character at the end of the line must be kept.
  • ORGANIZATION_NAME must be replaced by the name of the organization to which the previous Edge Gateway connects.

??? example “Example” For a platform with the following settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
- Organization name: `my-organization-name`
- Declaration of the HTML5 Gateway in the administration console:
    - Name: `html5-gateway`
    - URL: `HTML5`
    - Protocol: `WebSocket`
- An Edge Gateway server has:
    - An Edge Gateway service named `edge-gateway`
    - An HTML5 Gateway service named `html5-gateway`

The configuration file `/etc/ipdiva/httpd/commonParameters.extra.conf` created will be set up as follows:

``` apache hl_lines="1 5-6 12 16-17"
<Location /HTML5/>
        Order allow,deny
        Allow from all
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-IPdiva-Gateway edge-gateway|
        RequestHeader set X-IPdiva-Orgname my-organization-name
        RequestHeader set X-IPdiva-Service 127.0.0.1:8080

        ProxyPass http://127.0.0.1:9016/systanciaHTML5-6.0/ flushpackets=on
</Location>

<Location /HTML5/websocket-tunnel>
        Order allow,deny
        Allow from all
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-IPdiva-Gateway edge-gateway|
        RequestHeader set X-IPdiva-Orgname my-organization-name
        RequestHeader set X-IPdiva-Service 127.0.0.1:8080

        ProxyPass ws://127.0.0.1:9016/systanciaHTML5-6.0/websocket-tunnel
</Location>
```

Before applying the new settings, you must check that the new configuration does not cause any blocking errors for the Apache2 web server.
To do this, run the following command:

1
apache2ctl configtest

If the response is Syntax OK then the changes can be applied with the command below. Otherwise, check your configuration in the /etc/ipdiva/httpd/commonParameters.extra.conf file.

1
systemctl reload apache2

Connecting the Edge Gateway and HTML5 Gateway

Attention!

If you use certificates issued by a certification authority (CA) other than Systancia's for the SSL Router component, you must add the root CA to the Edge Gateway's trusted CAs: add the SSL Router's root CA to the trusted CAs for the Edge Gateway or HTML5 Gateway connection.

To configure the Edge Gateway and HTML5 Gateway instances on the server, follow the information provided in the following documentation: Pairing the server