Upgrade Guide from v3.0.2 to v3.1.0

This guide explains how to upgrade from IDSTower v3.0.2 to v3.1.0, to upgrade please follow the below steps.

Note

What this upgrade changes

  • Database schema: v3.1.0 includes a database schema change. It is applied automatically the first time the upgraded service starts — no action is required. If you prefer to apply it yourself, see Applying the database schema upgrade manually below.

  • Configuration profiles: Suricata configuration profiles need to be upgraded after this release (Filebeat profiles are unchanged). This is a post-upgrade step you perform from the web interface — see step 8.

  • Host configuration: once the profiles are upgraded, the configuration on your Suricata hosts is stale and needs to be redeployed — see step 9.

  1. Stop your IDSTower service

$ sudo systemctl stop idstower.service

  1. Take a full backup of your current IDSTower database

$ sudo mysqldump -B [DatabaseName] -u [DatabaseUsername] -p > IDSTower_backup_`date +%F_%H_%M_%S`.sql

.. note::
   Replace `[DatabaseName]` and `[DatabaseUsername]` with your actual database name and username, you can find these details in your IDSTower configuration file located at `/opt/idstower/appsettings.json`

  1. Take a backup of your IDSTower directory (including settings)

$ sudo cp -Rp /opt/idstower /opt/idstower_3.0.2_backup_`date +%F_%H_%M_%S`

  1. Upgrade IDSTower to Version 3.1.0.

on CentOS/RHEL/RockyLinux/AlmaLinux/OracleLinux:

$ sudo yum update idstower-3.1.0-1

on Ubuntu/Debian:

$ sudo apt update
$ sudo apt install idstower=3.1.0-1

  1. Start the IDSTower service.

$ sudo systemctl daemon-reload
$ sudo systemctl start idstower.service

  1. Verify IDSTower service has started correctly and database schema has been migrated

$ sudo systemctl status idstower.service

  1. Login to the IDSTower web interface and confirm the version shown is 3.1.0.

Post-Upgrade Steps

8. Upgrade your Suricata configuration profiles

Open each cluster in the web interface. Clusters whose Suricata configuration profile needs upgrading show a Profile Upgrade Required banner at the top of the cluster page:

  1. Navigate to Clusters and open the cluster

  2. Click the Upgrade button on the Profile Upgrade Required banner

  3. Review the changes and confirm the upgrade

Note

In v3.1.0 the Suricata network and port variables (HOME_NET, EXTERNAL_NET, the *_SERVERS groups and the port groups) are stored as plain comma-separated values, and the grouping brackets [ ] that Suricata uses for lists live in the configuration template instead of being baked into each value. Upgrading the profile moves any brackets stored in your values into the template automatically, so your customizations are preserved. Until the profile is upgraded, the cluster keeps working exactly as it did on v3.0.2.

Filebeat configuration profiles are unchanged in this release and need no action.

9. Deploy the updated configuration to your Suricata hosts

Upgrading the configuration profile marks the hosts using it as having a stale configuration. Once step 8 is complete, a Restart Required banner appears at the top of the cluster page, telling you how many hosts need a service restart to apply the config changes:

  1. Click Restart on the banner

  2. Review the list of hosts in the confirmation dialog and click Update Config

  3. Wait for the deployment to complete on all hosts

Note

The Restart Required banner is hidden while a configuration profile still needs upgrading, so it only becomes visible after step 8 — if you do not see it yet, complete step 8 first.

10. Verify cluster status

  1. Navigate to Cluster → Summary

  2. Verify all hosts show as connected and their Suricata services are running

  3. Verify that rules and IOCs are still being deployed correctly

Applying the database schema upgrade manually

This section is optional — it is only for installations where the database user IDSTower runs as is not permitted to change the schema, or where schema changes must be applied by a DBA. Everyone else should skip it: step 5 applies the schema automatically.

The schema upgrade script for this release is published at:

https://download.idstower.com/packages/3.1.0/sql_scripts/IDSTower_upgrade_database_schema_from_3.0.x_to_3.1.0.idempotent.sql

Apply it against your IDSTower database between step 4 and step 5:

$ sudo mysql -u [DatabaseUsername] -p [DatabaseName] < IDSTower_upgrade_database_schema_from_3.0.x_to_3.1.0.idempotent.sql

The script is idempotent — re-applying it is safe.

Important

After a manual schema upgrade you must still start IDSTower and let it finish.

An IDSTower upgrade has two parts: the schema change above, and a data-migration step that adapts your existing data to the new schema. The script performs only the first part, and deliberately does not record the new schema version. Your database will still report 3.0.0 until the service has started and completed the data migration — that is expected, and it is what causes the outstanding step to run.

Do not insert the version row into database_version_history by hand: doing so tells IDSTower the upgrade is complete and the data migration will never run.

Once the service has started successfully, you can confirm the upgrade finished with:

$ sudo mysql -u [DatabaseUsername] -p -e "SELECT * FROM [DatabaseName].database_version_history;"

The most recent row should read 3.1.0.

  1. done.