Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / Administering SLE Micro using the transactional-update command

Administering SLE Micro using the transactional-update command

Publication Date: 27 Sep 2024
WHAT?

The transactional-update command enables you to modify a read-only file system. The modifications are performed in a separate snapshot and do not influence the running system until you boot into the snapshot.

WHY?

You want to administer SLE Micro and manage its updates, minimizing the risk of system downtime due to update failures while ensuring easy rollbacks.

EFFORT

It takes less than 30 minutes to understand the transactional-update command.

GOAL

You will understand how transactional-update works and how you can use it to administer your system.

REQUIREMENTS

  • A running instance of SLE Micro

  • root privileges

1 Transactional updates

 

1.1 What are transactional updates?

 

To keep the base operating system stable and consistent, the SUSE Linux Enterprise Micro uses a read-only root file system. Therefore, you cannot perform direct changes to the root file system, for example, by using the zypper command. Instead, SLE Micro introduces transactional updates that allow you to apply one or more changes to the root file system.

The default transactional-update behavior is to create a new snapshot from the current root file system after each change. To apply the changes, you need to reboot the host. You cannot run the transactional-update command multiple times without rebooting to add more changes to the snapshot. This action creates separate independent snapshots that do not include changes from the previous snapshots.

1.2 How do transactional updates work?

 

Each time you call the transactional-update command to change your system—either to install a package, perform an update, or apply a patch—the following actions take place:

Procedure 1: Modifying the root file system
 

  1. A new read-write snapshot is created from your current root file system, or from a snapshot that you specified.

  2. All changes are applied (updates, patches or package installation).

  3. The snapshot is switched back to read-only mode.

  4. If the changes were applied successfully, the new root file system snapshot is set as default.

  5. After rebooting, the system boots into the new snapshot.

1.3 Benefits of transactional updates

 

  • They are atomic—the update is applied only if it completes successfully.

  • Changes are applied in a separate snapshot and so do not influence the running system.

  • Changes can easily be rolled back.

1.4 Environment within the transactional-update command

 

Each time you run the transactional-update command, the changes are performed in a new snapshot. The environment in the snapshot may differ from the one in the shell you run the transactional-update command from. For example, the current working directory ($PWD) is not set to the directory from which you run the transactional-update, but is set to /.

From within the snapshot, you cannot access the /var directory. This directory is also not included in the snapshot. However, some directories are not included in the snapshot but are accessible inside the transactional-update environment, for example, the /root directory.

2 Usage of the transactional-update command

 

The transactional-update command enables the atomic installation or removal of updates. Updates are applied only if all can be successfully installed. transactional-update creates a snapshot of your system and uses it to update the system. Later you can restore this snapshot. All changes become active only after reboot.

The transactional-update command syntax is as follows: 

transactional-update [option] [general_command] [package_command] standalone_command
Note
Note: Running transactional-update without arguments

If you do not specify any command or option while running the transactional-update command, the system updates itself.

Possible command parameters are described further.

transactional-update options
 
--interactive, -i

Can be used along with a package command to turn on interactive mode.

--non-interactive, -n

Can be used along with a package command to turn on non-interactive mode.

--continue [number], -c

The --continue option is for making multiple changes to the root file system without rebooting. Refer to Section 3, “Applying multiple changes without rebooting” for more details.

Another useful feature of the --continue option is that you may select any existing snapshot as the base for your new snapshot. The following example demonstrates running transactional-update to install a new package in a snapshot based on snapshot 13, and then running it again to install another package: 

> sudo transactional-update pkg install package_1
> sudo transactional-update --continue 13 pkg install package_2
--no-selfupdate

Disables self-updating of transactional-update.

--drop-if-no-change, -d

Discards the snapshot created by transactional-update if there were no changes to the root file system. If there are changes to the /etc directory, those changes merged back to the current file system.

--quiet

The transactional-update command does not output to stdout .

--help, -h

Prints help for the transactional-update command.

--version

Displays the version of the transactional-update command.

2.1 General commands

 

This section lists general purpose commands of transactional-update.

grub.cfg

Use this command to rebuild the GRUB boot loader configuration file.

bootloader

The command reinstalls the boot loader.

initrd

Use the command to rebuild initrd.

kdump

In case you perform changes to your hardware or storage, you may need to rebuild the Kdump initrd.

reboot

The system reboots after the transactional-update command is complete.

run <command>

Runs the provided command in a new snapshot.

shell

Opens a read-write shell in the new snapshot before exiting. The command is typically used for debugging purposes.

setup-fips

The command performs all changes needed to enable FIPS on your system.

setup-selinux

Installs and enables targeted SELinux policy.

3 Applying multiple changes without rebooting

 

The transactional-update command applies changes to the root file system on a transactional system. The default behavior is to create a new snapshot from the current root file system after each change and reboot to apply the changes.

To make multiple changes to the root file system without rebooting, you have several options, which are described in the following sections:

3.1 The transactional-update --continue option

 

Use the transactional-update command together with the --continue option to make multiple changes without rebooting. A separate snapshot is created on each run that contains all changes from the previous snapshot, plus your new changes. The final snapshot includes all changes. To apply them, reboot the system and your final snapshot becomes the new root file system.

3.2 The transactional-update run command

 

The transactional-update run command normally runs only a single command. However, you can use it to run multiple commands in one transactional session by concatenating them within a command shell such as bash, for example: 

> sudo transactional-update run bash -c 'ls && date; if [ true ]; then echo -n "Hello "; echo '\''world'\''; fi'
Note
Note

The transactional-update run command has the same limitations as the transactional-update shell command described in Section 3.3, “The transactional-update shell” except that the entered commands are logged in the /var/log/transactional-update.log file.

3.3 The transactional-update shell

 

The transactional-update shell command opens a shell in the transactional-update environment. In the shell, you can enter almost any Linux command to make changes to the file system, for example, install multiple packages with the zypper command or perform changes to files that are part of the read-only file system. You can also verify that the changes you previously made with the transactional-update command are correct.

Important
Important

The transactional shell has several limitations. For example, you cannot operate start or stop services using systemd commands, or modify the /var partition because it is not mounted. Also, commands entered during a shell session are not logged in the /transactional-update.log file.

All changes that you make to the file system are part of a single snapshot. After you finish making changes to the file system and leave the shell with the exit command, you need to reboot the host to apply the changes.

4 Performing snapshots cleanup

 

You can use transactional-update to clean unused file system snapshots and unreferenced /etc overlay directories.

transactional-update recognizes the following cleanup commands:

cleanup-snapshots

The command marks all unused snapshots for removal by Snapper.

cleanup-overlays

The command removes all unused overlay layers of /etc in the /var/lib/overlay directory.

cleanup

The command combines the cleanup-snapshots and cleanup-overlays commands.

4.1 How the cleanup works

 

If you run the command transactional-update cleanup, all old snapshots without a cleanup algorithm will have one set. All important snapshots are also marked. The command also removes all unreferenced (and thus unused) /etc overlay directories in /var/lib/overlay.

The snapshots with the set number cleanup algorithm will be deleted according to the rules configured in /etc/snapper/configs/root by the following parameters:

NUMBER_MIN_AGE

Defines the minimum age of a snapshot (in seconds) that can be automatically removed.

NUMBER_LIMIT/NUMBER_LIMIT_IMPORTANT

Defines the maximum count of stored snapshots. The cleaning algorithms delete snapshots above the specified maximum value, without taking into account the snapshot and file system space. The algorithms also delete snapshots above the minimum value until the limits for the snapshot and file system are reached.

The snapshot cleanup is also regularly performed by systemd.

5 Registering products

 

You can use the transactional-update register command to handle all tasks regarding product registration and its subscription management. You can supply the following options:

--list-extensions

With this option, the command lists available extensions for your system. You can use the output to find a product identifier for product activation.

-p, --product

Use this option to specify a product for activation. The product identifier has the following format: <name>/<version>/<architecture>, for example, sle-module-live-patching/15.3/x86_64. The corresponding command has the following form: 

> sudo transactional-update register -p sle-module-live-patching/15.3/x86_64
-r, --regcode

Register your system with the registration code provided. The command registers the subscription and enables software repositories.

-d, --de-register

The option deregisters the system, or when used along with the -p option, deregisters an extension.

-e, --email

Specify an email address that is used in SUSE Customer Center for registration.

--url

Specify the URL of your registration server. The URL is stored in the configuration and is used in subsequent command invocations. For example: 

> sudo transactional-update register --url https://scc.suse.com
-s, --status

Displays the current registration status in JSON format.

--write-config

Writes the provided options value to the /etc/SUSEConnect configuration file.

--cleanup

Removes old system credentials.

--version

Prints the version.

--help

Displays the usage of the command.

6 Managing software packages

 

You can use transactional-update to install, update or remove software packages.

SLE Micro obtains software packages from repositories that are available after the product registration.

transactional-update uses the following commands to manage software packages.

Tip
Tip: The pkg command and Zypper options

With transactional-update pkg commands, you can use any Zypper option that corresponds to the used subcommand. For example, transactional-update pkg install understands all options that zypper install does.

pkg install

Installs individual packages from the available channels using the zypper install command. This command can also be used to install Program Temporary Fix (PTF) RPM files. The default option for this command is --interactive. 

> sudo transactional-update pkg install package_name

or 

> sudo transactional-update pkg install rpm1 rpm2

Or, to install a software pattern: 

> sudo transactional-update pkg install -t pattern pattern_name
pkg remove

Removes individual packages from the active snapshot using the zypper remove command. This command can also be used to remove PTF RPM files. The default option for this command is --interactive. 

> sudo transactional-update pkg remove package_name
pkg update

Updates individual packages from the active snapshot using the zypper update command. Only packages that are part of the snapshot of the base file system can be updated. The default option for this command is --interactive. 

> sudo transactional-update pkg update package_name
patch

Checks for available patches and installs them. The default option for this command is --non-interactive.

dup

Performs an upgrade of your system. The default option for this command is --non-interactive.

up

Updates installed packages to newer versions. The default option for this command is --non-interactive.

migration

The command migrates your system to a selected target. Typically, it is used to upgrade your system if it has been registered via SUSE Customer Center.

7 Performing system rollback

 

GRUB 2 enables booting from btrfs snapshots and thus allows you to use any older functional snapshot in case the new snapshot does not work correctly.

When booting a snapshot, the parts of the file system included in the snapshot are mounted read-only; all other file systems and parts that are excluded from snapshots are mounted read-write and can be modified.

Tip
Tip: Rolling back to a specific installation state

An initial bootable snapshot is created at the end of the initial system installation. You can go back to that state at any time by booting this snapshot. The snapshot can be identified by the description first root file system.

There are two methods to perform a system rollback.

If your current snapshot is functional, you can use the following procedure for a system rollback.

Procedure 2: Rollback from a running system
 

  1. Identify the snapshot that should be set as the default one and note its number. 

    > sudo snapper list

  2. Set the snapshot as default. 

    > sudo transactional-update rollback snapshot_number

    If you omit the snapshot number, the current snapshot will be set as default.

    Tip
    Tip: Setting the last working snapshot

    To set the last working snapshot as the default one, run rollback last.

  3. Reboot your system to boot into the new default snapshot.

The following procedure is used in case the current snapshot is broken and you cannot boot into it.

Procedure 3: Rollback to a working snapshot
 

  1. Reboot your system and select Start bootloader from a read-only snapshot.

  2. Choose a snapshot to boot. The snapshots are sorted according to the date of creation, with the latest one at the top.

  3. Log in to your system and check whether everything works as expected. The data written to directories excluded from the snapshots will stay untouched.

  4. If the snapshot you booted into is not suitable for the rollback, reboot your system and choose another one.

    If the snapshot works as expected, you can perform the rollback by running the following command: 

    > sudo transactional-update rollback

    And reboot afterwards.

8 Managing automatic transactional updates

 

Automatic updates are controlled by systemd.timer that runs once per day. This applies all updates and informs rebootmgrd that the machine should be rebooted. You may adjust the time when the update runs, see systemd.timer(5) documentation.

8.1 Disabling automatic updates

 

The automatic updates are enabled by default. However, you can disable them with this command: 

> sudo systemctl --now disable transactional-update.timer

8.2 Configuring notifications of failed updates

 

When an automatic transactional-update fails, the failed snapshot is deleted. Meanwhile the system may reboot, and then you cannot find out that the last automatic update failed. Therefore, you can configure a systemd service that will inform you about the failure of the automatic transactional-update. The procedure of doing so can be summarized into the following steps:

8.2.1 Installing required packages

 

The packages mailx and systemd-status-mail are required to configure the notifications. They are present on the system by default. However, if you do not have them installed, install the packages by running the following command: 

> sudo transactional-update pkg in systemd-status-mail mailx

Reboot the system.

8.2.2 Configuring the systemd-status-mail service

 

To configure the systemd-status-mail service, you can create a configuration file or you can use the jeos-config tool.

8.2.2.1 Configuring the service using jeos-config
 

To configure the email notifications, you can use the jeos-config tools as described bellow.

  1. To open the configuration window, run the command: 

            > sudo jeos-config status_mail

  2. In the dialog, configure the items according to your needs.

  3. Confirm with OK.

8.2.2.2 Configuring the service by editing a configuration file
 

The default configuration file is in /usr/etc/default/systemd-status-mail. To modify it, create a copy in /etc/default/ and edit the following items:

ADDRESS

A mandatory entry. Specify the e-mail address the notification is sent to. For example: 

ADDRESS=“tux@example.com”
FROM

The sender e-mail of the notification mail. Ensure that the address is valid. For example: 

FROM=“geeko@example.com”
MAILER

The type of mail application for sending notifications. Use the mailx value as follows: 

MAILER=“mailx”
RELAYHOST

Specify the mail relay used by mailx. 

RELAYHOST=“mail.example.com:587”
MAILX_OPTIONS

Specify necessary options to ensure that the mail provider will accept the notification mail. `` 

MAILX_OPTIONS="-Sverbose -Ssmtp-use-starttls -Ssmtp-auth=login -Ssmtp-auth-user='tux@example.com' -Ssmtp-auth-password='TopSecret'"