1. Preface

This installation guide is based on Ubuntu 22.04 server. Commands may vary for other Linux distributions. A recent and systemd-based Linux is highly recommended.

2. Supported Version

This guide refers to the following versions:

Router management

2024.10.0

Autoupdate

2024.10.0

3. System Requirements

3.1. Application Server

  • Ubuntu 22.04 server (preferred)

  • 8 vCPUs

  • 16 GB RAM

  • 100 GB HDD

3.2. Optional: Dedicated Database Server for Larger Environments

  • Ubuntu 22.04 server (preferred)

  • 8 vCPUs

  • 16 GB RAM

  • 100 GB HDD

4. Setup PostgreSQL Database

Install a Postgres database server onto your application server or dedicated database server.

1
2

sudo apt update
sudo apt install postgresql-14 -y

Login to your postgres user, run psql CLI tool and execute the SQL commands.

1

sudo -u postgres psql

When logged in, run the following queries to create the database and user.

1
2
3
4
5

create database insysicomroutermgmt;
create user u4insysicomroutermgmt with encrypted password 'pw4insysicomroutermgmt';
alter database insysicomroutermgmt owner to u4insysicomroutermgmt;
grant all privileges on database insysicomroutermgmt to u4insysicomroutermgmt;
\q

4.1. Additional steps for a dedicated PostgreSQL server

You have to allow remote access to access a dedicated PostgreSQL database server from outside. The path depends on your PostgreSQL version; we are currently using Version 14.

1

sudo vi /etc/postgresql/14/main/postgresql.conf

Look for this line in the file:

1

#listen_addresses = 'localhost'

Uncomment, and change the value to *; this will allow Postgres' connections from anyone.

1

listen_addresses = '*'

Save and exit the file. Next, modify pg_hba.conf to also allow connections from everyone.

1

sudo vi /etc/postgresql/{db-psql-version}/main/pg_hba.conf

Modify this section:

# IPv4 local connections:
host    all             all             127.0.0.1/32            md5

To this:

# IPv4 local connections:
host    all             all             0.0.0.0/0            md5

In case of an active firewall, run

1

sudo ufw allow 5432/tcp

Restart the database service.

1

sudo systemctl restart postgresql

5. Setup application server

Create a directory in your home and copy the installation zip file irm_linux_2024_10_0.zip into this directory. Extract the content and remember the path. You need the router management executable for the next steps.

1
2
3
4

mkdir dist
cd dist
unzip irm_linux_2024_10_0.zip
ls -aFl

The list command should show the following files:

  • insysicom-routermgmt

  • insysicom-autoupdate

  • irm_linux_2024_10_0.zip

1

cd

Create a service user and all required directories. Populate the directories with the configurations and application binaries.

1
2
3
4
5
6
7
8

sudo adduser --home /var/opt/insysicom-routermgmt --no-create-home --gecos --disabled-password insysicom-routermgmt
sudo mkdir -p /opt/insysicom-routermgmt/etc
sudo mkdir -p /opt/insysicom-routermgmt/bin
sudo cp ./dist/insysicom-routermgmt /opt/insysicom-routermgmt/bin
sudo cp ./dist/insysicom-autoupdate /opt/insysicom-routermgmt/bin
sudo chown -R insysicom-routermgmt:insysicom-routermgmt /opt/insysicom-routermgmt
sudo mkdir /var/opt/insysicom-routermgmt
sudo chown insysicom-routermgmt:insysicom-routermgmt /var/opt/insysicom-routermgmt

5.1. Setup routermanagement-installation

We’re about to initialize the application for the first time. You have to change your current user to the previously added user insysicom-routermgmt and then change to the /opt/insysicom-routermgmt/etc directory. In this directory, we are placing our generated configuration file. The environment variables are necessary for the database connection. The initialization process prepares the database and afterwards dumps the configuration file into the current directory. The configuration file includes several application settings.

If you run a dedicated database server, change BARRACUDA_DATABASE_ARGS to match your database server hostname or IP address, e.g.: BARRACUDA_DATABASE_AGRS="…​ host=mydbserver port=5432 …​" 
1
2
3
4
5

sudo -i -u insysicom-routermgmt
cd /opt/insysicom-routermgmt/etc/
export BARRACUDA_DATABASE_DIALECT="postgres"
export BARRACUDA_DATABASE_ARGS="user=u4insysicomroutermgmt password=pw4insysicomroutermgmt dbname=insysicomroutermgmt host=localhost port=5432 sslmode=disable"
/opt/insysicom-routermgmt/bin/insysicom-routermgmt system upgrade --init --dump-config=insysicom-routermgmt.conf

Change the specified settings in the insysicom-routermgmt.conf file in order to allow communication between this service and the autoupdate service:

Open the configuration file.

1

vi /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf
/opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

barracuda_admin_api_port: 9201
barracuda_admin_api_host: "127.0.0.1"
bonaventure_grpc_server_port: 50052
bonaventure_grpc_server_host: "127.0.0.1"
barracuda_service_port: 9202
barracuda_service_host: "127.0.0.1"
barracuda_api_port: 9203
barracuda_api_host: "127.0.0.1"
barracuda_swagger_host: localhost
barracuda_swagger_port: 9203
barracuda_data_path: /var/opt/insysicom-routermgmt
...

Now, the configuration is adapted to fit the environment.

These settings ensure that the router management daemon is only accessible on your localhost and doesn’t conflict with common IP ports, because the application is protected with a front-facing NGINX web server. The barracuda_data_path setting has to be adjusted, because the init process adds the hidden directory .barracuda. This is not necessary in case of an application server.

5.2. Setup autoupdate-installation

To configure the autoupdate service, you need to create an environment file in the same directory as the router management configuration file.

1

vi /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env

Add the following content:

1
2
3
4
5

AUTOUPDATE_HTTP_PORT=8082
AUTOUPDATE_GRPC_PORT=50052
AUTOUPDATE_HTTP_READ_TIMEOUT=60s
AUTOUPDATE_SHUTDOWN_TIMEOUT=10s
FILE_STORAGE_TYPE=filesystem

Settings, that already exist in the routermanagement configuration file, are added to the environment file.

1
2
3

echo "MASTER_KEY=$(grep -oP '(?<=barracuda_master_key: ).*' /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf)" >> /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env
echo "DATABASE_ARGS=\"$(grep -oP '(?<=barracuda_database_args: ).*' /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf) $(grep -oP 'dbname=.*' /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf)\"" >> /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env
echo "DATA_DIRECTORY=$(grep -oP '(?<=barracuda_data_path: ).*' /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf)" >> /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env

Execute the following command to prepare the database for the autoupdate service.

1
2
3
4

set -a
source /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env
set +a
/opt/insysicom-routermgmt/bin/insysicom-autoupdate -migrate

The result should be Migration completed successfully or No pending migrations, depending on the current state of the database.

5.3. Create the systemd services

Switch back to your administrative user.

1

exit

Create a systemd service for the routermanagement.

1

sudo vi /etc/systemd/system/insysicom-routermgmt.service
If Postgres does not run on the same machine, please remove the line After=postgresql.service from the Unit section of your service
/etc/systemd/system/insysicom-routermgmt.service
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[Unit]
Description=INSYS icom Router Management
After=postgresql.service

[Service]
Type=simple
User=insysicom-routermgmt
Group=insysicom-routermgmt
WorkingDirectory=/var/opt/insysicom-routermgmt
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=insysicom-routermgmt
ExecStart=/opt/insysicom-routermgmt/bin/insysicom-routermgmt serve all -c /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf

[Install]
WantedBy=multi-user.target

Create a systemd service for the autoupdate.

1

sudo vi /etc/systemd/system/insysicom-autoupdate.service
If Postgres does not run on the same machine, please remove the line After=postgresql.service from the Unit section of your service
/etc/systemd/system/insysicom-autoupdate.service
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

[Unit]
Description=INSYS icom Autoupdateserver
After=postgresql.service

[Service]
Type=simple
User=insysicom-routermgmt
Group=insysicom-routermgmt
WorkingDirectory=/var/opt/insysicom-routermgmt
StandardOutput=file:/var/opt/insysicom-routermgmt/autoupdate_stdout.log
StandardError=file:/var/opt/insysicom-routermgmt/autoupdate_stderr.log
SyslogIdentifier=insysicom_autoupdate
EnvironmentFile=/opt/insysicom-routermgmt/etc/insysicom-autoupdate.env
ExecStart=/opt/insysicom-routermgmt/bin/insysicom-autoupdate -serve

[Install]
WantedBy=multi-user.target

5.4. Start the systemd services

1
2
3
4

sudo systemctl enable insysicom-routermgmt.service
sudo systemctl start insysicom-routermgmt.service
sudo systemctl enable insysicom-autoupdate.service
sudo systemctl start insysicom-autoupdate.service

Check if the systemd services are running. The status should be active (running) and the indicator should be lit green.

1
2

sudo systemctl status insysicom-routermgmt.service
sudo systemctl status insysicom-autoupdate.service

Setup cronjob for fetching device information

1

sudo crontab -e

and add the following lines to the end of the file:

1
2

30 4 * * * /opt/insysicom-routermgmt/bin/insysicom-routermgmt system fetchDeviceInfo -c /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf;
0 0 * * * /opt/insysicom-routermgmt/bin/insysicom-routermgmt system updateLicenseStatus -c /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf;

6. Setup NGINX web server

We highly recommend to start with the following HTTP-only setup and check the proper operation of the routermanagement application first, before you setup TLS.

Install NGINX

1
2

sudo apt update
sudo apt install nginx

Create a new NGINX server config

1

sudo vi /etc/nginx/sites-available/insysicom-routermgmt
/etc/nginx/sites-available/insysicom-routermgmt
 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

server {
    listen 80;
    listen [::]:80;
    server_name _;

    client_max_body_size 300M;
    client_header_timeout 600;
    client_body_timeout 600;
    send_timeout 600;
    proxy_read_timeout 600;

    location = / {
        return 301 /ui;
    }
    location /ui/ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:9203;
    }
    location /api/ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:9203;
    }
    location /auth/ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:9203;
    }
    location /graphql {
        proxy_read_timeout 180s;
        proxy_connect_timeout 180s;
        proxy_send_timeout 180s;
        send_timeout 180s;
        proxy_pass http://127.0.0.1:9203/graphql;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
    }
}

server {
    listen 8080;
    listen [::]:8080;
    server_name _;
    location /devicecontrol {
        proxy_read_timeout 180s;
        proxy_connect_timeout 180s;
        proxy_send_timeout 180s;
        send_timeout 180s;
        proxy_pass http://127.0.0.1:9202/devicecontrol;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    location /autoupdate/ {
        proxy_pass http://127.0.0.1:8082;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    }
}

Enable the server config and disable the default config

1
2

sudo ln -s /etc/nginx/sites-available/insysicom-routermgmt /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default

Adjust the server settings

1

sudo vi /etc/nginx/nginx.conf
/etc/nginx/nginx.conf
...
worker_rlimit_nofile 40000;
events {
        worker_connections 20000;
        # multi_accept on;
}

http {
    ...
    server_names_hash_bucket_size 64;
    ...
}
...

Validate the config and restart the webserver

1
2

sudo nginx -t
sudo systemctl restart nginx

7. Adjust system settings

To setup a router connection, changes to the System settings are needed. Otherwise the download of a routers startup configuration will fail.

Open your web browser and navigate to the installed application: http://myserver_or_ip_address

Login with the default credentials (you can change username and password later).

Username: default
Password: secret

Navigate to System Administration ⇒ System settings and adjust the following three setting as shown:

Name Value

DEVICECONTROL_SERVER_CERT

NONE

AUTOUPDATE_SERVER_CERT

NONE

INVENTORY_CONNECTION_PROFILE_HOSTNAME

IP-address or FQDN of your application server

Fully Qualified Domain Name (FQDN)

8. Check if your setup is working properly

Navigate to the router list, register a new router, use dummy values and try to download the startup-configuration.

NOTE: If you’re encountering difficulties downloading the startup configuration or registering a new router, it may indicate an issue with the application setup. If you cannot access the web application, please check your network and/or firewall settings. For specific help please contact our support team.

Extract the tarball archive and open the file ConnectionProfile_xxx.txt in your preferred text editor. The content of the file should look similar to the following output.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

-----LUA-----
host = "164.90.225.14"
path = "devicecontrol"
active_https = "0"
port = "8080"
device_id = "9a201fa4-c022-49ae-a5ba-86ee79acbbdd"
realm_uri = "devices.insys-tec.net"
-- configure the remote management service
cli("administration.remote_management.active=1")
cli("administration.remote_management.host=" .. host)
cli("administration.remote_management.path=" .. path)
cli("administration.remote_management.port=" .. port)
cli("administration.remote_management.device_id=" .. device_id)
cli("administration.remote_management.realm_uri=" .. realm_uri)
cli("administration.remote_management.active_https=" .. active_https)
cli("administration.remote_management.client_cert=" .. cert_name)
cli("administration.remote_management.client_key=" .. key_name)

-- activate profile
cli("administration.profiles.activate")
-----LUA-----

The parameter host should match the IP-address of your application server. In case you’re using a FQDN the host parameter should contain the corresponding FQDN.

Finally check if the websocket is accessible. Otherwise your routers cannot connect to the router management application. Change to a different machine and try the following command. Please adjust the IP address to match your application server’s IP address (or FQDN). The given port 8080 matches our current NGINX configuration.

1

curl http://164.90.225.14:8080/devicecontrol

If you receive the error handshake error: bad "Upgrade" header, everything is working as expected. In case of any other errors, please check your network and/or firewall settings.

9. Router Management in HTTP-only mode is ready for operation

The router management application is now prepared to handle router management exclusively through HTTP.

If the network infrastructure is entirely private or inaccessible from external sources, or if routers are connected through secure VPN tunnels (such as IPSec) to a corporate network, there is no need to implement additional TLS encryption and authentication. In such cases, the current setup can remain unchanged.

However, if the network configuration does not meet these criteria, it is advisable to proceed with the TLS configuration as described.

10. Securing with TLS

As router management is a fully web-based application, there are various methods to secure the application using TLS. This installation guide outlines the use of private certificates while separating the application and router connections (web sockets) through different IP ports, all utilizing the same application server IP address. The HTTP-only NGINX configuration mentioned earlier illustrates this setup. The application operates on port 80, while the routers connect to the backend through port 8080.

The ports will be changed to 443 and 8443, as these are commonly used for TLS authentication and encryption.

For those interested in using public certificates or managing router connections via a dedicated IP address or setting up NGINX DNS-based virtual hosts, please reach out for further assistance.

10.1. Issuing the server certificate

We do not support self-signed server certificates!

A server certificate matching the specific environment is needed to continue.

The common name should correspond to the FQDN of the application server. If an IP address-based connection is preferred, include an IP Subject Alternative Name (SAN) in the certificate. The example provided includes both elements.

The following certificate authority is used to sign the server certificate (the output has been trimmed to show only the relevant content):

CA
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 5909721596463708658 (0x52038c7b1eac79f2)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=DE, L=Regensburg, O=INSYS MICROELECTRONICS GmbH, CN=iRM Install Guide Certificate Services
        Validity
            Not Before: May 24 12:40:00 2022 GMT
            Not After : May 24 12:40:00 2032 GMT
        Subject: C=DE, L=Regensburg, O=INSYS MICROELECTRONICS GmbH, CN=iRM Install Guide Certificate Services
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:TRUE
            X509v3 Key Usage: critical
                Certificate Sign, CRL Sign

The resulting server certificate (with the output trimmed to display only the relevant content) is utilized in the forthcoming configuration. Additionally, the private key associated with this certificate is required.

Server Certificate
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 3573560371971845316 (0x3197d6398acb6cc4)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=DE, L=Regensburg, O=INSYS MICROELECTRONICS GmbH, CN=iRM Install Guide Certificate Services
        Validity
            Not Before: May 24 12:41:00 2022 GMT
            Not After : May 24 12:41:00 2024 GMT
        Subject: C=DE, L=Regensburg, O=INSYS MICROELECTRONICS GmbH, CN=irmop1.icomcloud.net
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Server Authentication, TLS Web Client Authentication
            X509v3 Subject Alternative Name:
                DNS:irmop1.icomcloud.net, IP Address:164.90.225.14

For the following instructions 3 PEM files are needed.

  • Certificate Authority (or chain) (in this guide called: iRM_Install_Guide_Certificate_Services.crt)

  • Server Certificate (in this guide called: irmop1.icomcloud.net.crt)

  • Server Private Key (in this guide called: irmop1.icomcloud.net.key)

10.2. Setup NGINX SSL

For TLS version 1.3 is recommended. If especialy needed, version 1.2 can also be used.

The file ssl-params.conf can be modified to meet specific security requirements. The sample configuration below is currently in use within our own cloud environment. Given that router management is a fully web-based application, it supports all standard features associated with such.

1

sudo vi /etc/nginx/snippets/ssl-params.conf
/etc/nginx/snippets/ssl-params.conf
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_dhparam /etc/nginx/dhparam.pem;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384;
ssl_ecdh_curve secp384r1; # Requires nginx >= 1.1.0
ssl_session_timeout  10m;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off; # Requires nginx >= 1.5.9
ssl_stapling on; # Requires nginx >= 1.3.7
ssl_stapling_verify on; # Requires nginx => 1.3.7
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
# Disable strict transport security for now. You can uncomment the following
# line if you understand the implications.
# add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";

Create Diffie-Hellman (DH) parameters based on the configurations specified in ssl-params.conf.

1

openssl dhparam -out /etc/nginx/dhparam.pem 4096

The certificates must be chained in the order expected by NGINX.

1
2
3
4

sudo mkdir /etc/nginx/ssl
sudo cat irmop1.icomcloud.net.crt iRM_Install_Guide_Certificate_Services.crt > /etc/nginx/ssl/insysicom-routermgmt.crt
sudo cp irmop1.icomcloud.net.key /etc/nginx/ssl/insysicom-routermgmt.key
sudo chmod 600 /etc/nginx/ssl/insysicom-routermgmt.key

The snippet should be configured to add the certificate chain and the private key to the NGINX configuration.

1

sudo vi /etc/nginx/snippets/insysicom-routermgmt-ssl.conf
/etc/nginx/snippets/insysicom-routermgmt-ssl.conf
1
2

ssl_certificate /etc/nginx/ssl/insysicom-routermgmt.crt;
ssl_certificate_key /etc/nginx/ssl/insysicom-routermgmt.key;

Finally, SSL support should be added to the NGINX configuration.

1

sudo vi /etc/nginx/sites-available/insysicom-routermgmt
/etc/nginx/sites-available/insysicom-routermgmt
 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    include snippets/insysicom-routermgmt-ssl.conf;
    include snippets/ssl-params.conf;
    server_name _;

    client_max_body_size 300M;
    client_header_timeout 600;
    client_body_timeout 600;
    send_timeout 600;
    proxy_read_timeout 600;

    location = / {
        return 301 /ui;
    }
    location /ui/ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:9203;
    }
    location /api/ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:9203;
    }
    location /auth/ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://127.0.0.1:9203;
    }
    location /graphql {
        proxy_read_timeout 180s;
        proxy_connect_timeout 180s;
        proxy_send_timeout 180s;
        send_timeout 180s;
        proxy_pass http://127.0.0.1:9203/graphql;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
    }
}

server {
    listen 8443 ssl;
    listen [::]:8443 ssl;
    include snippets/insysicom-routermgmt-ssl.conf;
    include snippets/ssl-params.conf;
    server_name _;

    location /devicecontrol {
        proxy_pass http://127.0.0.1:9202/devicecontrol;
        proxy_http_version 1.1;
        proxy_read_timeout 180s;
        proxy_connect_timeout 180s;
        proxy_send_timeout 180s;
        send_timeout 180s;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    location /autoupdate/ {
        proxy_pass http://127.0.0.1:8082;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   }
}

The NGINX SSL setup should now be checked to ensure it is functioning correctly before proceeding with the TLS configuration.

1
2
3

sudo nginx -t
sudo systemctl restart nginx
curl --cacert iRM_Install_Guide_Certificate_Services.crt https://164.90.225.14:8443/devicecontrol

The expected response is a handshake error: bad "Upgrade" header.

The parameter --cacert should point to the CA-chain PEM file that was used to sign the server certificate. Otherwise, the curl command will fail due to a lack of trust in the private certificates. Alternatively, the parameter -k can be used. For additional details, refer to the man pages of the curl command.

The handshake error will be encountered again. The router connection is functioning as expected and is now secured by TLS.

Open the browser and navigate to your router managements user interface.

The router managements user interface should appear. If the computer does not trust the private certificate authority, the web browser will display an error. This error can be bypassed by continuing to browse to the untrusted site or by adding the certificate authority to the list of trusted certificate authorities.

10.3. Add TLS support to router management

Router management requires access to the new server certificate as well. Since NGINX handles the TLS termination, it is only necessary to upload the public TLS certificate, such as irmop1.icomcloud.net.crt.

To import the certificate, navigate to the router management interface in the browser and go to Certificate Management ⇒ Certificates . A certificate with name (and a password if applicable) needs to be uploaded. After uploading, it can be used as server certificate by selecting it and executing Action⇒*Use as server certificate* in the top right.

Navigate to System Administration ⇒ System settings and set the appropriate TLS port:

Name Value

INVENTORY_CONNECTION_PROFILE_PORT

8443

After these system changes, router management is prepared to handle router connections via HTTPS. Access the router list and download the startup configuration again. A router for testing purposes was added in the previous section of the installation guide. If the tarball archive is extracted now and the file ConnectionProfile_xxx.txt is opened, a different configuration should be recognizable, which includes a client certificate, a client private key, and several other commands.

If the download of the startup configurations fails, it indicates that something was missed during the configuration process.

10.4. Add TLS client-authentication

When a new router is registered in the router management application, a client certificate for the router is automatically generated. This client certificate is included in the router’s startup configuration and will be installed on the router.

It is highly recommended to create a separate certificate authority (CA) for signing client certificates, rather than using the pre-installed CA. During initialization, router management will automatically create a CA and set it as the default for client certificates. However, this CA includes various attributes referencing INSYS icom GmbH properties. In this installation guide, an internal PKI is used to generate a new certificate authority. Alternatively, an existing PKI can be used, and a signing CA can be uploaded. For assistance with using an existing PKI, please contact support.
The HTTPS protocol shall never be used for the CRL distribution endpoint, as this can lead to download failures. Always use plain, unsecured HTTP. Since the CRL does not contain sensitive information and is signed by the associated CA, there are no security concerns.

Go to the router management interface in the browser and navigate to Certificate Management ⇒ Certificate Authorities . Click on Upload, select the CA (referred to in this guide as your_client_authentication-ca.crt), and choose New certificate authority with key (Format: PKCS#12). Provide a name (and a password if applicable).

After the upload, select the CA and click on Select action ⇒ Configure client CA in the top right. Read the information boxes and confirm that all the described requirements have been met. Since router management is using the default certificate authority, the new CA needs to be introduced.

Navigate to Routers in the router management interface and delete all registered routers. Register a router for testing purposes. The router management now creates a new client certificate that is signed by our new certificate authority.

If the router registration fails, an error in the setup may have occurred. Please contact support for further assistance.

Return to the console to set up NGINX.

Download the new certificate authority in PEM format.

In order to enable TLS client-authentication within the NGINX web server, we have to change the current configuration.

Copy the previously uploaded CA file your_client_authentication-ca.crt into the NGINX SSL folder.

1

sudo cp your_client_authentication-ca.crt /etc/nginx/ssl

Adjust the NGINX server configuration for the server running on port 8443.

1

sudo vi /etc/nginx/sites-available/insysicom-routermgmt
/etc/nginx/sites-available/insysicom-routermgmt
1
2
3
4
5
6
7

server {
    listen 8443 ssl;
    ...
    ssl_client_certificate /etc/nginx/ssl/your_client_authentication-ca.crt;
    ssl_verify_client on;
    ...
}

Verify and enable the new NGINX configuration.

1
2

sudo nginx -t
sudo systemctl restart nginx

Attempt to connect to the web socket endpoint without a client certificate.

1

curl https://164.90.225.14:8443/devicecontrol

This should result in an error.

1
2
3
4
5
6
7
8

<html>
<head><title>400 No required SSL certificate was sent</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<center>No required SSL certificate was sent</center>
<hr><center>nginx/1.18.0 (Ubuntu)</center>
</body>
</html>

Attempt to connect to the web socket endpoint using a valid client certificate. For that, access the router managements user interface and download the startup configuration for the previously added router.

Extract the tarball archive and open the file ConnectionProfile_xxx.txt. This file contains two PEM blocks: a certificate and a private key. Copy these PEM blocks (excluding the square brackets) into separate files (client.crt and client.key) on the local PC. These files will be needed for the subsequent curl command.

1

curl --cert client.crt --key client.key --cacert iRM_Install_Guide_Certificate_Services.crt https://164.90.225.14:8443/devicecontrol

If you receive a handshake error: bad "Upgrade" header, the TLS client authentication is working.

10.5. Forward client certificate to router management for further processing

The following configuration is required for your routers to download associated update-packets.

1

sudo vi /etc/nginx/sites-available/insysicom-routermgmt
/etc/nginx/sites-available/insysicom-routermgmt
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

server {
    listen 8443 ssl;
    ...
    location /devicecontrol {
        ...
        proxy_set_header X-Forwarded-Client-Cert $ssl_client_cert;
    }
    location /autoupdate/ {
        ...
        proxy_set_header X-Forwarded-Client-Cert $ssl_client_cert;
    }
}

Check and enable the new NGINX configuration.

1
2

sudo nginx -t
sudo systemctl restart nginx

10.6. Notes for connecting a icom OS router

Since private certificates are being used in this example, the icom OS router does not trust the CA that signed the NGINX server certificate. Before applying the startup configuration on the router, the CA certificates must be installed.

Open the routers user interface and navigate to Administration ⇒ Certificates.

Upload the CA certificate that was used to sign the server certificate. If a CA hierarchy is being used, begin with the Root CA and then add the Intermediate CAs in the correct order.

Now, the router is ready to be connected to the router management application. Ensure that the network settings allow a connection from the router to the router management server. Test the connection using a ping. Navigate to Administration ⇒ Debugging in the routers user interface and send a ping to the IP address or FQDN of the router management application server.

Ensure that NTP is configured on the routers. The date and time must be set correctly to allow connections via certificates.

Access the router managements user interface and register the icom OS router. Download its startup configuration and return to the routers user interface. Navigate to Administration ⇒ icom Router Management. Select and upload the startup configuration.

If everything is set up correctly, the router should connect to the router management, and the connection status will change to online.

11. Installation approval

NOTE: The installation is only considered complete upon approval from the support team. A checklist for prior verification can be downloaded: Post installation checklist.

Back to the Configuration Guides for icom Router Management

Back to overview