=====
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) <swupd.1.html>`__ 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) <mixer.1.html>`__ and `os-format(7) <os-format.7.html>`__.

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) <update-triggers.target.4.html>`__ 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
------

    Swupd search functionality is provided by the 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.

-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.service.4.html>`__,  `swupd-update.timer(4) <swupd-update.timer.4.html>`__,  `update-triggers.target(4) <update-triggers.target.4.html>`__,  `mixer(1) <mixer.1.html>`__,  `os-format(7) <os-format.7.html>`__

| Official repository     https://github.com/clearlinux/swupd-client/
| Official documentation  https://clearlinux.org/documentation/
