Compatibility Policy

Update

[update.path] Upgrading between major versions is only guaranteed from the latest minor version. pdating a minor version may be done with gaps.

Example. There are: v12.34.0, v12.34.1, v12.34.2, v12.35.0, v12.35.1.

  • Guaranteed:
    • v12.34.2 → v12.35.0,
    • v12.34.2 → v12.35.1,
    • v12.34.0 → v12.34.2.
  • Not guaranteed:
    • v12.34.0 → v12.35.x,
    • v12.34.1 → v12.35.x.

Non-guaranteed updates are usually technically possible but not tested.

[update.migration] If the format of the settings changes during the update, they are guaranteed to be 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

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

[api.changelog] 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

[detect.migration] 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 an object file relies on an application binary interface (ABI) to work. The required ABI version is specified through the section name in the object file, in the code this is done through a macro (FILTER_V1 specifies ABI version 1). Since the program code may not be available when updating, the ABI version is unbound from the system version. ABI does not change without objective reasons (security issues, fundamentally new features). ABI versions are incompatible with each other.

The ABI changes include everything that could cause a program to work incorrectly with a formally correct binary:

  • Removal of functions, including renaming.
  • Function signature change.
  • Adding possible function return values.
  • Changing the description of API data types.
  • Changing the behavior of functions with existing parameters (not always).

Replacing reserved fields of a structure or function parameters with meaningful ones while maintaining the structure size or parameter format does not change the ABI.

[bpf.abi.compat] Programs for a specific version of the ABI run on any version of the system where that version of the ABI is supported.

Example: If v12.34.0, v12.34.1, v12.35.0 support ABI v1, then program for ABI v1 works the same on any of these versions.

[bpf.abi.deprecation] Support for ABI versions is removed only when new major versions are released.

Example: ABI v1 running in v12.34.0 cannot be removed in v12.34.1, only in v12.35.0.