Compatibility Policy

Upgrade Path

A successful upgrade to the next major versions is only guaranteed from the latest minor version of the currently installed major version.

Minor versions within a major version may be skipped during an upgrade.

Example. Given available versions: v12.34.0, v12.34.1, v12.34.2, v12.35.0, v12.35.1.

  • Guaranteed:

    • v12.34.2 → v12.35.0 (minor version .2 is the latest of v12.34)
    • v12.34.2 → v12.35.1 (see above, v12.35.0 can be skipped)
    • v12.34.0 → v12.34.2 (v12.34.1 can be skipped)

  • Not guaranteed:

    • v12.34.0 → v12.35.x (minor version .0 is not the latest of v12.34)
    • v12.34.1 → v12.35.x (see above)

When settings format changes during the update, the settings are migrated to the new format with the preservation of meaning, if the corresponding logic is preserved.

Example. Up until v20.02, the MCR key was specified as base64 in the API and as text in the UI. Since v20.06, the key is given as a hex string. When updating, the bytes of existing keys are converted to the new format.

Example: see «Autodetection thresholds» section.

Backend API

Within the major version, a backward compatible request format is guaranteed.

Incompatible changes are described in the changelog.

Example: all queries for v12.34.0 also work with v12.34.1.

Example: some queries for v12.34.2 may not work in v12.35.0, changes are described in «Changelog v12.35.0» section.

Autodetection Thresholds

If the threshold names change in the new version, it is guaranteed that the values of the old thresholds will be migrated to the new thresholds on update, unless the old logic is removed.

Example. In version v12.34 there was a Threshold threshold, upon crossing which the countermeasure was turned on or off, it was set to 100. In version v12.35, the countermeasure is enabled by the Threshold.On threshold, and disabled by Threshold.Off. When updating, the Threshold threshold will be removed, instead Threshold.Off and Threshold.On will be created with the same values of 100.

BPF Programs

Binary code in object files works via the application binary interface (ABI). ABI change may prevent existing object files from loading or may lead to program malfunction.

ABI is only changed on major version releases. ABI change is announced in the changelog.

Source code in C language uses API in mitigator_bpf.h. API change may break compilation of existing source code, although already compiled object code will continue to load and function.

API changes affecting existing programs are only released with major versions.

Example. Version v21.04 introduced IPv6 support for BPF, some data types were changed. ABI version was bumped, so previously compiled programs stopped loading. API also changed, so existing code required fixes. The changes had been announced in the changelog.