documentation.suse.com / SUSE Linux Enterprise Micro Documentation / Administration Guide / Common tasks / Administration using transactional updates
Applies to SUSE Linux Enterprise Micro 5.3

3 Administration using transactional updates

  

This chapter describes the usage of the transactional-update command.

Warning
Warning

In case you do not reboot your machine before performing further changes, the transactional-update command will create a new snapshot from the current root file system. This means that you will end up with several parallel snapshots, each including that particular change but not changes from the other invocations of the command. After reboot, the most recently created snapshot will be used as your new root file system, and it will not include changes done in the previous snapshots.

3.1 transactional-update usage

  

The transactional-update command enables the atomic installation or removal of updates; updates are applied only if all of them 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 an existing snapshot without rebooting.

The default transactional-update behavior is to create a new snapshot from the current root file system. If you forget something, such as installing a new package, you have to reboot to apply your previous changes, run transactional-update again to install the forgotten package, and reboot again. You cannot run the transactional-update command multiple times without rebooting to add more changes to the snapshot, because this will create separate independent snapshots that do not include changes from the previous snapshots.

Use the --continue option to make as many changes as you want without rebooting. A separate snapshot is made each time, and each snapshot contains all the changes you made in the previous snapshots, plus your new changes. Repeat this process as many times as you want, and when the final snapshot includes everything you want, reboot the system, and your final snapshot becomes the new root file system.

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: 

# transactional-update pkg install package_1
# 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 some changes to the /etc directory, those changes are merged back to the current file system.

--quiet

The transactional-update command will not output to stdout.

--help, -h

Prints help for the transactional-update command.

--version

Displays the version of the transactional-update command.

The general commands are the following:

General commands
  
cleanup-snapshots

The command marks all unused snapshots that are intended to be removed.

cleanup-overlays

The command removes all unused overlay layers of /etc.

cleanup

The command combines the cleanup-snapshots and cleanup-overlays commands. For more details, refer to Section 3.2, “Snapshots cleanup”.

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

If you perform changes to your hardware or storage, you may need to rebuild the kdump initrd.

shell

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

reboot

The system reboots after the transactional-update is complete.

run <command>

Runs the provided command in a new snapshot.

setup-selinux

Installs and enables the targeted SELinux policy.

The package commands are the following:

Important
Important: Installing packages outside of the official SLE Micro repositories

The installation of packages from repositories other than the official ones (for example, the SUSE Linux Enterprise Server repositories) is not supported and not recommended. To use the tools available for SUSE Linux Enterprise Server, run the toolbox container and install the tools inside the container. For details about the toolbox container, refer to Chapter 9, toolbox for SLE Micro debugging.

Package commands
  
dup

Performs an upgrade of your system. 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.

patch

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

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. 

# transactional-update pkg install package_name

or 

# transactional-update pkg install rpm1 rpm2
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. 

# 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. 

# transactional-update pkg update package_name
register

The register command enables you to register/deregister your system. For a complete usage description, refer to Section 3.1.1, “The register command”.

up

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

The standalone commands are the following:

Standalone commands
  
rollback <snapshot number>

This sets the default subvolume. The current system is set as the new default root file system. If you specify a number, that snapshot is used as the default root file system. On a read-only file system, it does not create any additional snapshots. 

# transactional-update rollback snapshot_number
rollback last

This command sets the last known to be working snapshot as the default.

3.1.1 The register command

  

The register command enables you to handle all tasks regarding registration and subscription management. You can supply the following options:

--list-extensions

With this option, the command will list 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 appropriate command will then be the following: 

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

Register your system with the provided registration code. The command will register the subscription and enable 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 will be used in SUSE Customer Center for registration.

--url

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

# 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.

3.2 Snapshots cleanup

  

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.

3.3 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 after installation.

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 3.1: Rollback from a running system
  

  1. Choose the snapshot that should be set as default, run: 

    # snapper list

    to get a list of available snapshots. Note the number of the snapshot to be set as default.

  2. Set the snapshot as default by running: 

    # transactional-update rollback snapshot_number

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

  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 are not able to boot into it.

Procedure 3.2: 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: 

    # transactional-update rollback

    And reboot afterwards.

3.4 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.

You can disable automatic transactional updates with this command: 

# systemctl --now disable transactional-update.timer