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

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.