Preface
This installation guide is based on Red Hat Enterprise Linux 9. Commands may vary for other Linux distributions. A recent and systemd-based Linux is highly recommended.
Supported Version
This guide refers to the following versions:
Router management | 2025.03.0 |
Autoupdate | 2025.03.0 |
System Requirements
Application Server Red Hat Enterprise Linux 9
Requirements | 1 - 1.500 Routers | 1.500 - 3.000 Routers |
---|---|---|
CPU | 8 vCPUs | 16 vCPUs |
RAM | 16 GB | 32 GB |
Storage | 100 GB HDD | 200 GB HDD |
Optional: Dedicated Database Server for Larger Environments
Red Hat Enterprise Linux 9 (preferred)
8 vCPUs
16 GB RAM
100 GB HDD
Install needed packages
Install the following packages, that will be needed in later steps of this guide:
Setup PostgreSQL Database
Install a Postgres database server (PostgreSQL 14) onto your application server or dedicated database server.
Install the repository RPM.
Disable the built-in PostgreSQL module
Install PostgreSQL
Optionally initialize the database and enable automatic start
Login to your postgres user, run psql CLI tool and execute the SQL commands.
When logged in, run the following queries to create the database and user.
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.
Look for this line in the file:
Uncomment, and change the value to *; this will allow Postgres' connections from anyone.
Save and exit the file. Next, modify pg_hba.conf
to also allow connections from everyone.
Modify this section:
To this:
Please note!
In case of an active firewall, ensure port 5432 is opened.
Restart the database service.
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.
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.
The list command should show the following files:
insysicom-routermgmt
insysicom-autoupdate
irm_linux_2024_10_0.zip
Create a service user and all required directories. Populate the directories with the configurations and application binaries.
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.
Please note!
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 …"
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.
/opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf
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.
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.
Add the following content:
Settings, that already exist in the routermanagement configuration file, are added to the environment file.
Execute the following command to prepare the database for the autoupdate service.
The result should be Migration completed successfully
or No pending migrations
, depending on the current state of the database.
Create the systemd services
Switch back to your administrative user.
Create a systemd service for the routermanagement.
Please note!
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
Create a systemd service for the autoupdate.
Please note!
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
Create a systemd timer for the icom Router Management
and add the following lines to the file:
Create a systemd service for the icom Router Management
and add the following lines to the file:
Start the systemd services
Check if the systemd services are running. The status should be active (running)
and the indicator should be lit green.
Setup NGINX web server
Please note!
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.
Create a new NGINX server config
*/etc/nginx/conf.d/insysicom-routermgmt.conf
Warning!
Since SELinux reserves special ports, we need to use port 8081 for the inventory connection. Please ensure that this port is available.
Adjust the server settings
/etc/nginx/nginx.conf
Validate the config and restart the webserver
SELinux configuration
Red Hat Enterprise Linux uses Security-Enhanced Linux (SELinux) to enforce security policies. The following commands allow NGINX to connect to the router management backend processes.
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).
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 |
INVENTORY_CONNECTION_PROFILE_PORT | 8081 |
Fully Qualified Domain Name (FQDN)
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.
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 8081 matches our current NGINX configuration.
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.
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.
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 8081.
The ports will be changed to 443 and 8443, as these are commonly used for TLS authentication and encryption.
Please note!
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.
Issuing the server certificate
Warning!
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
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
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)
Setup NGINX SSL
Please note!
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.
/etc/nginx/snippets/ssl-params.conf
Create Diffie-Hellman (DH) parameters based on the configurations specified in ssl-params.conf
.
The certificates must be chained in the order expected by NGINX.
The snippet should be configured to add the certificate chain and the private key to the NGINX configuration.
/etc/nginx/snippets/insysicom-routermgmt-ssl.conf
Finally, SSL support should be added to the NGINX configuration.
/etc/nginx/sites-available/insysicom-routermgmt
The NGINX SSL setup should now be checked to ensure it is functioning correctly before proceeding with the TLS configuration.
The expected response is a handshake error: bad "Upgrade" header
.
Please note!
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.
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.
Please note!
If the download of the startup configurations fails, it indicates that something was missed during the configuration process.
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.
Please note!
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.
Please note!
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.
Adjust the NGINX server configuration for the server running on port 8443.
/etc/nginx/sites-available/insysicom-routermgmt
Verify and enable the new NGINX configuration.
Attempt to connect to the web socket endpoint without a client certificate.
This should result in an error.
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.
If you receive a handshake error: bad "Upgrade" header
, the TLS client authentication is working.
Forward client certificate to router management for further processing
The following configuration is required for your routers to download associated update-packets.
/etc/nginx/sites-available/insysicom-routermgmt
Check and enable the new NGINX configuration.
Notes for connecting an 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.
Please note!
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.
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.