Ubuntu Wiki

• Created: 2012-04-07

• Contributors: SteveLangasek

• Packages affected: update-notifier, flashplugin-nonfree, msttcorefonts

Summary

Provide a standard interface through update-notifier for handling downloads of extra data needed by packages, in a way that does not break dist-upgrades in case of a download failure.

This is based on Bug # 876298

Rationale

Installer packages which download non-redistributable data from the Internet at package install time are a major source of package management failures. When the server is unreachable, the package will fail to install, potentially causing a cascading failure that could break a system install or an upgrade between releases.

Handling the data downloads with a common interface which reports failures out of band via update-notifier will improve reliability of package management.

Assumptions

• update-notifier-common is a suitable package to pull in as a dependency whenever ttf-mscorefonts-installer or flashplugin-installer are installed.
• update-notifier desktop notifications are a suitable out-of-band mechanism for notifying the admin of a failed download.

Design

Package interfaces

Packages request data downloads by shipping a config file in the /usr/share/package-data-downloads/ directory. The filename of the config file should preferably match the binary package name.

Stamp files are created in /var/lib/update-notifier/package-data-downloads/ to track the status of the downloads, using the same name as the config file from /usr/share/package-data-downloads/ with an optional extension. Packages must take care to remove these stamp files on package removal. If a package upgrade requires data to be downloaded again, either due to changes in the resources to download or in the post-download processing done by the package-provided handler, the stamp files must also be removed on upgrade to the new package version.

Stamp files are also used to record that a package's data download has experienced a permanent failure, either due to repeated download failures or due to a failure calling the package's post-download handler. If an updated package includes a fix for such a handler failure, the package must take care to remove /var/lib/update-notifier/package-data-downloads/package.permanent-failure on upgrade to the fixed version, to request that the download be retried.

Config file format

The per-package config file shipped in /usr/share/package-data-downloads/ is a Debian-RFC822 format file with one or more resource stanzas followed by a single script stanza.

Each resource stanza consists of one each of the following two mandatory fields:

• Url: the url of the resource to download.

• Sha256: the sha256sum of the expected resource.

Checksums other than sha256 are not currently supported. Downloading of resources whose checksum is not known is not supported; this mechanism may only be used for downloading known previously-verified resources.

The script stanza contains the following fields:

• Script: (mandatory) the path to a script provided by the package for post-processing of the downloaded files. update-notifier will pass the script the list of local paths for the downloaded files. The file arguments will be in the same path as they appear in the config file.

• Should-Download: (optional) the name of a boolean debconf question that update-notifier should query to determine whether or not to download the files. This allows a package to signal to update-notifier that the data should not be downloaded if, for instance, the user has not agreed to the license of the downloaded data. If the field is absent, the named debconf question does not exist, or the named debconf question is not of boolean type, update-notifier will assume a default of "yes".

CategorySpec