1. Preface
This installation guide is based on Ubuntu 22.04 Linux. Commands may vary for other Linux distributions. A recent and systemd-based Linux is highly recommended.
4. Setup PostgreSQL Database
Install a Postgre database server onto your application server or dedicated database server.
$ sudo apt update $ sudo apt install postgresql postgresql-contrib
Login to your postgres user, run psql CLI tool and execute the SQL commands.
$ sudo -u postgres psql
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.
$ sudo vi /etc/postgresql/14/main/postgresql.conf
Look for this line in the file:
#listen_addresses = 'localhost'
Uncomment, and change the value to *; this will allow Postgre’s connections from anyone.
listen_addresses = '*'
Save and exit the file.
Next, modify pg_hba.conf to also allow connections from everyone.
$ sudo vi /etc/postgresql/14/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
$ sudo ufw allow 5432/tcp
Restart the database service.
$ sudo systemctl restart postgresql
5. Setup application server
Create a directory in your home and copy the installation zip file irm_linux_2024_07_0.zip into this directory.
Extract the content and remember the path.
You need the router management executable for the next steps.
$ mkdir dist $ cd dist $ unzip irm_linux_2024_07_0.zip $ ls -aFl total 86292 drwxr-xr-x 3 root root 4096 May 24 10:27 ./ drwx------ 7 root root 4096 May 24 10:24 ../ -rw-r--r-- 1 root root 137 Dec 22 11:43 README.txt -rwxr-xr-x 1 root root 69894144 Dec 22 11:07 insysicom-routermgmt* -rw-r--r-- 1 root root 24819506 May 2 09:58 irm_linux_2024_07_0.zip $ cd
Create a service user, all required directories and populate the directories with the configuration and application binary.
$ sudo adduser --home /var/opt/insysicom-routermgmt --no-create-home --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 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
We’re about to initialize the application for the first time.
You have to change your current user to previously added insysicom-routermgmt user 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 dumps afterwards 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 …"
|
$ 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
Now, we change now some settings in the configuration file to fit the environment.
$ vi /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf
barracuda_admin_api_port: 9201 barracuda_admin_api_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
These settings ensure that the router management daemon is only accessible on your localhost and doesn’t conflict with common IP ports, because we protect the application with a front-facing NGINX web server.
The barracuda_data_path setting has to be adjusted, because the init process adds accidentally the hidden directory .barracuda.
This is not necessary in case of an application server.
Switch back to your administrative user, now.
$ exit
Create the systemd service
$ sudo vi /etc/systemd/system/insysicom-routermgmt.service
If Postgres does not run on the same machine, please remove the line starting with After from the Unit section of your service
|
[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
Start the systemd service
$ sudo systemctl enable insysicom-routermgmt.service $ sudo systemctl start insysicom-routermgmt.service
Check if the systemd service is running
$ sudo systemctl status insysicom-routermgmt.service
● insysicom-routermgmt.service - INSYS icom Router Management
Loaded: loaded (/etc/systemd/system/insysicom-routermgmt.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2024-05-16 11:09:12 UTC; 45s ago
Main PID: 2056 (insysicom-routermgmt)
Tasks: 6 (limit: 1131)
Memory: 57.0M
CGroup: /system.slice/insysicom-routermgmt.service
└─2056 /opt/insysicom-routermgmt/bin/insysicom-routermgmt serve all -c /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf
May 24 11:09:12 ubuntu-s-1vcpu-1gb-fra1-01 systemd[1]: Started INSYS icom Router Management.
May 24 11:09:12 ubuntu-s-1vcpu-1gb-fra1-01 insysicom-routermgmt[2056]: time="2024-05-16T11:09:12Z" level=warning msg="ATTENTION: Starting in dangerous HTTP mode..."
May 24 11:09:12 ubuntu-s-1vcpu-1gb-fra1-01 insysicom-routermgmt[2056]: time="2024-05-16T11:09:12Z" level=info msg="Started Admin-API server (3/3)" host=127.0.0.1 port=9201
May 24 11:09:12 ubuntu-s-1vcpu-1gb-fra1-01 insysicom-routermgmt[2056]: time="2024-05-16T11:09:12Z" level=info msg="Started device-services server (1/3)" host=127.0.0.1 port=9202
May 24 11:09:12 ubuntu-s-1vcpu-1gb-fra1-01 insysicom-routermgmt[2056]: time="2024-05-16T11:09:12Z" level=info msg="Started API server (2/3)" host=127.0.0.1 port=9203
Setup cronjob for fetching device information
$ sudo crontab -e
and add the following line to the end of the file:
30 4 * * * /opt/insysicom-routermgmt/bin/insysicom-routermgmt system fetchDeviceInfo;
6. Setup NGINX web server
| We highly recommends to start with the following HTTP-only setup and check the proper operation of the router management application first, before you setup TLS. |
Install NGINX
$ sudo apt update $ sudo apt install nginx
Create a new NGINX server config
$ sudo vi /etc/nginx/sites-available/insysicom-routermgmt
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:9202;
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
$ sudo ln -s /etc/nginx/sites-available/insysicom-routermgmt /etc/nginx/sites-enabled/ $ sudo rm /etc/nginx/sites-enabled/default
Adjust the server settings
$ sudo vi /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
$ sudo nginx -t $ sudo systemctl restart nginx
7. Adjust system settings
You need to change some application settings, otherwise you cannot setup a router connection. The download of the router startup configuration will fail.
Start 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 |
8. Check if your setup is working properly
Change to the router list, register a new router, use dummy values and try to download the startup-configuration.
| If you cannot download the startup configuration your setup might be wrong. Please contact our support. Same if you even cannot register a new router. If you cannot access the web application, please check your network and/or firewall settings. |
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.
-----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 with the IP-address of your application server.
In case you’re using a FQDN the host parameter should contain the FQDN.
Finally check if the websocket is accessible. Otherwise your routers cannot connect to the router management application. Change to a different computer 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.
$ curl http://164.90.225.14:8080/devicecontrol handshake error: bad "Upgrade" header
If you receive the handshake error, 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
At this stage the router management application is ready to manage your routers in HTTP-only mode.
If your networking infrastructure is totally private or not accessible from outside or if your routers are connected by secured VPN tunnels, e.g. IPSec, to your corporate network, than there’s no need to setup additional TLS encryption and authentication. You can leave your current setup as it is.
Otherwise move forward and setup TLS as described.
10. Securing with TLS
Since router management is a full web-based application, you can vary between different ways to secure the application with TLS. In this installation guide we decided to use private certificates and split the application and the router connections (web sockets) thru different IP ports, using the same application server IP-address. See above HTTP-only NGINX configuration. The application is hosted on port 80 and the routers are connecting thru port 8080 to the backend. We will change the ports to 443 and 8443, because these ports are common if you run TLS authentication and encryption.
| In case you want to use public certificates or manage the router connections through a dedicated IP address or setting up NGINX DNS-based virtual hosts, contact us. |
10.1. Issuing the server certificate
| We do not support self-signed server certificates! |
Issue a server certificate that that matches your environment. The common name should equal the FQDN of your application server. In case you prefer an IP-address based connection add a IP SAN to your certificate. Our example includes both.
We use following certificate authority (the output is stripped to relevant content) to sign the server certificate.
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 result is the following server certificate (the output is stripped to relevant content) that we use in our upcoming configuration. We need the private key of this certificate, too.
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 you need 3 PEM files. * 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
The file ssl-params.conf can be adjusted by your security needs.
The following configuration is a sample that we’re running in our own cloud.
Since router management is a fully web-based application, it supports everything that is common in conjunction with web-based applications.
$ sudo vi /etc/nginx/snippets/ssl-params.conf
ssl_protocols TLSv1.2; 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, depending on your ssl-params.conf
$ openssl dhparam -out /etc/nginx/dhparam.pem 4096
Chain all the certificates in the order that NGINX expects.
$ 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
Configure the snippet that adds the certificate chain and the private key to your NGINX configuration.
$ sudo vi /etc/nginx/snippets/insysicom-routermgmt-ssl.conf
ssl_certificate /etc/nginx/ssl/insysicom-routermgmt.crt; ssl_certificate_key /etc/nginx/ssl/insysicom-routermgmt.key;
Finally add the SSL support to your NGINX configuration
$ sudo vi /etc/nginx/sites-available/insysicom-routermgmt
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_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:9202;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
We will check now if the NGINX SSL setup is working, before continuing our TLS configuration.
$ sudo nginx -t $ sudo systemctl restart nginx $ curl --cacert iRM_Install_Guide_Certificate_Services.crt https://164.90.225.14:8443/devicecontrol handshake error: bad "Upgrade" header
The parameter --cacert should point to the CA-chain PEM file, which was used to sign the server certificate.
Otherwise the curl command will fail, because it does not trust your private certificates.
Alternatively use the parameter -k.
See the man pages of the curl command.
|
You will see the handshake error again. Our router connection works as expected and is secured by TLS now.
Open the browser and navigate to http://myserver_or_ip_address
The router management user interface should appear. If your computer doesn’t trust your private certificate authority, your web browser will show an error. You can skip this error by continue surfing an untrusted site or add your certificate authority to your trusted certificate authorities.
10.3. Add TLS support to router management
Router management needs access to the new server certificate, too. Since NGINX already handles the TLS termination, we only have to upload the public TLS certificate, e.g. irmop1.icomcloud.net.crt.
To import the certificate go to your router management installation in the browser and navigate to Certificate Management → Certificates (http://myserver_or_ip_address/ui/certificates). Click on Browse, select your certificate file and provide a name (and a password if you have set one). After uploading, select the certificate, click on Use as server certificate in the right side bar and confirm the dialog.
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 ready to handle router connections through HTTPS.
Go to the router list and download the startup configuration again.
We’ve added a router for testing purposes in the previous section of the installation guide.
If you extract the tarball archive now and open again the file ConnectionProfile_xxx.txt, you should recognize a different configuration, that includes a client certificate and a client private key and several other commands.
| If the download of the startup configurations fails, you missed something during configuration. |
10.4. Add TLS client-authentication
If you register a new router in the router management application, a client certificate for the new router is generated automatically. This client certificate is included in the startup configuration of the router and will be installed on the router.
| We highly recommend to create a different certificate authority for client certificate signin instead of using the pre-installed CA. During the initialization process, router management will create a certificate authority automatically and assign this CA as default for client certificates. But this CA certificate includes various attributes that references properties of INSYS icom GmbH, especially the CRL distribution points. Before you add routers, create and change the signin CA for the client certificates. In this installation guide, we use our internal PKI to generate a new certificate authority. Alternatively you can use your own PKI, if exists, and upload a signin CA. Please contact us, if you wish to use your own PKI. |
| Never use HTTPS protocol for the CRL distribution endpoint. This can lead to download failures. Always use plain, unsecured HTTP. Since the CRL doesn’t includes sensitive information and is signed by the associated CA, no security concerns exists. |
Go to your router management installation in the browser and navigate to Certificate Management → Certificate Authorities (http://myserver_or_ip_address/ui/certificate-authorities). Click on Browse, select your CA (in this install guide called: your_client_authentication-ca.crt) and select New certificate authority with key (Format: PKCS#12). Provide a name (and a password if you have set one). Following the upload, select the CA and click on Configure client CA in the right side bar. Read the info boxes and confirm that you have fulfilled all described requirements. Since router management is using the default certificate authority, we have to introduce the new CA. Change to the router management user interface, delete all registered routers and then click on the top right wrench icon.
Go back to the empty router list and register again 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, you may set up something wrong. Feel free to contact us.
Change back to your console to setup 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 CA your_client_authentication-ca.crt uploaded before into our NGINX ssl folder.
$ sudo cp your_client_authentication-ca.crt /etc/nginx/ssl
Adjust the NGINX server configuration for the server on port 8443.
$ sudo vi /etc/nginx/sites-available/insysicom-routermgmt
server {
listen 8443 ssl;
...
ssl_client_certificate /etc/nginx/ssl/your_client_authentication-ca.crt;
ssl_verify_client on;
...
}
Check and enable the new NGINX configuration.
$ sudo nginx -t $ sudo systemctl restart nginx
Let’s try to connect against the web socket endpoint without a client certificate. This should lead to an error.
$ curl https://164.90.225.14:8443/devicecontrol <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>
Let’s try to connect against the web socket endpoint with a valid client certificate.
Go to the router management 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 includes two PEM blocks, a certificate and a private key.
Copy these PEM blocks (without the squared brackets) into separate files (client.crt and client.key) on your local PC.
We need these files for the following curl command.
$ curl --cert client.crt --key client.key --cacert iRM_Install_Guide_Certificate_Services.crt https://164.90.225.14:8443/devicecontrol handshake error: bad "Upgrade" header
If you receive the handshake error, the TLS client authentication is working.
10.5. Support for certificate revocation lists
You may remember our CRL distribution endpoint and if you spend a deeper look into our Swagger API documentation, you’ll recognize that our PKI even offers a CRL download. Please do not add CRL support into your current NGINX configuration!
In the current version of router management the included CRL is not usable by openssl or NGINX. In the upcoming release we’ll introduce extensive support for CRLs. During the upgrade we’ll enable the CRL distribution endpoint, too.
If your deleting a router in the router management, the router cannot establish a successful connection to the router management application, although the NGINX TLS client authentication was successful. Our application checks the existence of router and rejects the connection, if the router doesn’t exists or the client certificate is part of our internal CRL.
From a security perspective this is not the recommended solution, because the verification of a valid client certificate should happen completely on the TLS termination side, in our case NGINX. With the upcoming release of router management this minor security issue is fixed.
10.6. Forward client certificate to router management for further processing
| This setting has no effect with version 2022.09.0 of the router management application. During pen-tests we added this extra verification to the cloud version of router management. The upcoming on-premises release requires the following configuration, otherwise your routers my not download associated update-packets. |
$ sudo vi /etc/nginx/sites-available/insysicom-routermgmt
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.
$ sudo nginx -t $ sudo systemctl restart nginx
10.7. Notes for connecting a icom OS router
Since we’re using private certificates in our example, the icom OS router doesn’t trust the CA that signed our NGINX server certificate. Before applying the startup configuration on the router, you have to install the CA-certificates.
Change to the router user interface and go to (System) Administration → Certificates.
Upload the CA-certificate that you’ve used to sign the server certificate. In case you’re using a CA hierarchy start with the Root-CA and then add the Intermediate-CAs in the right order.
Now you’re ready to connect a router to the router management application. Ensure that your networking settings allows a connection from the router to the router management server. Test the connection with a ping. Therefore change to the menu Help → Debugging and release a ping to the IP-address or FQDN of your router management application server.
| Please ensure that you’ve configured NTP on your routers. Date and time must be set correctly to allow connections via certificates. |
Go to the router management user interface and register the icom OS router. Download the startup configuration and change back to the router user interface. Go to the menu (System) Administration → Up-/Download. Pick the startup configuration and click on the button Upload. The configuration is applied immediately. If everything is setup correctly, your router should connect router management and the connection status changes to online.
11. Installation approval
| The instllation is only considered as completed upon approval of our support team. You may download this checklist, which will be used for approval, for a prior check. |
Back to the Configuration Guides for icom Router Management
Back to overview