Installing iRM on Ubuntu

  • Updated on Apr 17, 2025
  • Published on Jun 19, 2024

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.

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

  • 8 vCPUs

  • 16 GB RAM

  • 100 GB Storage

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:

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:

sudo -u postgres psql

Now execute the following SQL commands to create the database and user:

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)

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:

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

Look for the following line:

#listen_addresses = 'localhost'

Uncomment it and change the value to allow external access:

listen_addresses = '*'

Save and close the file. Now edit the pg_hba.conf file to allow external connections:

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

Replace the following entry:

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

with:

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

If a firewall is active, open the PostgreSQL port:

sudo ufw allow 5432/tcp

Finally, restart the database service:

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.

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:

sudo chmod +x dist/insysicom-routermgmt

For the insysicom-autoupdate binary:

sudo chmod +x dist/insysicom-autoupdate

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

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.

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:

sudo chmod +x dist/insysicom-routermgmt

For the insysicom-autoupdate binary:

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:

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

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 ..."

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

Edit the configuration in the file insysicom-routermgmt.conf to allow communication between this service and the autoupdate service:

vi /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf

Example content of /opt/insysicom-routermgmt/etc/insysicom-routermgmt.conf:

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:

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

Insert the following content:

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:

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:

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:

exit

Create systemd service for Router Management

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.

[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

sudo vi /etc/systemd/system/insysicom-autoupdate.service

Note

If PostgreSQL is not running on the same system, remove the line After=postgresql.service from the [Unit] section.

[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

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):

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

Setup Cronjob to Fetch Device Information

sudo crontab -e

Add the following lines at the end of the file:

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

It is strongly recommended to start with the HTTP-only configuration to verify correct operation of the application before enabling TLS.

Install NGINX

sudo apt update
sudo apt install nginx

Create 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: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

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

Adjust 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 and Restart Web Server

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:

http://myserver_or_ip_address

Login using the default credentials (these can be changed later):

Username: default
Password: secret

Navigate to:

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

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:

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:

curl http://164.90.225.14:8080/devicecontrol

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

If you wish to use public certificates, dedicated IP addresses, or DNS-based NGINX virtual hosts, please contact support.

Issue a Server Certificate

⚠️ 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):

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

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

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.

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:

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

Update the NGINX configuration for 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;
    ...
}

Test configuration and restart NGINX:

sudo nginx -t
sudo systemctl restart nginx

Verify WebSocket Endpoint

Test without client certificate:

curl https://164.90.225.14:8443/devicecontrol

Expected error

Error page showing 400 No required SSL certificate was sent

Test with valid client certificate:

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

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:

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;
    }
}
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

Attention

Installation is only considered complete after support team approval. A post-installation checklist is available for final verification.