[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.
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.
[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.
[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.
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:
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.