Skip to content

Software Update Configuration and Usage

The Welma software update service provides several interfaces for controlling and configuring the update process:

  • Runtime configurations and daemon behavior: Can be configured through /etc/updated.conf configuration file.

  • The updatectl command-line tool: Provides the primary user interface for managing software updates.

  • D-Bus API: Allows applications to interact directly with the update daemon.

This page describes these interfaces and how they can be used to control and configure the Welma software update service.

Runtime configuration

The updated daemon supports two runtime configuration options in /etc/updated.conf: confirm-timeout and allow-downgrade.

Confirm timeout

confirm-timeout defines the maximum time, in seconds, allowed to confirm an update after the system boots on newly installed partitions. Once the system has booted into the updated version, updated waits for a ConfirmUpdate request. If the update is not confirmed within the configured timeout, a rollback is triggered and the system returns to the previously installed version.

The confirmation timeout mechanism can be disabled by setting confirm-timeout to 0 or to a negative value. When disabled, no automatic rollback is triggered due to a missing update confirmation.

confirm-timeout is a required configuration entry in /etc/updated.conf.

Allow downgrade

allow-downgrade controls whether updated accepts an update that would replace a module with an older version. Version comparison relies on the version information provided by the Software Version Control feature.

When allow-downgrade is set to true, installing a module whose version is lower than the currently installed version is allowed. When set to false, updated rejects such an update before installation.

This option is optional and defaults to true when it is not specified in /etc/updated.conf.

Warning

By default, Welma allows downgrade updates. You can change this behavior by adding allow-downgrade=false line in /etc/updated.conf

Example of /etc/updated.conf content

/etc/updated.conf
[core]
# Set confirm timeout to 2min
confirm-timeout=120

updatectl API

updatectl is the command-line interface for controlling the Welma software update service.

It communicates with the updated daemon through its D-Bus API and provides commands to configure updated, install software update packages, inspect the current update status, confirm or abort an update, and interact with the clearance mechanism.

It can be used directly from the command line or from scripts to manage the software update lifecycle.

Usage: updatectl install FILE [FILE ...]
       updatectl confirm
       updatectl abort
       updatectl status [PROPERTY]
       updatectl set [PROPERTY] [VALUE]
       updatectl clearance-request REASON
       updatectl clearance-notify RESPONSE

Commands:

  confirm   Confirm a software udpate under test
  install   Install a software update and schedule it for next reboot as under test
  abort     Abort a pending software update (scheduled or under test)
  status    Print update status
  set       Set a property to a specified value
            Currently only "allow-downgrade" is supported.
  clearance-notify
            Send the clearance response.
  clearance-request
            Send a request for clearance.

Arguments:

  FILE      A software module to be installed.
  PROPERTY  A single property for which the status is needed
  REASON    download | install
  RESPONSE  ready | rejected | retry-later

Example of a manual installation scenario

  1. Get the current update status 

    # updatectl status

state               normal
partitions-active   /dev/mmcblk2p1 /dev/mmcblk2p3 /dev/mmcblk2p5
partitions-inactive /dev/mmcblk2p2 /dev/mmcblk2p4 /dev/mmcblk2p6
allow-downgrade     true

  2. Install the update package 

    # updatectl install /tmp/appro-v1.1.swu
    Installation logs are recorded in the system journal and can be viewed using journalctl -u updated.

  3. Check the update status state after the installation 

    # updatectl status state

normal,test-scheduled

  4. Reboot 

    # reboot

  5. Check the update status after the reboot 

    # updatectl status

state               under-test
partitions-active   /dev/mmcblk2p1 /dev/mmcblk2p3 /dev/mmcblk2p6
partitions-inactive /dev/mmcblk2p2 /dev/mmcblk2p4 /dev/mmcblk2p5
allow-downgrade     true
    Note that /dev/mmcblk2p6 and /dev/mmcblk2p5 switch roles between the active and inactive partitions.

  6. Confirm the update 

    # updatectl confirm

D-Bus API

The updated daemon exposes a D-Bus API, described in this section.

Bus name: 

com.witekio.update1
Manager object: 
NAME                                TYPE      SIGNATURE RESULT/VALUE FLAGS
com.witekio.update1.Manager         interface -         -            -
.AbortUpdate                        method    -         -            -
.BeginUpdate                        method    -         -            -
.ConfirmUpdate                      method    -         -            -
.InstallLocalFile                   method    s         -            deprecated
.InstallLocalFiles                  method    as        -            -
.MarkSlotUpdated                    method    s         -            -
.NotifyClearance                    method    s         -            -
.RequestClearance                   method    s         s            -
.SubmitUpdate                       method    -         -            -
.AllowDowngrade                     property  b         false        emits-change writable
.ConfirmTimeoutSec                  property  i         120          emits-change
.State                              property  s         "normal"     emits-change
.ClearanceRequested                 signal    s         -            -

Methods

  • AbortUpdate

    Aborts a started update transaction, before or after reboot. Aborting an update after reboot leads to reboot and a rollback to the initial software system.

  • BeginUpdate

    Starts an update transaction, that shall be followed by:

    • Installing packages, via InstallLocalFiles
    • Submitting the update to the bootloader, via SubmitUpdate
    • Rebooting
    • Confirming the update of A/B partitions, via ConfirmUpdate

  • InstallLocalFile

    Installs a package onto its inactive partition. Cannot be used in mode mender-connected (see MarkSlotUpdated).

    Warning

    InstallLocalFile is deprecated. Please use InstallLocalFiles instead

  • InstallLocalFiles

    Installs a list of package onto inactive partition. Used also to check all packages compatibilites before any installation (see This page for more details). Cannot be used in mode mender-connected (see MarkSlotUpdated).

  • MarkSlotUpdated

    Marks a slot (partition) as updated, when the installation was not made using InstallLocalFile or InstallLocalFiles. This is typically used in mode mender-connected. slot_name must be a valid partition name of /etc/welma-partitions.conf.

  • SubmitUpdate

    Submits the update to bootflags, that tells the bootloader to do next boot on the newly installed partitions.

  • ConfirmUpdate

    Makes the update persistent. Rollback cannot be performed after this. Not applicable when only single mode packages were installed.

  • RequestClearance

    Requests that the embedded system prepares itself for a significant update operation such as downloading or installing packages. It is typically called by a program in charge of downloading and installing packages when another program (application, GUI,...) is in charge of granting clearance (by calling NotifyClearance).

    • reason must be one of: download, install.
    • response is the status given by NotifyClearance(), or timeout if no response is received after 5 minutes.

    Only one clearance request is allowed at a time. See an example of a typical clearance request sequence.

  • NotifyClearance

    Informs the update subsystem about the status of the clearance request. status must be one of: ready, rejected, retry-later. It is given as a response to RequestClearance.

  • ClearanceRequested

    Sent out each time a clearance request is done. reason is the reason given in the clearance request (see RequestClearancefor possible values).

Properties

  • State

    Contains the state of the update daemon, one of:

    • normal: Regular operational state, a new update procedure may be initiated by BeginUpdate.
    • normal,ongoing-install: A package is being installed by InstallLocalFiles. Other installation or submit requests will be rejected.
    • normal,aborting: An installation procedure is being aborted by AbortUpdate. Other requests will be rejected.
    • normal,test-scheduled: An update procedure has been submitted by SubmitUpdate and awaits a reboot for taking effect.
    • under-test: The system is running on packages that just got installed before the latest reboot, and the update daemon is waiting for a call to ConfirmUpdate.

  • ConfirmTimeoutSec

    Contains the time, in seconds, allowed to confirm an update. Read only property.

  • AllowDowngrade

    Contains the current state of the allow-downgrade configuration. Can be updated using D-Bus interface or updatectl tool.

See also: