transactional-update, transactional-update.service, transactional-update.timer — Apply updates to the system in an atomic way via transactional updates.
transactional-update
[options
...] [general-command
...] [package-command
[command-argument
...]
]
transactional-update
[options
...] standalone-command
transactional-update.service
transactional-update.timer
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).
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.
If none of the following commands is given, the value of
UPDATE_METHOD
in
transactional-update.conf(5)
will be assumed.
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.
apply
¶Mounts /usr, /etc and /boot of the (new) default snapshot into the currently running system. This is mostly useful for using newly installed packages directly without a reboot. When using apply on a system where existing files will be replaced (e.g. when doing a system update) this behaves similarly to a regular zypper update where files of currently running applications will also be replaced, but with the additional advantage that the update itself was finished successfully as a whole, avoiding inconsistent states on update failures.
Note that - in contrast to regular zypper updates - services will not be restarted automatically. Additionally mounting the three directories is not one atomic operation, so there will be a short timespan where the directories visible to the system will not be in sync.
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-fips
¶Install the FIPS pattern package and configure the kernel command line parameter to activate FIPS mode.
This command can not be combined with any
Package Command other than
install
.
setup-kdump
[--crashkernel=low
,high
]¶
Sets up kdump on the system; if no --crashkernel
option is specified then it will use the values determined by
kdumptool calibrate, otherwise the values of
low
and high
(numbers in Megabytes) will be used for the corresponding
crashkernel kernel parameters.
This command can not be combined with any
Package Command other than
install
.
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 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.
dist-upgrade
, 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.
update
, 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.
register
arguments
¶Register a (commercial) system. This is a simple wrapper for SUSEConnect, as some commands may require access to the root file system (e.g. to add a new key to the RPM database). Any arguments will just be forwarded to SUSEConnect.
This command implies the --drop-if-no-change
option
to avoid creation of unnecessary snapshots, as many of the
SUSEConnect options are read-only or only require
access to /etc.
SUSEConnect is always a non-interactive command.
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.
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.
This command can be combind with the apply
command
to make the snapshot effective immediately.
status
¶This command is under development and will change in the future. The status command is currently using a non-stable feature of MicroOS, the control.xml file, that will change the scope and location in future releases.
Shows the status of current and older snapshots. The status try to represent how the system diverges from an ideal base image, and the list of patterns and packages added and removed from it.
The status is represented via a hash (currently sha256) of a manifest file that contains the list of expected packages and the build time of those packages. The list of expected packages are calculated using the libsolv library, and resolving it for the list of default patterns associated with the role used during the installation.
Two manifest files are created. One will use the information from the repositories used for the installation. The list of packages (including the full version and architecture) and the build time will be extracted from the repository information. The other one will use the same list of packages, but using the build time from the current system (if the package is present).
Both manifest files will be the same if we have a fresh installed system. But in distributions like MicroOS, that are released based on a rolling model, the subsequent updates will make compromises that will result in a diverged state. In that way, if two systems have the same BASE_MANIFEST_DIGEST (the digest calculated from the repository information), we can assume that are in the same state even if the SYSTEM_MANIFEST_DIGEST is different.
We can require of two system to be in the exact same status, and for that we can compare both digests.
The status also shows the differences in patterns and packages from the expected situation, and will save a copy of both manifest for further audit of the system.
To write the necessary state file
EXPERIMENTAL_STATUS=1
has to be set in
transactional-update.conf.
--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
when generated by transactional-update itself, i.e. when using the
run
command only the actual output of the command
will be shown, for other commands the --quiet
option will be appended to the corresponding helper applications if
available (e.g. to the zypper command for the
Package Commands).
--help
, -h
¶Display help and exit
--version
¶Output version information and exit
0
¶All commands were executed successfully.
1
¶One of the commands returned with an error. Due to that a potential new snapshot has been deleted again.
2
¶The apply
command was not successfull.
If called together with another commands, these commands were completed
successfully, but the new default snapshot will not be set in the
live system.
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 (except when
using --continue
to explicitly continue a previous snapshot
or when apply
was called previously).