SUSE SolidDriver Compliance Definition
Compatibility
Module package does not break SUSE Linux Enterprise installations
The installation of the kernel module must not do any of the following:
- Replace OS system files.
- Update or replace system or user configuration files without informing the user.
- Delete any pre-existing files without informing the user.
The most common case of replacing system files is the practice of installing an updated driver by overwriting the kernel module binary files installed by the base kernel package. For example, installing an updated Intel gigabit NIC driver by overwriting the file
/lib/modules/<kver>-<kflav>/kernel/drivers/net/e1000e/e1000e.kobreaks SolidDriver compliance for the following two reasons:
Since the original e1000e.ko file is installed using an RPM package, it’s existence is tracked in the RPM database which is used by the SUSE package management system. Overwriting the file breaks the integrity of this database which in turn breaks the integrity of the SUSE Linux Enterprise installation itself. This must be avoided.
Overwriting the kernel file creates a collision in the kernel files space. When the kernel package is re-installed it will again overwrite the file, or when a kernel update is to be installed, the existing kernel file structure will be removed and no longer be valid, resulting in the new kernel not loading any module that has been placed in that path. Both scenarios of re-installing, or updating the kernel can cause the undesirable effect of silently downgrading or removing the driver and potentially lead to a non-functional system.
The SUSE SolidDriver Program has defined a packaging standard that allows updated kernel modules to be installed along side the standard SUSE Linux Enterprise kernels without the need for overwriting the standard kernel files, and allowing for compatibility with kernel package updates. See the Kernel Module Package Manuals1 for further information.
When it is necessary to update system files (i.e. system configuration files) during the installation of a kernel module, any automatic changes shall be made clear to the user before installation of the update with instructions on how to restore the files to the previous state. This can be achieved through standard documentation or README files provided with the update package.
A proper use case for deleting system or user files by a kernel module update is hard to imagine and probably should be avoided. If absolutely necessary, the deletion shall be clearly identified in user documentation along with instructions on how to restore the files.
SUSE Linux Enterprise kernel updates do not silently break module functionality
The customer shall be able to install official updates to the SUSE Linux Enterprise kernel as provided by SUSE without danger of silently breaking a previously installed kernel module. The kernel and kernel modules consist of complicated code with extensive ABIs and other interdependencies. While it is not feasible to guarantee that every SUSE kernel update will not break functionality of every kernel module, there are a few things that can be done to protect users from the common issues.
Installing kernel modules in parallel with the official kernel package.
Keeping the kernel ABI compatible with SUSE kernel updates.
Inform the user in the case of incompatibility between currently installed kernel modules, and a kernel update about to be installed
Inform the user when trying to install a kernel module that is not compatible with the currently installed kernel package.
With regard to item 1) it was illustrated in the previous section that installing the updated kernel module by overwriting the original module will most likely cause breakage when updating the kernel package. Item 2) is a SUSE task and by policy SUSE maintains the kernel ABI compatibility with kernel updates whenever possible. SUSE has a history of being very successful at keeping the kABI compatible with kernel updates, but regardless, SUSE is realistic and admits that compatibility can’t be 100% guaranteed. That is where items 3) and 4) come into play.
Items 3) and 4) are covered by using the Kernel Module Package standard when creating packages that deliver updates to kernel modules. The KMP standard leverages the RPM package dependency mechanisms to establish compatibility between kernels and kernel module packages at the kernel ABI level. This allows for the standard package management tools to trigger dependency conflicts when a user attempts to install a kernel update that is incompatible with previously installed KMPs or vice versa. This protects the user from unknowingly putting the system in a broken or degraded state.
Stick to standard kernel APIs meant for kernel modules
For ensured compatibility and runtime integrity of the SUSE kernel, kernel module shall:
- Only use standard kernel API available to modules. That is:
- EXPORT_SYMBOL()
- EXPORT_SYMBOL_GPL()
- kernel headers
- Not alter security structures and settings internal to the kernel
- Not alter code paths outside of specific kernel modules
Sticking to official kernel APIs for interfacing with the kernel ensures compatiblity across SUSE kernel updates that maintain the kernel ABI.
Modifying internal kernel structures or code paths otherwise (e.g. modifying the kernel syscall table) can both destabalize the kernel as well as break live patching functionality rendering the system unsupported by SUSE.