Index transactional-update 2.28.3

Name

transactional-update, transactional-update.service, transactional-update.timer — Apply updates to the system in an atomic way via transactional updates.

Synopsis

transactional-update [options...] [general-command...] [package-command [command-argument...] ]

transactional-update [options...] standalone-command

transactional-update.service

transactional-update.timer

DESCRIPTION

transactional-update updates the system in a transactional way; this means updates are atomic, so either the patches are fully applied or nothing is changed. The update does not influence the running system and it can be rolled back. To activate the changes, the system needs to be rebooted.

To achieve this transactional-update is using Btrfs' snapshot mechanism, combined with the default distribution tools. Whenever an update of the root file system is going to be performed, snapper(8) will create a new snapshot of the root file system first. This new snapshot is then used to perform the update, e.g. by calling zypper(8) with the -R option pointing to the new snapshot. If no errors occured the snapshot will be set as the new default snapshot and set as read-only. In case of errors the snapshot will be deleted again.

By default the snapshot is always branched off from the current root file system, i.e. calling transactional-update multiple times without rebooting will create separate, independent snapshots, not containing the changes of the previous run. If multiple consecutive actions are to be executed, the --continue option can be used. This will still create a separate snapshot for each call, so it is possible to roll back to previous intermediate steps in case of errors.

On read-only systems each snapshot will have a corresponding /etc overlay located in /var/lib/overlay. As configuration files may be modified after a snapshot was created and before a reboot is performed (e.g. via configuration management software) the overlay file system will use multiple lower layers, i.e. configuration file changes applied to the currently running system will be visible in the new system, but not vice versa. To keep the number of layers at a minimum the /etc state of the previous snapshot is synchronized into the new root file system; unused overlays will be removed at a later time (see the cleanup-overlays option).

Warning

If a file in /etc has been changed during the update and is also changed in the running system after the snapshot has been taken, then only the version of the new snapshot will be visible after a reboot. When booting into the new snapshot for the first time transactional-update-etc-cleaner.service will print a warning about such conflicts to the system log file.

Older transactional-update versions were using a single /etc overlay for all snapshots; a migration mechanism is in place, the directory will also be removed if no snapshot is using it any more.

On read-write systems please be aware that all changes done to the running root filesystem after snapshot creation are lost after the next reboot. For this reason the system should be rebooted as fast as possible after a successful update.

For easier maintenance of big clusters, transactional-update is run by systemd.timer(5) in regular intervals. The specific time can be configured in /etc/systemd/system/transactional-update.timer.d/local.conf. See systemd.unit(5) for more information.

COMMANDS

If none of the following commands is given up will be assumed.

General Commands

General Commands can be used together in any combination; additionally they can be extended with one Package Command. The order of the General Commands doesn't matter.

cleanup

Identical to calling both cleanup-snapshots and cleanup-overlays.

cleanup-snapshots

If the current root filesystem is identical to the active root filesystem (means after a reboot, before transactional-update creates a new snapshot with updates), all old snapshots without a cleanup algorithm get a cleanup algorithm set. This is to make sure, that old snapshots will be deleted by snapper. See the section about cleanup algorithms in snapper(8).

cleanup-overlays

Removes all unreferenced (and thus unused) /etc overlay directories in /var/lib/overlay.

grub.cfg

grub2-mkconfig(8) is called to create a new /boot/grub2/grub.cfg configuration file for the bootloader.

bootloader

Same as grub.cfg, but will also rewrite the bootloader itself.

initrd

A new initrd is created in a snapshot.

kdump

A new initrd for kdump is created in a snapshot.

reboot

Trigger a reboot after updating the system.

Several different reboot methods are supported, configurable via the REBOOT_METHOD configuration option in transactional-update.conf(5). By default rebootmgrd(8) will be used to reboot the system according to the configured policies if the service is running, otherwise systemctl reboot will be called.

run cmd

Execute the the command cmd inside a new snapshot. By default this snaphot will remain, but if --drop-if-no-change is set, the new snapshot will be dropped if there is no change in the file system.

This command consumes all the remaining parameters, so should be placed in the last position.

To use features like command lists (e.g. pipes or separators) wrap the script into a Shell command like such as

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

setup-selinux

Sets up a SELinux system: Installs the default SELinux "Targeted policy" and enables it.

This command can not be combined with any Package Command other than install.

shell

Opens a shell to execute commands like zypper manually. After all actions are done, before the snapshot with the changes is unmounted and switched to read-only, a shell is started in the new snapshot as chroot environment for testing and debugging.

Package Commands

Package Commands will invoke zypper(8) to perform actions on the RPM packages. Only one Package Command can be used at the same time. Can be combined with any number of General Commands.

By default commands usually invoked from scripts are called in non-interactive mode (assuming the default answer in case of questions), commands typically called by the user are called in interactive mode. The behaviour can be changed or enforced using the --interactive respectively the --non-interactive options.

To facilitate scripting Package Commands will exit early if no packages were updated; if combined with General Commands those will not be executed any more in that case.

Non-interactive Package Commands

dup

If new updates are available, a new snapshot is created and zypper dup --no-allow-vendor-change is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot.

up

If new updates are available, a new snapshot is created and zypper up is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot.

patch

If new updates are available, a new snapshot is created and zypper patch is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot.

Interactive Package Commands

migration

On systems which are registered against the SUSE Customer Center (SCC) or SMT, a migration to a new version of the installed products can be made with this option.

pkg command arguments

Calls zypper with the given command and arguments. The arguments are typically one or more package names, but can be any zypper(8) parameter for the given command including options. The following commands are supported:

install, in

Installs additional software. See the install description in the "Package Management Commands" section of zypper's man page for all available arguments.

remove, rm

Removes installed software. See the remove description in the "Package Management Commands" section of zypper's man page for all available arguments.

update, up

Update selected software. See the update description in the "Update Management Commands" section of zypper's man page for all available arguments.

Standalone Commands

rollback [number]

Sets the default root file system. On a read-only system the root file system is set directly using btrfs. On read-write systems snapper(8) rollback is called.

If no snapshot number is given, the current root file system is set as the new default root file system. Otherwise number can either be a snapshot number (as displayed by snapper list) or the word last. last will try to reset to the latest working snapshot.

OPTIONS

--interactive, -i

Calls zypper in interactive mode, even if the default for this command is non-interactive.

--non-interactive, -n

Calls zypper in non-interactive mode, even if the default for this command is interactive.

--continue [number], -c [number]

Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot.

--no-selfupdate

Skip checking for newer transactional-update versions.

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

If the action does not produce a change in the underlying file system, the snapshot will be dropped.

--quiet

Don't print warnings and informational messages to stdout.

--help, -h

Display help and exit

--version

Output version information and exit

IMPORTANT

Only RPMs which are fully part of the root filesystem and /etc can be updated. There is also limited handling for adding files and directories to /var, however modifications of existing files (e.g. migrating databases) are supposed to be handled by systemd jobs at startup (see the initial configuration and deployment section of the packaging guidelines).

Since all changes to the root filesystem will get lost after creating the snapshot for the update, the system should be rebooted as fast as possible after the update finished.

Every time transactional-update will create a new snapshot it will be based on the currently running system. Calling transactional-update multiple times without rebooting will not include the changes of the previous snapshot, thus effectively discarding all previous changes.

SEE ALSO

transactional-update.conf(5), systemd.timer(5), systemd.time(7), The Transactional Update Guide