openSUSE:Packaging Requirements for Atomic and Image Update

This document describes the requirements for packages to comply with transactional-update, systemd-sysext and in general with openSUSEs snapshot and rollback functionality.

Updates with transactional-update are atomic, which means, either the update is fully applied without any error, or no change is made to the system. Additionally such kind of updates should not influence the currently running processes. If the update fails, it is not visible to the system that there was the try of an update, so no visible changes are done and the snapshot with the broken update gets removed. The update and all changes are only visible after the next reboot and you can always reboot to an older snapshot to do a rollback of the changes done by the update. systemd-sysext adds images with additional software (sysext-system extensions) to the running system, which are immediately visible without reboot. They temporary modify the running system until the next reboot.

In all cases, packages in RPM format are the starting point. These are either installed directly in the system, or OCI images, filesystem images or systemd-sysext images are created from them, which are then used to install or update the system.

Definitions

• Images: if images is used in this document, this are not full disk raw images but the content of a partition. E.g. an image could contain only the content of /usr if /usr is an own partition or btrfs subvolume. The format could be a raw partition, an OCI container, a tar archive, or something similar. Images are normally build out of the RPM pool.
• hermetic-usr: the OS resources (code, data files, …) should be hermetic in an immutable /usr. This means that a /usr tree should carry everything needed to set up the minimal set of directories and files outside of /usr to make the system work. This /usr tree can then be mounted read-only into the writable root file system that then will eventually carry the local configuration, state and user data in /etc , /var and /home as usual. See Fitting Everything Together for all details and background
• hermetic OS is comprehensively defined within /usr: combine the /usr tree with an empty, otherwise unpopulated root file system, and it will boot up successfully, automatically adding the strictly necessary files and resources that are necessary to boot up.

Requirements

For transactional-update, there are two ways to install the system and updates:

1. Via RPMs
2. Via OCI container (images)

The requirements for OCI images are much stricter than for RPMs: RPMs can have %pre/%post scripts. This have limited functionality compared to be installed/updated on Tumbleweed or plain SLES, but can do some changes inside of the snapshot. Images (e.g. OCI, but not limited to this) don't have any %pre/%post scripts. The scripts of the RPMs are run in the build environment when building the image, not on the final system. So modifying configuration files of the old image is not possible at all. Checking the hardware for special features is useless, as the final system will run on different hardware.

Configuration file handling should follow the Configuration File Specification.

User data and applications

User data and applications need to be strictly separated. User data should be in another subvolume than the main root subvolume with the application. Applications should always be in the main root subvolume and not in other subvolumes. Using /srv is a real problem in this regard: it contains applications, user data and configuration files mixed up. For this reason, it should only be used by ISVs and third party vendors, but not by the distributor.

Requirements for RPMs to be compatible with transactional-update

• All files must be stored inside the snapshot, which is in our case /etc and /usr, not /var, /opt, /srv, /usr/local or anything else.
• (Re)starting daemons is not possible.
• Modifying files outside of /usr and /etc is not possible.
• Following the Configuration File Specification is optional, but preferred, as this also solves several update problems of configuration files (see openSUSE:Packaging UsrEtc)
• Modifications outside the snapshot have to be done via systemd-tmpfiles and systemd services.
• Software is not allowed to modify files in the read-only part of the system at any time.

Requirements for Image based updates

• Same rules like for RPMs
• There are no %pre/%post scripts for update, they run only in the build environment when building the image.
• The package content is limited to /usr (which does not include /usr/local), for systemd-sysext /opt can be used, too.
• Following the Configuration File SpecificationConfiguration Files Specification is mandatory or installing/adjusting configuration files has to be done via hacks from systemd services.
• New system users and groups can only be created at next boot, all files should be owned by root:root.

Since systemd-sysext uses images, the stricter rules for image based apply (hermetic-usr) without any exception.

Perfect Packages

Perfect packages for transactional-update and for building images are RPMs which follow hermetic-usr, have no %pre/%post or similar scripts and all files are owned by root:root. System users and groups are only needed at runtime or to store data after first start, so that it is sufficient if the users, groups and directories/files outside /usr are only created with the next reboot via sysusers.d and tmpfiles.d configuration files.

While many packages follow already the hermetic-usr principle, having no %pre/%post scripts makes many RPMs unusable for consumption by openSUSE Tumbleweed or SUSE Linux Enterprise Server, so traditional Linux distributions. Here the possibility to restart systemd services, create system users and execute systemd-tmpfiles during package installation is necessary. For this the standard RPM macros for systemd should be used, from where we know that they work with transactional-update.

Testing for conformance

• Check the RPM file list, everything must be in /usr (and /etc)
• Install RPM, check which files got accessed from %pre/%post scripts

Possible solutions

Files and directories in /var

RPMs should not package files in /var, as these files cannot be created, updated or deleted during installation, update or removal of that package. A better solution is to use systemd-tmpfiles to create these files:

• Store the files in a directory below /usr/share or /usr/lib
• Create a /usr/lib/tmpfiles.d/<package>.conf file which copies or links the file to /var

An example (taken from ypserv) could look like:

ypserv.conf:

  d /var/yp 0755 - - -
  L /var/yp/Makefile - - - - ../../usr/lib/yp/ypMakefile
  L /var/yp/securenets - - - - ../../usr/lib/yp/securenets.example

ypserv.spec:

  %post
  %tmpfiles_create ypserv.conf

For more information, read the documentation for the tmpfiles configuration file format

pam-config and /etc/pam.d

pam-config is called by several RPMs in the %post script to add PAM modules to the PAM config. This is not possible in the image case, a possible solution could look like:

• Move /etc/pam.d to /usr/share/factory/pam.d
• Create a /usr/share/tmpfiles.d/pam.d.conf file:

pam.d.conf:

   L /etc/pam.d

This will create a symlink /etc/pam.d to /usr/share/factory/pam.d via systemd-tmpfiles.

fillup and /etc/sysconfig

There are two possible solutions: 1. Convert your sysconfig files to "default" config files, which are also in a shell parseable KEY=VALUE format. /usr/etc/default/<example> contains the file provided by the RPM/distribution, /etc/default/<example> can be created by the admin and overwrite single values.

2. Use /usr/share/factory and systemd-tmpfiles like in the "Files and directories in /var" example.

fillup does not work with systemd-sysext nor does the above workaround with systemd-tmpfiles. So better don't use fillup at all.

Open issues and other limitations

There are some open questions:

• While %set_permissions and similar macros work when building the image, the feature does not work later in the running system as the root filesystem is read-only and permissions cannot be changed.