swupd.1.rst

swupd

OS software update program

Copyright:	(C) 2019 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).

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.

• -u, --url={url}

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

• -c, --contenturl={url}

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

• -v, --versionurl={url}

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

• -P, --port={port}

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

• -p, --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 /.

• -F, --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, --statedir={path}

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

• -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.

• -n, --nosigcheck

  Do not attempt to enforce certificate or signature checking.

• -I, --ignore-time

  Ignore system/certificate time when validating signature.

• -C, --certpath

  Specify alternate path to swupd certificates.

• -t, --time

  Show verbose time output for swupd operations.

• -W, --max-parallel-downloads

  Set the maximum number of parallel downloads.

• -r, --max-retries

  Maximum number of retries for download failures.

• -d, --retry-delay

  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.

• -j, --json-output

  Prints the swupd output as a machine readable JSON stream.

• --quiet

  Print only important information and errors.

• --debug

  Print extra information to help debugging problems.

• --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.

  Important note: 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.

• --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.

SUBCOMMANDS

autoupdate [--enable|--disable]

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.

bundle-add {bundles}

Installs new software bundles. Any bundle name listed after bundle-list --all will be downloaded and installed.

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-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.

• --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.

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.

bundle-list

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

• -a, --all

  Lists all available software bundles, either installed or not, that are available. It will return 0 with succeeded and a different value of 0 with failed.

• --deps={bundle}

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

• -D, --has-dep={bundle}

  Displays a tree 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.

check-update

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

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=[VER]

  Diagnose against manifest version VER.

• -Y, --picky

  Also list files which should not exist. Only files listed in the manifests should exist.

• -X, --picky-tree=[PATH]

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

• -w, --picky-whitelist=[RE]

  Any path matching the POSIX extended regular expression 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.

• -q, --quick

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

• -x, --force

  Attempt to proceed even if non-critical errors found.

• --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.

hashdump {path}

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

• -n --no-xattrs

  Ignore extended attributes when calculating hash.

• -p, --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.

info

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

mirror

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

• -s, --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

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.

• -V, --version

  Install OS version V.

• -x, --force

  Attempt to proceed even if non-critical errors found.

• -B, --bundles=[BUNDLES]

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

  Examples:

  • --bundles xterm,vi

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

• --download

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

repair

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

• -V, --version=[VER]

  Repair against manifest version VER.

• -Y, --picky

  Also remove files which should not exist. Only files listed in the manifests should exist.

• -X, --picky-tree=[PATH]

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

• -w, --picky-whitelist=[RE]

  Any path matching the POSIX extended regular expression 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.

• -q, --quick

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

• -x, --force

  Attempt to proceed even if non-critical errors found.

• --extra-files-only

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

search

Swupd search functionality is provided by swupd-search binary available on os-core-search bundle. For more information run:

$ swupd search --help

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.

• -l, --library

  Restrict search to designated dynamic shared library paths.

• -B, --binary

  Restrict search to designated program binary paths.

• -i, --init

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

• -T, --top

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

• -m, --csv

  Output the search results in a machine readable CSV format.

• -o, --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)

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 verify --fix 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

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

• -m, --manifest

  Update to a specific version. This flag has been superseded. Please use -V instead.

• -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.

• --download

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

• -T, --migrate

  Perform an update to the local user mix content, enabling swupd to use content from both upstream, and the local system.

• -a, --allow-mix-collisions

  Ignore and continue if custom user content conflicts with upstream provided content.

• -k, --keepcache

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

verify

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.

NOTE: This command has been superseded, please consider using "swupd diagnose" instead.

• -V, --version

  Verify against a specific version.

• -m, --manifest

  Verify against a specific version. This flag has been superseded. Please use -V instead.

• -f, --fix

  Correct any issues found. This will overwrite incorrect file content, add missing files and do additional corrections, permissions etc. This option has been superseded, please consider using "swupd repair" instead.

• -Y, --picky

  Also List files which should not exist. Only files listed in the manifests should exist. If the flag is used along with --fix, it removes these files.

• -X, --picky-tree=[PATH]

  Selects the sub-tree where --picky looks for extra files. To be specified as absolute path. The default is /usr.

• -w, --picky-whitelist=[RE]

  Any path matching the POSIX extended regular expression 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.

• -i, --install

  Install all files into {path} as specified by the --path={path} option. Useful to generate a new system root, or verify side by side. This option has been superseded, please consider using "swupd os-install" instead.

• -q, --quick

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

• -x, --force

  Attempt to proceed even if non-critical errors found.

• -B, --bundles=[BUNDLES]

  Forces swupd to only consider the (comma separated) list of BUNDLES for verify.

  Examples:

  • --bundles os-core,vi

    Only runs the verify operation on the os-core and vi bundles.

• --extra-files-only

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

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
• 33: Collisions found between a mix and upstream
• 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

SEE ALSO

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