swupd

OS software update program

Copyright:

(C) 2020 Intel Corporation, CC-BY-SA-3.0

Manual section:

1

SYNOPSIS

swupd [subcommand] <flags>

DESCRIPTION

swupd(1) is an OS-level software update program that applies updates to system software.

The updates are fetched from a central software update server. If a valid update is found on the server, it can be downloaded and applied.

The swupd tool can also install and remove bundles, check for updates without applying them, perform system-level diagnose of the system software, and install an OS.

A version url server provides version information. This server notifies the program of available updates.

A content url server (can be the same as version url server) provides the file and metadata content for all versions. The content url server provides metadata in the form of manifests. These Manifest files list and describe file contents, symlinks, directories. Additionally, the actual content is provided to clients in the form of archive files.

swupd consumes update artifacts generated by mixer in the specific format the installed version of swupd understands. For more information about how these artifacts are generated see mixer(1) and os-format(7).

The swupd tool can also manage 3rd-party content, this allows users to install, remove, and update bundles from 3rd-party repositories.

OPTIONS

The following options are applicable to most subcommands, and can be used to modify the core behavior and resources that swupd uses.

-h, --help

Display general help information. If put after a subcommand, it will display help specific to that subcommand.

-v, --version

Displays the version information of the swupd program, and exit. It also displays compile options and copyright information.

-p <path>, --path=<path>

Optionally set the top-level directory for the swupd-managed system. This can be used to point to a chroot installation of the OS or a custom mount. If not specified this will default to /.

-u <url>, --url=<url>

Specify an RFC-3986 encoded url. The url will be used to download version information and file content downloads.

-P <port>, --port=<port>

Specify the port number of the server to connect to. Applies to both version and file content url server connections.

-c <url>, --contenturl=<url>

Specify an RFC-3986 encoded url. The url will be used for file content downloads only.

-v <url>, --versionurl=<url>

Specify an RFC-3986 encoded url. The url will be used to download version information.

-F <formatstring>, --format=<formatstring>

Specify the format suffix for version file downloads. Is usually one of 1, 2, 3, etc. or staging. Software update formats may change regularly and normally you should consult the swupd server data for the appropriate latest version available. If that version is not supported by your version of swupd, you should subtract 1 from the number and try again until it succeeds.

-S <path>, --statedir=<path>

Specify an alternate path for swupd cache and data directory. Normally swupd uses /var/lib/swupd.

-K <path>, --cachedir=<path>

Specify an alternate swupd cache directory. Normally swupd uses /var/lib/swupd.

-Z <path>, --datadir=<path>

Specify an alternate swupd data directory. Normally swupd uses /var/lib/swupd.

-C <path>, --certpath=<cert>

Specify alternate path to swupd certificate store (pem file). Default is /usr/share/clear/update-ca/Swupd_Root.pem

-W <n>, --max-parallel-downloads=<n>

Set the maximum number of parallel downloads.

-r <n>, --max-retries=<n>

Maximum number of retries for download failures.

-d <n>, --retry-delay=<n>

Initial delay in seconds between download retries, this will be doubled for each retry until the download succeeds or the maximum number of retries has been reached.

-n, --nosigcheck

Do not attempt to enforce certificate or signature checking.

-n, --nosigcheck-latest

Do not attempt to enforce signature checking when retrieving the latest version number.

-I, --ignore-time

Ignore system/certificate time when validating signature.

-t, --time

Show verbose time output for swupd operations.

-N, --no-scripts

Do not run the post-update scripts and boot update tool.

-b, --no-boot-update

Do not update the boot files using clr-boot-manager.

-j, --json-output

Prints the swupd output as a machine readable JSON stream.

-y, --yes

Assume yes as answer to all prompts and run non-interactively.

--allow-insecure-http

For security reasons, swupd only allows system updates using secure https connections by default. This option forces swupd to allow updates over insecure http connections.

Warning: although it is not recommended, if an http server is set up as the upstream server, the allow_insecure_http=true option will need to be setup in the swupd configuration file for the autoupdate command to continue to work.

--quiet

Sets swupd to print a minimal and more stable output that is easier to parse for its commands. Only the most relevant information and errors are printed out. Output displayed when using this option is rarely going to change, so this is a good option to use when writing scripts that use swupd.

--verbose

Enable verbosity for commands.

--debug

Print extra information to help debugging problems.

--no-progress

Don’t print progress report on commands that informs the percentage left in current operation.

--wait-for-scripts

Wait for the post-update scripts to complete.

--assume=<yes|no>

Sets an automatic response to all prompts and run non-interactively.

SUBCOMMANDS

info

Shows the current OS version and the URLs used for updates.

autoupdate

Enables or disables automatic updates, or reports current status. Enabling updates does not cause an immediate update - use swupd update to force one if desired.

--enable

Enable autoupdates

--disable

Disable autoupdates

check-update

Checks whether an update is available and prints out the information if so. Does not download update content.

update

Performs a system software update.

The program will contact the version server at the version url, and check to see if a system software update is available. If an update is available, the update content will be downloaded from the content url and stored in the /var/lib/swupd state path. Once all content is downloaded and verified, the update is applied to the system.

In case any problem arises during a software update, the program attempts to correct the issue, possibly by performing a swupd repair operation, which corrects broken or missing files and other issues.

After the update is applied, the system performs an array of post-update actions. These actions are triggered through systemd(1) and reside in the update-triggers.target(4) system target.

-V <version>, --version=<version>

Update to a specific version, also accepts ‘latest’ (default).

-s, --status

Do not perform an update, instead display whether an update is available on the version url server, and what version number is available. This is the same as running swupd check-update.

-k, --keepcache

Do not delete the swupd state directory content after updating the system.

--download

Do not perform an update, instead download all resources needed to perform the update, and exit.

--update-search-file-index

Update the index used by search-file to speed up searches. Don’t enable this if you have download or space restrictions.

--3rd-party

If update is successfull, also update content from 3rd-party repositories.

bundle-add <bundles>

Installs new software bundles. Any bundle name listed after bundle-add will be installed in the system. A list of all existing bundles can be displayed with the bundle-list --all command.

The names can also be aliases that are not actual bundles names but instead are names in an alias configuration file. See swupd-alias(7)

--skip-optional

Do not install optional bundles (also-add flag in Manifests). A bundle may include other bundles that will also get installed when installing the bundle that includes them. This included bundles can be either optional, or mandatory. Optional bundles can be skipped at install time by using this option.

--skip-diskspace-check

Skip checking for available disk space before installing a bundle. By default, swupd attempts to determine if there is enough free disk space to add the passed in bundle before attempting to install. The current implementation will check free space in /usr/ by default, or it will check the passed in –path option with /usr/ appended.

bundle-remove <bundles>

Removes software bundles. Any bundle name listed after bundle-remove will be removed from the system. If the bundle is required by another bundle(s) on the system, a tree will be displayed to indicate which bundles are blocking removal.

-x, --force

Removes a bundle along with all the bundles that depend on it.

Warning: This operation is dangerous and must be used with care since it can remove many unexpected bundles.

-R, –recursive Removes a bundle and its dependencies recursively, except for

bundle os-core.

Warning: This operation is dangerous and must be used with care since it can remove many unexpected bundles.

--orphans

Removes all orphaned bundles. Orphan bundles are those that are no longer required by any of the tracked bundles.

Warning: This operation is dangerous and must be used with care since it can remove many unexpected bundles.

bundle-list

List all installed software bundles in the local system. Available bundles can be listed with the --all option.

-a, --all

Lists all available software bundles, either installed or not, that are available.

-D <bundle>, --has-dep=<bundle>

Displays a list of all bundles which include the passed BUNDLE as a dependency. Combine with --all to report all bundles including those not installed on the system. Combine with --verbose to show a tree of those bundles.

--status

Show the installation status of the listed bundles. Bundles installation status can be; “explicitly installed”, meaning that they were specifically requested to be installed by the user, or they can be “implicitly installed”, meaning they were installed as a dependency of another explicitly installed bundle.

--deps=<bundle>

Lists all bundle dependencies of the passed BUNDLE, including recursively included bundles.

--orphans

List orphaned bundles. Orphan bundles are those that are installed but no longer required by any tracked bundle.

bundle-info

Display detailed information about a bundle.

-V <version>, --version=<version>

Show the bundle info for the specified version, it also accepts ‘latest’.i It defaults to the current version if no version is specified.

--dependencies

Show the bundle’s direct and indirect dependencies as well as if they are optional or mandatory dependencies. Direct dependencies are those that are specifically included by the bundle in question, while indirect dependencies are those that are included by the bundles that are a direct dependency of the bundle in question.

--files

Show the files directly included in this bundle, in other words it shows the files included in the bundle’s manifest. If this option is used along with the --dependencies option, all files installed by the bundle are listed, including those files installed by the dependencies of the bundle.

search-file <string>

Search for matching paths in manifest data. The specified {string} is matched in any part of the path listed in manifests, and all matches are printed, including the name of the bundle in which the match was found.

If manifest data is not present in the state folder, it is downloaded from the content url.

Because this search consults all manifests, it normally requires to download all manifests for bundles that are not installed, and may result in the download of several mega bytes of manifest data.

-V <version>, --version=<version>

Search for a match of the given file in the specified version version.

-l, --library

Restrict search to designated dynamic shared library paths.

-B, --binary

Restrict search to designated program binary paths.

-T <num_results>, --top=<num_results>

Only display the top specified number of results for each bundle.

-m, --csv

Output the search results in a machine readable CSV format.

-i, --init

Just perform the collection and download of all required manifest resources needed to perform the search, then exit.

-o <order>, --order=<order>

Sort the output in one of two ways:

  • Use ‘alpha’ to order alphabetically (default)

  • Use ‘size’ to order by bundle size (smaller to larger)

diagnose

Perform system software installation verification. The program will obtain all the manifests needed from version url and content url to establish whether the system software is correctly installed and not overwritten, modified, missing or otherwise incorrect (permissions, etc.).

After obtaining the proper resources, all files that are under control of the software update program are verified according to the manifest data

-V <version>, --version=<version>

Diagnose against the specified manifest VERSION.

-x, --force

Attempt to proceed even if non-critical errors found.

-q, --quick

Omit checking hash values. Instead only looks for missing files and directories and/or symlinks.

-B <bundles>, --bundles=<bundles>

Forces swupd to only diagnose the (comma separated) list of bundles provided.

Examples:

  • --bundles xterm,vim

    Diagnoses only bundles xterm and vim.

-Y, --picky

Also list files which should not exist. Only files listed in the manifests should exist. By default swupd only looks for these files at /usr, this path can be changed using --picky-tree. Some paths at /usr are skipped by default: /usr/lib/modules, /usr/lib/kernel, /usr/local and /usr/src. These paths can be changed using --picky-whitelist.

-X <path>, --picky-tree=<path>

Changes the path where --picky and --extra-files-only looks for extra files. To be specified as absolute PATH. The default path is /usr.

-w <regex>, --picky-whitelist=<regex>

Any path matching the POSIX extended regular expression regex is ignored by --picky. The given expression is always wrapped in ^( and )$ and thus has to match the entire path. Matched directories get skipped completely.

The default is to ignore /usr/lib/kernel, /usr/lib/modules, /usr/src and /usr/local.

Examples:

  • /var|/etc/machine-id

    Ignores /var or /etc/machine-id, regardless of whether they are directories or something else. In the usual case that /var is a directory, also everything inside it is ignored because the directory gets skipped while scanning the directory tree.

  • empty string or ^$

    Matches nothing, because paths are never empty.

--extra-files-only

Like --picky, but it only looks for extra files. It omits checking hash values, and for missing files, directories and/or symlinks.

--file

Forces swupd to only diagnose the specified file or directory (recursively).

repair

Correct any issues found. This will overwrite incorrect file content, add missing files and do additional corrections, permissions, etc.

-V <version>, --version=<version>

Repair against the specified manifest version.

-x, --force

Attempt to proceed even if non-critical errors found.

-q, --quick

Omit repairing corrupt files. Instead only add missing files and directories and/or symlinks.

-B <bundles>, --bundles=<bundles>

Forces swupd to only repair the (comma separated) list of bundles provided.

Examples:

  • --bundles xterm,vim

    Repairs only bundles xterm and vim.

-Y, --picky

Also removes files which should not exist. Only files listed in the manifests should exist. By default swupd only looks for these files at /usr, this path can be changed using --picky-tree. Some paths at /usr are skipped by default: /usr/lib/modules, /usr/lib/kernel, /usr/local and /usr/src. These paths can be changed using --picky-whitelist.

-X <path>, --picky-tree=<path>

Changes the path where --picky and --extra-files-only looks for extra files. To be specified as absolute PATH. The default path is /usr.

-w <regex>, --picky-whitelist=<regex>

Any path matching the POSIX extended regular expression regex is ignored by --picky. The given expression is always wrapped in ^( and )$ and thus has to match the entire path. Matched directories get skipped completely.

The default is to ignore /usr/lib/kernel, /usr/lib/modules, /usr/src and /usr/local.

Examples:

  • /var|/etc/machine-id

    Ignores /var or /etc/machine-id, regardless of whether they are directories or something else. In the usual case that /var is a directory, also everything inside it is ignored because the directory gets skipped while scanning the directory tree.

  • empty string or ^$

    Matches nothing, because paths are never empty.

--extra-files-only

Like --picky, but it only removes extra files. It omits repairing corrupt files, and adding missing files, directories and/or symlinks.

--file

Forces swupd to only repair the specified file or directory (recursively).

os-install

Perform system software installation in the specified location. Install all files into {path} as specified by the swupd os-install {path} option. Useful to generate a new system root. The only bundle that will be installed by default is os-core unless more bundles are specified with the --bundles option.

-V <version>, --version=<version>

Install the specified version of the OS.

-x, --force

Attempt to proceed even if non-critical errors found.

-B <bundles>, --bundles=<bundles>

Include the (comma separated) list of bundles with the base OS install.

Examples:

  • --bundles xterm,vim

    Installs bundles xterm and vim, along with os-core (installed by default).

-s <path>, --statedir-cache=<path>

After checking for content in the statedir, check the statedir-cache before downloading it over the network.

--download

Do not perform an install, instead download all resources needed to perform the install, and exit.

--skip-optional

Do not install optional bundles (also-add flag in Manifests). A bundle may include other bundles that will also get installed when installing the bundle that includes them. This included bundles can be either optional, or mandatory. Optional bundles can be skipped at install time by using this option.

mirror

Configure a mirror URL for swupd to use instead of the defaults on the system or compiled into the swupd binary.

-s <url>, --set=<url>

Set the content and version URLs to URL by adding configuration files to <path>/etc/swupd/mirror_contenturl and <path>/etc/swupd/mirror_versionurl

-U, --unset

Remove the content and version URL configuration by removing <path>/etc/swupd

clean

Removes files cached by swupd.

Note that removing these files may cause swupd to perform slower the next time it is used since it may need to download some files from the update server again.

--all
Removes all the content including recent metadata.
--dry-run

Just prints files that would be removed.

hashdump

Calculates and print the Manifest hash for a specific file on disk.

-n, --no-xattrs

Ignore extended attributes when calculating hash.

-p <path>, --path=<path>

Specify the PATH to use for operations. This can be used to point to a chroot installation of the OS or a custom mount.

3rd-party

Manages 3rd-party repositories and content installed from them. A 3rd-party repository enables the distribution of user produced content.

The following subcommands are available to manage 3rd-party repositories:

  • add

    Adds a 3rd-party repository.

    • force

    Attempt to proceed with the removal of the repo even if non-critical errors found.

  • remove

    Removes a 3rd-party repository along with all the content installed from it from the system.

    • force

    Attempt to proceed with the removal of the repo even if non-critical errors found.

  • list

    Lists the 3rd-party repositories available to the system. These repositories must have been previously added using swupd 3rd-party add.

Most of the swupd subcommands used for managing upstream content are supported to manage 3rd-party content along with most of their options. To use these subcommands for 3rd-party content, it is necessary to use the 3rd-party subcommand followed by the desired operation to be performed.

This is the syntax for 3rd-party operations to manage content:

$ swupd 3rd-party <subcommand> [option(s)]

Example:

  • swupd 3rd-party bundle-add my_bundle

    Looks for the 3rd-party bundle my_bundle among all the available 3rd-party repositories, and installs it in the system as long as it is found in one, and only one, repository. If the bundle exists in more than one 3rd-party repository, users are required to specify the repository to install it from by using the --repo option.

    There is no need to specify the 3rd-party repository if the bundle name is unique among 3rd-party repositories, even if a bundle with the same name exists in the upstream update server. Bundles from 3rd-party repositories are installed in a different location so they don’t clash with upstream bundles.

  • swupd 3rd-party update --repo my_repo

    Performs a software update for content installed from the 3rd-party repository my_repo. If no repository is specified, content from all 3rd-party repositories is updated.

All 3rd-party content is installed in the following location: /opt/3rd-party/<bundle_name>/

The following subcommands are available to manage 3rd-party content:

  • update

    Update to latest version of a 3rd-party repository. For information about the options for this command please refer to the swupd update section.

  • bundle-add

    Installs a bundle from a 3rd-party repository. For information about the options for this command please refer to the swupd bundle-add section.

  • bundle-remove

    Remove a bundle from a 3rd-party repository. For information about the options for this command please refer to the swupd bundle-remove section.

  • bundle-list

    List bundles from a 3rd-party repository. For information about the options for this command please refer to the swupd bundle-list section.

  • bundle-info

    Display information about a bundle in a 3rd-party repository. For information about the options for this command please refer to the swupd bundle-info section.

  • diagnose

    Verify content from a 3rd-party repository. For information about the options for this command please refer to the swupd diagnose section.

  • repair

    Repair local issues relative to a 3rd-party repository. For information about the options for this command please refer to the swupd repair section.

  • check-update

    Check if a new version of a 3rd-party repository is available. For information about the options for this command please refer to the swupd check-update section.

  • clean

    Clean cached files of a 3rd-party repository. For information about the options for this command please refer to the swupd clean section.

FILES

/usr/share/defaults/swupd

Sometimes a set of flags is always used for one, or many swupd commands. The swupd configuration file provides a convenient way of persistently define these flags so they don’t need to be specified every time a command is run.

The configuration file is an INI type of file that consists of sections, each led by a [section] header, followed by key/value entries separated by a ‘=’ character. Note that there should be no whitespace between key=value. The configuration file may include comments, prefixed by either the ‘#’ or the ‘;’ characters.

There can be one section for each swupd command (e.g. [bundle-add], [update], etc.) and one for global options (e.g. [GLOBAL]). Global options can be specified in the either in the GLOBAL section, in a command section, or in both. Global options specified in the command section have higher precedence than those specified in the GLOBAL section, so it is possible to define a GLOBAL option that will apply to all swupd command except for that one overwritten in the command section.

A sample swupd configuration file can be found at this location (this file should not be modified): /usr/share/defaults/swupd

To use it, copy it to /etc/swupd where swupd reads the configuration from.

EXIT STATUS

On success, 0 is returned. A non-zero return code signals a failure.

If the subcommand check-update was specified, the program returns 0 if an update is available, 1 if no update available, and a return value higher than 1 signals a failure.

If the subcommand was autoupdate without options, then the program returns 0 if automatic updating is enabled.

If the subcommand was diagnose, then the program returns 0 if the system is consistent at the end of the process or 1 if there are invalid/missing files in the system.

The non-zero return codes for other operations are listed here:

2 A required bundle was removed or was attempted to be removed

3 The specified bundle is invalid
4 Unable to download or read MoM manifest
5 Unable to delete a file
6 Unable to rename a directory
7 Unable to create a file
8 Unable to recursively load included manifests
9 Unable to obtain lock on state directory
10 Unable to rename a file
11 Unable to initialize curl agent
12 Initialization error
13 Bundle not tracked on system
14 Unable to load manifest into memory
15 Invalid command-line option
16 Unable to connect to update server
17 File download issue
18 Unable to untar a file
19 Unable to create required directory
20 Unable to determine current version of the OS
21 Unable to initialize signature verification
22 System time is off by a large margin
23 Pack download issue
24 Unable to verify server SSL certificate
25 There is not enough disk space left (or it cannot be determined)
26 The required path was not found in any manifest
27 Unexpected condition found
28 Unable to execute another program in a subprocess
29 Unable to list the content of a directory
30 An error occurred computing the hash of a file
31 Unable to get current system time
32 Unable to write a file
34 swupd ran out of memory
35 Unable to fix/replace/delete one or more files
36 Unable to execute binary, is either missing or invalid
37 Invalid 3rd-party repository (not found)
38 File is missing or invalid

SEE ALSO

swupd-update.service(4), swupd-update.timer(4), update-triggers.target(4), mixer(1), os-format(7)
Official repository https://github.com/clearlinux/swupd-client/
Official documentation https://clearlinux.org/documentation/