--- title: "Installing icom Router Management on Ubuntu" slug: "installing-icom-router-management-on-ubuntu" description: "Install icom Router Management on Ubuntu - follow step-by-step instructions for secure, compliant, and scalable on-premises router management." tags: ["icom Router Management", "Installation", "iRM", "On-Premises"] updated: 2025-11-11T15:35:52Z published: 2025-11-11T15:35:52Z canonical: "docs.insys-icom.com/installing-icom-router-management-on-ubuntu" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.insys-icom.com/llms.txt > Use this file to discover all available pages before exploring further. # Installing icom Router Management in Ubuntu > [!CAUTION] > Deprecated Installation! > > Starting with **icom Router Management On-Premises Version 2025.09.0b**, new installations with **binaries will no longer be supported**. We strongly recommend to perform a [**Docker-based installation**](/kb/docs/installing-icom-router-management-with-docker) to ensure compatibility and future updates. ## Preface This installation guide is based on Ubuntu 22.04 server. Commands may vary for other Linux distributions. > [!WARNING] > **icom Router Management (iRM) requires PostgreSQL version 14 or higher.** Please note that **PostgreSQL 14+ is not supported on Ubuntu 20.04 (Focal Fossa)**. > > If you're running Ubuntu 20.04, you will not be able to install or run the required database version for iRM. --- ## Supported Version This guide refers to the following versions: | Router management | 2025.03.0 | | --- | --- | | Autoupdate | 2025.03.0 | --- ## **System Requirements** ### Application Server Ubuntu ≥ 22.04 Server | 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 - Ubuntu ≥ 22.04 Server - 8 vCPUs - 16 GB RAM - 100 GB Storage --- ## Setting Up the PostgreSQL Database Install a PostgreSQL database server on the application server or on a dedicated database server: ```bash sudo apt update sudo apt install postgresql-14 -y ``` Then log in as the PostgreSQL user, start the `psql` command-line tool, and execute the SQL commands: ```bash sudo -u postgres psql ``` Now execute the following SQL commands to create the database and user: ```pgsql 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 ``` --- ### Additional Steps for a Dedicated PostgreSQL Server *(Optional Step)* > [!TIP] > Information > > A dedicated database server can offer advantages, especially in larger or security-critical environments — such as improved performance, load separation, and a clearer division of responsibilities within IT infrastructure. It also allows for more granular access control and network segmentation, contributing to overall security. > > However, operating a separate database server involves additional administrative overhead and infrastructure costs. For smaller installations or test environments, a dedicated server is not necessary — in such cases, the database can run on the same system as the iRM application. If the database runs on a separate server, **remote access must be enabled**. The path to the configuration files may vary depending on the PostgreSQL version (in this example: version 14). Open the `postgresql.conf` configuration file: ```bash sudo vi /etc/postgresql/14/main/postgresql.conf ``` Look for the following line: ```ini #listen_addresses = 'localhost' ``` Uncomment it and change the value to allow external access: ```ini listen_addresses = '*' ``` Save and close the file. Now edit the `pg_hba.conf` file to allow external connections: ```bash sudo vi /etc/postgresql/{db-psql-version}/main/pg_hba.conf ``` Replace the following entry: ```bash # IPv4 local connections: host    all             all             127.0.0.1/32            md5 ``` with: ```bash # IPv4 local connections: host    all             all             0.0.0.0/0               md5 ``` If a firewall is active, open the PostgreSQL port: ```bash sudo ufw allow 5432/tcp ``` Finally, restart the database service: ```bash sudo systemctl restart postgresql ``` --- ## Setup application server Create a directory in your home and copy the installation zip file `irm_linux_2025_03_0.zip` into this directory. Extract the content and remember the path. You need the router management executable for the next steps. ```bash mkdir dist unzip irm_linux_2025_03_0.zip -d dist ls -aFl dist ``` The list command should show the following files: - insysicom-routermgmt - insysicom-autoupdate - VERSIONS.txt. You should see the insysicom-routermgmt and insysicom-autoupdate binaries in the dist directory. Mark the new binaries as executable if the `ls` command did not show the executable flag indicated by `*` behind the file name. For the insysicom-routermgmt binary: ```bash sudo chmod +x dist/insysicom-routermgmt ``` For the insysicom-autoupdate binary: ```bash sudo chmod +x dist/insysicom-autoupdate ``` Create a service user and all required directories. Populate the directories with the configurations and application binaries. ```bash sudo mkdir /var/opt/insysicom-routermgmt 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 chown -R insysicom-routermgmt:insysicom-routermgmt /var/opt/insysicom-routermgmt ``` --- ### Setting Up the Application Server Create a directory in your home directory and copy the installation ZIP file `irm_linux_2025_03_0.zip` into this directory. Extract the contents and take note of the path. You will need the router management executable for the next steps. ```bash mkdir dist unzip irm_linux_2025_03_0.zip -d dist ls -aFl dist ``` The `ls` command should list the following files: - `insysicom-routermgmt` - `insysicom-autoupdate` - `VERSIONS.txt` You should see both `insysicom-routermgmt` and `insysicom-autoupdate` in the `dist` directory. Make the new binaries executable if the `ls` output does not indicate the executable flag `*` after the file name. For the `insysicom-routermgmt` binary: ```bash sudo chmod +x dist/insysicom-routermgmt ``` For the `insysicom-autoupdate` binary: ```bash sudo chmod +x dist/insysicom-autoupdate ``` Create a system user and all required directories. Then populate them with the application’s configuration files and binaries: ```bash sudo mkdir /var/opt/insysicom-routermgmt 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 chown -R insysicom-routermgmt:insysicom-routermgmt /var/opt/insysicom-routermgmt ``` --- ### Preparing Router Management for Installation The application will now be initialized for the first time. Switch to the previously created user `insysicom-routermgmt` and navigate to the `/opt/insysicom-routermgmt/etc` directory. The generated configuration file will later be placed there. The environment variables are required for the database connection. The initialization process prepares the database and then writes the configuration file to the current directory. This file contains central application settings. > [!NOTE] > Note > > If you are using a dedicated database server, adapt the value of `BARRACUDA_DATABASE_ARGS` to match the hostname or IP address of your database server, for example: `BARRACUDA_DATABASE_ARGS="... host=mydbserver port=5432 ..."` ```bash sudo -i -u insysicom-routermgmt cd /opt/insysicom-routermgmt/etc/ ``` ```bash 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 ``` Edit the configuration in the file `insysicom-routermgmt.conf` to allow communication between this service and the autoupdate service: ```bash vi /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf ``` Example content of `/opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf`: ```plaintext barracuda_admin_api_port: 9201 barracuda_admin_api_host: "127.0.0.1" barracuda_grpc_server_port: 50051 barracuda_grpc_server_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 ``` These settings ensure that the router management daemon is only accessible via localhost and avoids conflicts with standard IP ports. The application is secured by a front-facing NGINX web server. The `barracuda_data_path` must be adjusted since the initialization process adds a hidden `.barracuda` directory (not required on a dedicated application server). --- ### Preparing the Autoupdate Service To configure the autoupdate service, create an environment file in the same directory as the router management configuration file: ```bash vi /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env ``` Insert the following content: ```ini AUTOUPDATE_HTTP_PORT=8082 AUTOUPDATE_GRPC_PORT=50052 AUTOUPDATE_HTTP_READ_TIMEOUT=60s AUTOUPDATE_SHUTDOWN_TIMEOUT=10s FILE_STORAGE_TYPE=filesystem ``` Add additional required environment variables that are already defined in the router management configuration: ```bash 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 ``` Then execute the following command to prepare the database for the autoupdate service: ```bash set -a source /opt/insysicom-routermgmt/etc/insysicom-autoupdate.env set +a /opt/insysicom-routermgmt/bin/insysicom-autoupdate -migrate ``` The result should either be `Migration completed successfully` or `No pending migrations`, depending on the current state of the database. --- ### Creating systemd Services Switch back to your administrative user: ```bash exit ``` #### Create systemd service for Router Management ```bash sudo vi /etc/systemd/system/insysicom-routermgmt.service ``` **Note:** If PostgreSQL is not running on the same system, remove the line `After=postgresql.service` from the `[Unit]` section. ```ini [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 systemd service for Autoupdate ```bash sudo vi /etc/systemd/system/insysicom-autoupdate.service ``` > [!NOTE] > Note > > If PostgreSQL is not running on the same system, remove the line `After=postgresql.service` from the `[Unit]` section. ```ini [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-autoupdate [Install] WantedBy=multi-user.target ``` ### Start systemd Services ```bash sudo systemctl enable insysicom-routermgmt.service sudo systemctl start insysicom-routermgmt.service sudo systemctl enable insysicom-autoupdate.service sudo systemctl start insysicom-autoupdate.service ``` Verify service status (should show `active (running)` with green indicator): ```bash sudo systemctl status insysicom-routermgmt.service sudo systemctl status insysicom-autoupdate.service ``` ### Setup Cronjob to Fetch Device Information ```bash sudo crontab -e ``` Add the following lines at the end of the file: ```plaintext 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; ``` --- ### Configure NGINX Web Server > [!NOTE] > Note > > It is strongly recommended to start with the HTTP-only configuration to verify correct operation of the application before enabling TLS. #### Install NGINX ```bash sudo apt update sudo apt install nginx ``` #### Create new NGINX server config ```bash sudo vi /etc/nginx/sites-available/insysicom-routermgmt ``` ```nginx 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 NGINX Configuration ```bash sudo ln -s /etc/nginx/sites-available/insysicom-routermgmt /etc/nginx/sites-enabled/ sudo rm /etc/nginx/sites-enabled/default ``` #### Adjust Server Settings ```bash sudo vi /etc/nginx/nginx.conf ``` ```nginx ... worker_rlimit_nofile 40000; events {    worker_connections 20000;    # multi_accept on; } http {    ...    server_names_hash_bucket_size 64;    ... } ... ``` #### Validate and Restart Web Server ```bash sudo nginx -t sudo systemctl restart nginx ``` --- ### Adjust System Settings To enable router connections, system settings must be changed. Otherwise, the download of a router’s startup configuration will fail. Open your browser and navigate to the installed application: ```plaintext http://myserver_or_ip_address ``` Login using the default credentials (these can be changed later): ```plaintext Username: default Password: secret ``` Navigate to: ```plaintext System Administration ⇒ System settings ``` Update the following settings: | Name | Value | | --- | --- | | DEVICECONTROL_SERVER_CERT | NONE | | AUTOUPDATE_SERVER_CERT | NONE | | INVENTORY_CONNECTION_PROFILE_HOSTNAME | IP address or FQDN of your server | --- ### Configuration Verification Navigate to the router list, register a new router using dummy values, and attempt to download the startup configuration. > [!NOTE] > Note > > If registration or download fails, the application may not be properly configured. Check network/firewall settings or contact support. Extract the tarball and open `ConnectionProfile_xxx.txt`. Content should resemble: ```plaintext 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" 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) cli("administration.profiles.activate") ``` The `host` parameter must match your server’s IP or FQDN. ### Verify WebSocket Access On another machine, run: ```bash curl http://164.90.225.14:8080/devicecontrol ``` > [!NOTE] > Note > > If you receive `handshake error: bad "Upgrade" header`, the connection is working correctly. Otherwise, check network/firewall settings. ### HTTP-only Mode Operation The router management application is now ready for HTTP-only operation. TLS is **not necessary** if: - The network is fully private or inaccessible from outside - Routers are connected via secure VPN (e.g., IPSec) to the enterprise network Otherwise, TLS setup as outlined in the next section is recommended. ### TLS Protection Since iRM is a fully web-based application, TLS can be implemented in various ways. This guide uses **private certificates** and separates web and router connections via different IP ports on the same server IP. - Application (web interface): Port 80 - Router connections: Port 8080 - After enabling TLS: Port 443 (web) and 8443 (router) > [!NOTE] > Note > > If you wish to use public certificates, dedicated IP addresses, or DNS-based NGINX virtual hosts, please contact support. ### Issue a Server Certificate > [!WARNING] > ⚠️ **Warning** > > Self-signed certificates are not supported! A server certificate tailored to your environment is required. The Common Name (CN) must match the server's FQDN. For IP-based access, a Subject Alternative Name (SAN) with the IP address must also be included. Example certificate output (truncated): ```yaml 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 ``` --- ### Enable TLS Support in Router Management To enable TLS communication, router management needs access to the new server certificate. Since TLS termination is handled by NGINX, only the public certificate (e.g., `irmop1.icomcloud.net.crt`) must be uploaded. Steps: - Open the router management UI in a browser - Navigate to **Certificate Management ⇒ Certificates** - Upload the certificate (name and optional password required) - Select **Action ⇒ Use as server certificate** Then, go to **System Administration ⇒ System settings** and set: | Name | Value | | --- | --- | | INVENTORY_CONNECTION_PROFILE_PORT | 8443 | After these changes, router management will accept HTTPS connections. Test by downloading the startup configuration of a previously registered test router (e.g., `ConnectionProfile_xxx.txt`). It should now include a client certificate, private key, and additional parameters. > [!NOTE] > Note > > If the download fails, TLS configuration may be incomplete. --- ### Add TLS Client Authentication When a new router is registered, a client certificate is automatically generated and included in the startup configuration. > [!NOTE] > Note > > It is strongly recommended to create a dedicated certificate authority (CA) for signing client certificates. The default CA generated by iRM contains INSYS icom identifiers. Alternatively, you may upload your own CA from an existing PKI. Contact support for guidance on PKI integration. > [!WARNING] > Important > > Never use HTTPS as the CRL distribution endpoint — this may cause download errors. Use plain HTTP instead. CRLs are signed and do not contain sensitive data. Steps: - Navigate to **Certificate Management ⇒ Certificate Authorities** - Click **Upload**, select your CA file (e.g., `your_client_authentication-ca.crt`) - Choose **New certificate authority with key (Format: PKCS#12)** - Assign a name and password (if applicable) - After upload, select **Action ⇒ Configure client CA** - Confirm all prompts Then: - Delete all routers and register a new test router - The new client certificate will be signed by the uploaded CA If registration fails, verify your setup or contact support. --- ### Enable TLS Client Authentication in NGINX Download the new certificate authority in PEM format and copy it to the SSL directory: ```bash sudo cp your_client_authentication-ca.crt /etc/nginx/ssl ``` Update the NGINX configuration for port 8443: ```bash sudo vi /etc/nginx/sites-available/insysicom-routermgmt ``` ```nginx server {    listen 8443 ssl;    ...    ssl_client_certificate /etc/nginx/ssl/your_client_authentication-ca.crt;    ssl_verify_client on;    ... } ``` Test configuration and restart NGINX: ```bash sudo nginx -t sudo systemctl restart nginx ``` --- ### Verify WebSocket Endpoint Test without client certificate: ```bash curl https://164.90.225.14:8443/devicecontrol ``` > [!TIP] > Expected error > > Error page showing `400 No required SSL certificate was sent` Test with valid client certificate: ```bash curl --cert client.crt --key client.key --cacert iRM_Install_Guide_Certificate_Services.crt https://164.90.225.14:8443/devicecontrol ``` > [!NOTE] > Note > > If you receive `bad "Upgrade" header`, client authentication is working as expected. --- ### Forward Client Certificate to iRM To forward the client certificate to iRM, modify NGINX: ```bash sudo vi /etc/nginx/sites-available/insysicom-routermgmt ``` ```nginx 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;    } } ``` ```bash sudo nginx -t sudo systemctl restart nginx ``` --- ### Connecting an icom OS Router Because this guide uses private certificates, the icom OS router does not initially trust the CA. Therefore: - Upload CA certificates manually via **Administration ⇒ Certificates** - Respect CA chain order: Root CA first, then intermediates Test connection: - Open **Administration ⇒ Debugging** in the router UI - Ping the iRM server's IP or FQDN Then: - Register the router in iRM - Upload the startup configuration via **Administration ⇒ icom Router Management** If everything is configured correctly, the router will connect and show status as "online". --- ### Installation Completion > [!WARNING] > Attention > > Installation is only considered complete after support team approval. A [post-installation checklist](https://public.centerdevice.de/89c6314b-9f42-44c6-942f-0761679db131) is available for final verification.