Upgrade Guide from v2.9.x to v3.0.0

This guide explains how to upgrade from IDSTower v2.9.x to v3.0.0. This is a major release with significant architectural changes, please read the entire guide carefully before proceeding.

Warning

Important Pre-Upgrade Requirements:

  • Operating System Check: Ubuntu 18.04, Ubuntu 20.04, and Debian 11 (Bullseye) are no longer supported in v3.0.0. You must upgrade your operating system to a supported version before upgrading IDSTower:

    • Ubuntu 22.04 (Jammy Jellyfish) or later

    • Debian 12 (Bookworm) or later

    • AlmaLinux 8/9/10

    • Rocky Linux 8/9/10

    • Oracle Linux 8/9/10

    • CentOS Stream 9

  • Multi-Instance Architecture: This release introduces a major architectural change. The migration process will automatically convert hosts from single-instance to multi-instance architecture.

  • Backup Required: Always backup your database and configuration before upgrading.

Pre-Upgrade Steps

1. Verify Operating System Compatibility

Before upgrading, verify that all your IDSTower and Suricata hosts are running a supported operating system. If any hosts are running Ubuntu 18.04, Ubuntu 20.04, or Debian 11, you must upgrade them first.

To check your OS version:

$ cat /etc/os-release

2. Stop your IDSTower service

$ sudo systemctl stop idstower.service

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

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

$ sudo cp -Rp /opt/idstower /opt/idstower_2.9.x_backup_`date +%F_%H_%M_%S`

Upgrade Steps

5. Upgrade IDSTower to Version 3.0.0

on CentOS/RHEL/RockyLinux/AlmaLinux/OracleLinux:

$ sudo yum update idstower-3.0.0-1

on Ubuntu/Debian:

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

6. Start the IDSTower service

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

7. Verify IDSTower service has started correctly

$ sudo systemctl status idstower.service

Check the logs for any migration messages:

$ sudo journalctl -u idstower.service -f

Post-Upgrade Steps

8. Upgrade Configuration Profiles

After the upgrade, IDSTower will display warning banners for configuration profiles that need to be upgraded. Follow these steps:

  1. Login to the IDSTower web interface

  2. You will see warning banners on profiles requiring attention

  3. Click the Upgrade button on each banner to upgrade the configuration profile

  4. Review and confirm the upgrade

Note

Configuration profiles need to be upgraded to support the new multi-instance architecture and Suricata 8/Filebeat 9 compatibility.

9. Update ET Open Ruleset URL (If Applicable)

If you are using the Emerging Threats Open Ruleset, update your feed URL to use the Suricata 7 version:

  1. Navigate to Settings → Feeds → IDS Rules Feeds

  2. Edit your Emerging Threats Open feed

  3. Update the URL to: https://rules.emergingthreats.net/open/suricata-7/emerging-all.rules.tar.gz

  4. Save the changes

Note

The ET Open ruleset has been updated to version 7. Older installations using the previous URL should update to ensure compatibility with the latest rules format.

10. Deploy Configuration to Suricata Hosts

After upgrading configuration profiles, deploy the updated configuration to all hosts:

  1. Navigate to Cluster → Hosts

  2. Select Host Actions → All Hosts → Refresh stale config

  3. Wait for the deployment to complete on all hosts

The migration process will automatically:

  • Convert single-instance hosts to multi-instance architecture

  • Update service configurations for the new architecture

  • Preserve your existing rules and IOCs settings

11. Verify Cluster Status

After deployment, verify that all clusters are operating correctly:

  1. Navigate to Cluster → Summary

  2. Verify all hosts show as connected

  3. Check that Suricata services are running on all hosts

  4. Verify that rules and IOCs are being deployed correctly

What’s New in v3.0.0

  • Multi-Instance Architecture (Enterprise): Hosts can now run multiple Suricata instances with isolated configurations

  • IDS Rules Deployment Templates: Configurable template-based system for managing IDS rule deployments

  • Enhanced Editor Features: Display formatting, syntax highlighting, auto-completion and built-in docs for IDS Rules and configuration files

  • Suricata 8 Support: Full compatibility with Suricata version 8.x

  • Filebeat 9 Support: Full integration with Filebeat 9.x

  • Feed Pagination Support: TAXII and MISP API feeds now support pagination

  • New OS Support: AlmaLinux 10, Rocky Linux 10, Oracle Linux 10, Ubuntu 25.04, and Debian 13 (Trixie)

  • Critical Disk Usage Protection: Automatic log file management when disk usage reaches 90%

  • Improved Rule Sync: Rules source code is now kept in sync with the latest version from feeds

For a complete list of changes, please refer to the Changelog.

Your IDSTower installation has been successfully upgraded to v3.0.0. If you encounter any issues, please contact support at support@idstower.com.