Ubuntu Manpage: system-image-dbus - Ubuntu System Image Upgrader DBus service

name
synopsys
description
options
d-bus api
files
see also
author
copyright

Provided by: system-image-common_3.1+16.04.20160407-0ubuntu1_all

NAME

       system-image-dbus - Ubuntu System Image Upgrader DBus service

SYNOPSYS

       system-image-dbus [options]

DESCRIPTION

       The  DBus  service published by this script upgrades the system to the latest available image (i.e. build
       number).  With no options, this starts up the com.canonical.SystemImage service.

OPTIONS

       -h, --help
              Show the program's message and exit.

       --version
              Show the program's version number and exit.

       -v, --verbose
              Increase the logging verbosity.  With one -v, logging goes to the console in addition to  the  log
              file, and logging at INFO level is enabled.  With two -v (or -vv), logging both to the console and
              to the log file are output at DEBUG level.

       -C DIR, --config DIR
              Use the given configuration directory, otherwise use the system default.  The  program  will  read
              all the files in this directory that begin with a number, followed by an underscore, and ending in
              .ini (e.g. 03_myconfig.ini).  The files are read in sorted  numerical  order  from  lowest  prefix
              number to highest, with later configuration files able to override any variable in any section.

D-BUS API

This process exports a D-Bus API on the bus name com.canonical.SystemImage, object path /Service, and
interface com.canonical.SystemImage. The D-Bus service process is normally started by D-Bus activation.

The API specification follows. In all cases, where strings are described, they are UTF-8 encoded, and in
English where appropriate. All datetimes are encoded as UTF-8 strings in the UTC timezone using the
combined format (i.e. 'T' separating the date and time portions), with 1 second resolution.

The calls may be synchronous or asynchronous. In the former case, the return values are described. In
the latter case, a description of the possible signals a client may receive is given; see the detailed
description of the signals for details of their payload.

Methods
CheckForUpdate()
This is an asynchronous call instructing the client to check whether an update is available. If a
check is already in progress, it continues. If the client is in auto-download mode (see below),
then this call will automatically begin to download the update if one is available, otherwise the
download must be explicitly initiated by a DownloadUpdate() call. It is possible for an update to
only occur if certain criteria are met, e.g. only if the devices is on wifi. CheckForUpdate()
never resumes a paused download. In all cases, an UpdateAvailableStatus signal is emitted
containing the results of the check. If the device is in auto-download mode, an UpdateProgress
signal is sent as soon as the download is started.

DownloadUpdate()
This is an asynchronous call used to begin the downloading of an available update, and it is a
no-op if there is no update to download, a download is already in progress, CheckForUpdate() was
not called first, or the update status is in an error condition. If a previous download was
paused, DownloadUpdate() resumes the download. An UpdateProgress() signal is sent as soon as the
download begins. Other status signals as described below will be sent when the download
terminates.

ApplyUpdate()
This is an asynchronous call used to apply a previously downloaded update. After the update has
been applied, an Applied signal is sent. Some devices require a reboot in order to apply the
update, and such devices may also issue a Rebooting signal. However, on devices which require a
reboot, the timing and emission of both the Applied and Rebooting signals are in a race condition
with system shutdown, and may not occur.

CancelUpdate()
This is a synchronous call to cancel any update check or download in progress. The empty string
is returned unless an error occurred, in which case the error message is returned.

PauseDownload()
This is a synchronous method to pause the current download. The empty string is returned unless
an error occurred, in which case the error message is returned.

Information()
This is a synchronous call which returns an extensible mapping of UTF-8 keys to UTF-8 values. The
following keys are currently defined:

• current_build_number - The current build number as an integer.

• target_build_number - If an update is known to be available, this will be the build number that
an update will leave the device at. If no CheckForUpdate() has been previously performed, then
the target_build_number will be "-1". If a previous check has been performed, but no update is
available (i.e., the device is already at the latest version), then target_build_number will be
the same as current_build_number.

• device_name - The name of the device type.

• channel_name - The channel the device is currently on.

• last_update_date - The last time this device was updated as a datetime, e.g.
"YYYY-MM-DDTHH:MM:SS"

• version_detail - A string containing a comma-separated list of key-value pairs providing
additional component version details, e.g. "ubuntu=123,mako=456,custom=789".

• target_version_detail - Like version_detail but contains the information from the server. If an
update is known to be available, this will be taken from index.json file's image specification,
for the image that the upgrade will leave the device at. If no update is available this will be
identical to version_detail. If no CheckForUpdate() as been previously performed, then the
target_version_detail will be the empty string.

• last_check_date - The last time a CheckForUpdate() call was performed.

New in system-image 2.3

New in system-image 2.5: target_build_number was added.

New in system-image 3.0: target_version_detail was added.

FactoryReset()
This is a synchronous call which wipes the data partition and issue a reboot to recovery. A
Rebooting signal may be sent, depending on timing.

New in system-image 2.3.

ProductionReset()
This is a synchronous call which wipes the data partition, sets a flag for factory wipe (used in
production), and issue a reboot to recovery. A Rebooting signal may be sent, depending on timing.

New in system-image 3.0.

SetSetting(key, value)
This is a synchronous call to write or update a setting. key and value are strings. While any
key/value pair may be set, some keys have predefined semantics and values. See below for details.

If the new value is different than the old value, or if the key was not previously set, a
SettingChanged signal is sent.

For values with the above semantics, any invalid value is ignored (i.e. not set or stored).

Keys with underscore prefixes are reserved for user defined values.

GetSetting(key)
This is a synchronous call to read and return a setting. If key has not been previously set, the
empty string is returned. Note that some of the pre-defined keys have default settings.

ForceAllowGSMDownload()
This is a synchronous call to force the use of the GSM network for an in-progress wifi-only update
stalled while the device is on GSM. This is only effective when using ubuntu-download-manager.
New in system-image 3.1.

Exit() This is a synchronous call which causes the D-Bus service process to exit immediately. There is
no return value. If Exit() is never called, the service will still exit normally after some
configurable amount of time. D-Bus activation will restart it.

Signals
UpdateAvailableStatus(is_available, downloading, available_version, update_size, last_update_date,
error_reason)
Sent in response to a CheckForUpdate() call, this signal provides information about the state of
the update. The signal includes these pieces of information:

• is_available - A boolean flag which indicates whether an update is available or not. This will
be false if the device's build number is equal to or greater than any candidate build on the
server (IOW, there is no candidate available). This flag will be true when there is an update
available.

• downloading - A boolean flag indicating whether a download is in progress. This doesn't include
any preliminary downloads needed to determine whether a candidate is available or not (e.g.
keyrings, blacklists, channels.json, and index.json files). This flag will be false if a
download is paused.

• available_version - A string specifying the update target candidate version.

• update_size - An integer providing total size in bytes for an available upgrade. This does not
include any preliminary files needed to determine whether an update is available or not.

• last_update_date - The ISO 8601 format UTC date (to the second) that the last update was applied
to this device. This will be the empty string if no update has been previously applied.

• error_reason - A string indicating why the download did not start. Only useful if the second
argument (downloading) is false, otherwise ignore this value.

Depending on the state of the system, some of the arguments of this signal may be ignored. Some
example signal values include:

• UpdateAvailableStatus(true, true, build_number, size, "YYYY-MM-DDTHH:MM:SS", descriptions, "") -
This means that an update is available and is currently downloading. The build number of the
candidate update is given, as is its total size in bytes, and the descriptions of the updates in
all available languages.

• UpdateAvailableStatus(true, false, build_number, size, "YYYY-MM-DDTHH:MM:SS", descriptions,
"paused") - This means that an update is available, but it is not yet downloading, possibly
because the client is in manual-update mode, or because the download is currently paused. The
reason is given in the last argument, and the build number, size, and descriptions are given as
above.

• UpdateAvailableStatus(false, ?, ?, ?, "YYYY-MM-DDTHH:MM:SS", ?, ?) - There is no update
available. The ISO 8601 date of the last applied update is given, but all other arguments should
be ignored.

DownloadStarted()
Sent when the download of the update files has started. New in system-image 3.1.

UpdateProgress(percentage, eta)
Sent periodically, while a download is in progress. This signal is not sent when an upgrade is
paused.

• percentage - An integer between 0 and 100 indicating how much of the download (not including
preliminary files) have been currently downloaded. This may be 0 if we do not yet know what
percentage has been downloaded.

• eta - The estimated time remaining to complete the download, in float seconds. This may be 0 if
we don't have a reasonable estimate.

UpdatePaused(percentage)
Sent whenever a download is paused as detected via the download service.

• percentage - An integer between 0 and 100 indicating how much of the download (not including
preliminary files) have been currently downloaded. May be 0 if this information cannot be
obtained.

UpdateDownloaded()
Sent when the currently in progress update has been completely and successfully downloaded. When
this signal is received, it means that the device is ready to have the update applied via
ApplyUpdate().

UpdateFailed(consecutive_failure_count, last_reason)
Sent when the update failed for any reason (including cancellation, but only if a download is in
progress). The client will remain in the failure state until the next CheckForUpdate() call.

• consecutive_failure_count - An integer specifying the number of times in a row that a
CheckForUpdate() has resulted in an update failure. This increments until an update completes
successfully (i.e. until the next UpdateDownloaded signal is issued).

• last_reason - A string containing the reason for why this updated failed.

Applied(status)
Sent in response to an ApplyUpdate() call. See the timing caveats for that method. New in
system-image 3.0

• status - A boolean indicating whether an update has been applied or not.

Rebooting(status)
On devices which require a reboot in order to apply an update, this signal may be sent in response
to an ApplyUpdate() call. See the timing caveats for that method.

• status - A boolean indicating whether the device has initiated a reboot sequence or not.

SettingChanged(key, value)
Sent when a setting is changed. This signal is not sent if the new value is the same as the old
value. Both the key and value are strings.

• key - The key of the value that was changed.

• value - The new value for the key.

Additional API details
The SetSetting() call takes a key string and a value string. The following keys are predefined.

• min_battery - The minimum battery strength which will allow downloads to proceed. The value is the
string representation of a number between 0 and 100 percent.

• auto_download - A tri-state value indicating whether downloads should normally proceed automatically
if an update is available when a CheckForUpdate() was issued. The value is the string
representation of the following integer values:

• 0 - Never download automatically; i.e. an explicit DownloadUpdate() call is required to start the
download.

• 1 - Only download automatically if the device is connected via wifi. This is the default.

• 2 - Always download the update automatically.

• failures_before_warning - Unused by the client, but stored here for use by the user interface.

FILES

       /etc/system-image/[0-9]+*.ini
              Default configuration files.

       /etc/dbus-1/system.d/com.canonical.SystemImage.conf
              DBus service permissions file.

       /usr/share/dbus-1/system-services/com.canonical.SystemImage.service
              DBus service definition file.

AUTHOR

       Barry Warsaw <barry@ubuntu.com>

COPYRIGHT

       2013-2016 Canonical Ltd.