Upgrading Suricata and Filebeat¶

IDSTower tells you when a newer Suricata or Filebeat version can be installed on a cluster, and upgrades the hosts in one operation. This page covers when an upgrade is offered, what it does to your sensors, and what to do when it fails.

Important

Upgrades need the Package Management capability. A cluster IDSTower installed is fully managed and always has it. On an onboarded cluster, turn it on from the Enabled Capabilities panel on the Summary tab, where you also pick the package source IDSTower installs from (see Management Capabilities). Without it, the upgrade dialog shows Package Management Not Enabled instead of an Upgrade button.

How IDSTower learns about a newer version¶

Official repository. Each host’s health heartbeat runs every minute and asks the host’s package manager (apt, dnf or yum) which Suricata and Filebeat versions its repositories offer. On apt hosts the heartbeat refreshes the package index once a day, between 00:00 and 00:05 host time, so a newly published release shows up after that refresh, or sooner if the index is refreshed on the host by other means; dnf and yum refresh their own metadata when it expires. On an onboarded cluster the heartbeat needs the Health Monitoring capability. IDSTower does not ask the hosts about new major versions: it offers the next major version it supports (Suricata 8 on a Suricata 7 cluster, for example) and checks whether the hosts can install it when you run the upgrade.

Built-In and User-Custom repositories. IDSTower lists the packages in the repository on the IDSTower server each time you open the cluster page, so a version you add (see Configuring the Built-In Packages repository and Configuring the User-Custom Packages repository) is offered the next time the page is opened. Minor and major upgrades both come from this list. A cluster whose packages are Pre-Installed is never offered an upgrade; record versions you install on it yourself with accept installed version (see Upgrades done outside IDSTower).

Where the offer appears¶

On the cluster’s Summary tab, under the Suricata or Filebeat status:

Notice	Meaning
Newer version is available, upgrade to Suricata 7.0.11	Official repository only. A newer release within the same major version; the version offered is the highest one any host reports.
Suricata 8.x is available, upgrade to Suricata 8.x	The next major version, from the cluster’s own repository type. One major version at a time: a cluster on Filebeat 7 is offered 8.x, and 9.x after that.
Newer version is available in the … repository	Built-In or User-Custom repository: it holds a newer version than the cluster’s. Not shown while a major upgrade is offered.

Running an upgrade¶

The link opens Upgrade Suricata to <version> (or Filebeat), listing every host in the cluster: the whole cluster is upgraded together. Check the version in the title before you click Upgrade. The dialog will not run while any of those hosts has configuration changes that are not applied yet, and names them. Apply the changes with Update Config in the Config Update Required banner at the top of the cluster page, then open the dialog again.

Mixed versions. By default every host must end on the same version: a specific version must be available on every host, and for a major upgrade (8.x) IDSTower picks the highest version all hosts can install. If there is none, the upgrade stops before installing anything and lists the versions each host offers. Tick Allow installing the latest available version per host when the hosts’ repositories cannot agree, typically in a mixed-OS cluster where each distribution packages a different latest version. Each host then installs the highest version its own repositories offer within the requested series: the same major version for 8.x, the same minor series for a specific version (8.0.* for 8.0.3). IDSTower records the highest installed version as the cluster’s version and each host’s own version against that host, so hosts that ended lower are afterwards shown as running a different version from the cluster’s. That is expected: their fix link would try to install the cluster’s version, which their repositories do not offer. The option only matters for the Official repository: the Built-In and User-Custom repositories install the same package everywhere.

What the upgrade does¶

Prepares the package source. For the Official repository, each host’s package manager is pointed at the repository for the target version, and the versions it offers are read. If this fails, IDSTower tries to restore the previous repository configuration and installs nothing. For the Built-In and User-Custom repositories, 8.x resolves to the latest 8 version they hold.
Installs the packages and checks the installed version on every host.
Returns the services to their recorded state. Instances recorded as running are restarted on the new binary and checked to have started; instances recorded as stopped are stopped, even if they were running when the upgrade began. Filebeat is stopped when all of the host’s Suricata instances are recorded as stopped, and started otherwise.
Records the new version for the cluster and each host, only if every step succeeded and the installed versions passed the checks (see When an upgrade fails).

The upgrade applies no configuration: nothing from the Configs tab is deployed, and each host keeps the configuration it has.

Note

On an onboarded cluster without the Service Control capability, step 3 is skipped: IDSTower starts, stops and restarts nothing, and running Suricata instances keep executing the old binary until you restart them yourself.

Major upgrades (for example Suricata 7 to 8) are the same operation. The configuration profile is not tied to a Suricata or Filebeat version, so the upgrade leaves it unchanged and does not ask for a profile upgrade; the new version starts with the configuration already on the hosts. On an onboarded cluster without Configuration Management that configuration is yours: check it against the new version’s upgrade notes first. An instance that cannot start with it is reported as not having come back up.

Fixing a single host¶

When a host runs a different version from the cluster’s, the Summary tab reports hosts “running unexpected version”, and the Hosts tab underlines that host’s version with a fix link. The link opens Change Suricata to <cluster version>; Change runs the same operation on that host alone and installs the cluster’s version, whether that is an upgrade or a downgrade, so that version must be available to the host. Apply any pending configuration changes on the host first with Refresh stale config (see Cluster Hosts Tab).

Upgrades done outside IDSTower¶

If Suricata or Filebeat is upgraded by other means, such as your own tooling or automatic OS updates, the hosts report the new version and IDSTower flags them. Once every host that reports a version reports the same one, the Summary tab offers accept installed version <version>, which records that version as the cluster’s expected version. It runs nothing on the hosts and does not need Package Management. Accept when the hosts run the version you want to keep; to put them back on the recorded version, use the fix links instead. Hosts report their version through the heartbeat, so on an onboarded cluster this needs Health Monitoring.

When an upgrade fails¶

The dialog shows a summary and each affected host: click a host to see the task that failed and its message. The cluster keeps its recorded version.

If the install failed on only some hosts, the others are already on the new packages, and their services may be stopped or still running the old version. Fix the failing hosts and run the upgrade again: it completes the rest and brings every host’s services back.

“… is not available on all hosts” or “No common … version matching …”: nothing was installed, because the hosts’ repositories do not offer one version all of them can install. The message lists what each host offers. Make the version available on those hosts, or tick Allow installing the latest available version per host. With that option ticked, the equivalent is “No … version matching prefix … is available on one or more hosts”.
Any other host error from the repository check (for example Suricata 8 on Ubuntu 20.04): nothing was installed, and IDSTower tried to restore the previous repository configuration.
“No Package found for … in the repository”: the Built-In or User-Custom repository on the IDSTower server has no package for that version.
“System is reporting unexpected version of Suricata …” (Filebeat: “… incorrect version of Filebeat …”) under a host: the package was installed, but the version the host reports afterwards is not the one requested. Check which version is installed on that host and what its repositories provide, then run the upgrade again.
“Suricata Service instance … did not start” or “Filebeat Service did not start …” under a host: the new packages are installed but the service did not come back up. Check the log shown with the error, fix the cause, then run the upgrade again to start it.

For a per-task record of every run, see Recording Ansible runs with ARA.