swupd-client/docs/swupd.1

.\" Man page generated from reStructuredText.
.
.TH SWUPD 1 "" "" ""
.SH NAME
swupd \- OS software update program
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBswupd [subcommand] <flags>\fP
.SH DESCRIPTION
.sp
\fBswupd\fP(1) is an OS\-level software update program that applies updates
to system software.
.sp
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.
.sp
The \fBswupd\fP tool can also install and remove bundles, check for
updates without applying them, and perform system\-level verification of
the system software.
.sp
A \fIversion url\fP server provides version information. This server
notifies the program of available updates.
.sp
A \fIcontent url\fP server (can be the same as \fIversion url\fP 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.
.SH OPTIONS
.sp
The following options are applicable to most subcommands, and can be
used to modify the core behavior and resources that swupd uses.
.INDENT 0.0
.IP \(bu 2
\fB\-h, \-\-help\fP
.sp
Display general help information. If put after a subcommand, it will
display help specific to that subcommand.
.IP \(bu 2
\fB\-v, \-\-version\fP
.sp
Displays the version information of the swupd program, and exit. It also
displays compile options and copyright information.
.IP \(bu 2
\fB\-u, \-\-url={url}\fP
.sp
Specify an RFC\-3986 encoded url. The url will be used to download
version information and file content downloads.
.IP \(bu 2
\fB\-c, \-\-contenturl={url}\fP
.sp
Specify an RFC\-3986 encoded url. The url will be used for file
content downloads only.
.IP \(bu 2
\fB\-v, \-\-versionurl={url}\fP
.sp
Specify an RFC\-3986 encoded url. The url will be used to download
version information.
.IP \(bu 2
\fB\-P, \-\-port={port}\fP
.sp
Specify the port number of the server to connect to. Applies to both
version and file content url server connections.
.IP \(bu 2
\fB\-p, \-\-path={path}\fP
.sp
Specify the path to use for operations. This can be used to point to
a chroot installation of the OS or a custom mount.
.IP \(bu 2
\fB\-F, \-\-format={formatstring}\fP
.sp
Specify the format suffix for version file downloads. Is usually one
of \fB1\fP, \fB2\fP, \fB3\fP, etc. or \fBstaging\fP\&. 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 \fBswupd\fP, you should subtract \fB1\fP
from the number and try again until it succeeds.
.IP \(bu 2
\fB\-f, \-\-force\fP
.sp
Forces completion of swupd beyond critical failures. This may ignore
filesystem errors, configuration errors and other errors which are
considered fatal, and could damage an installation if not addressed
properly.
.IP \(bu 2
\fB\-S, \-\-statedir={path}\fP
.sp
Specify an alternate swupd state directory. Normally \fBswupd\fP uses
\fB/var/lib/swupd\fP\&.
.IP \(bu 2
\fB\-N, \-\-no\-scripts\fP
.INDENT 2.0
.INDENT 3.5
Do not run the post\-update scripts and boot update tool.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fB\-b, \-\-no\-boot\-update\fP
.INDENT 2.0
.INDENT 3.5
Do not update the boot files using clr\-boot\-manager
.UNINDENT
.UNINDENT
.IP \(bu 2
\fB\-n, \-\-nosigcheck\fP
.INDENT 2.0
.INDENT 3.5
Do not attempt to enforce certificate or signature checking
.UNINDENT
.UNINDENT
.IP \(bu 2
\fB\-I, \-\-ignore\-time\fP
.INDENT 2.0
.INDENT 3.5
Ignore system/certificate time when validating signature
.UNINDENT
.UNINDENT
.IP \(bu 2
\fB\-C, \-\-certpath\fP
.INDENT 2.0
.INDENT 3.5
Specify alternate path to swupd certificates
.UNINDENT
.UNINDENT
.IP \(bu 2
\fB\-t, \-\-time\fP
.INDENT 2.0
.INDENT 3.5
Show verbose time output for swupd operations
.UNINDENT
.UNINDENT
.UNINDENT
.SH SUBCOMMANDS
.sp
\fBautoupdate [\-\-enable|\-\-disable]\fP
.INDENT 0.0
.INDENT 3.5
Enables or disables automatic updates, or reports current
status. Enabling updates does not cause an immediate update \-
use \fIswupd update\fP to force one if desired.
.UNINDENT
.UNINDENT
.sp
\fBbundle\-add {bundles}\fP
.INDENT 0.0
.INDENT 3.5
Installs new software bundles. Any bundle name listed after
\fIbundle\-list \-\-all\fP will be downloaded and installed.
.INDENT 0.0
.IP \(bu 2
\fI\-\-skip\-diskspace\-check\fP
.INDENT 2.0
.INDENT 3.5
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 \(aq/usr/\(aq by default,
or it will check the passed in \-\-path option with \(aq/usr/\(aq appended.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBbundle\-remove {bundles}\fP
.INDENT 0.0
.INDENT 3.5
Removes software bundles. Any bundle name listed after \fIbundle\-remove\fP
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.
.UNINDENT
.UNINDENT
.sp
\fBbundle\-list\fP
.INDENT 0.0
.INDENT 3.5
List all installed sofware bundles in the local system. Bundles available
can be listed with the \fI\-\-all\fP option.
.INDENT 0.0
.IP \(bu 2
\fI\-a, \-\-all\fP
.INDENT 2.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-d, \-\-deps={bundle}\fP
.INDENT 2.0
.INDENT 3.5
Lists all bundle dependencies of the passed bundle, including
recursively included bundles.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-D, \-\-has\-dep={bundle}\fP
.INDENT 2.0
.INDENT 3.5
Displays a tree of all bundles which include the passed bundle as a
dependency. Combine with \fI\-\-all\fP to report all bundles including those
not installed on the system.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBcheck\-update\fP
.INDENT 0.0
.INDENT 3.5
Checks whether an update is available and prints out the information
if so. Does not download update content.
.UNINDENT
.UNINDENT
.sp
\fBhashdump {path}\fP
.INDENT 0.0
.INDENT 3.5
Calculates and print the Manifest hash for a specific file on disk.
.INDENT 0.0
.IP \(bu 2
\fI\-n \-\-no\-xattrs\fP
.INDENT 2.0
.INDENT 3.5
Ignore extended attributes when calculating hash.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-p, \-\-path={path}\fP
.INDENT 2.0
.INDENT 3.5
Specify the path to use for operations. This can be used to
point to a chroot installation of the OS or a custom mount.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBinfo\fP
.INDENT 0.0
.INDENT 3.5
Shows the current OS version and the URLs used for updates.
.UNINDENT
.UNINDENT
.sp
\fBmirror\fP
.INDENT 0.0
.INDENT 3.5
Configure a mirror URL for swupd to use instead of the defaults on the
system or compiled into the swupd binary.
.INDENT 0.0
.IP \(bu 2
\fI\-s, \-\-set URL\fP
.INDENT 2.0
.INDENT 3.5
Set the content and version URLs to URL by adding configuration files to
<path>/etc/swupd/mirror_contenturl and
<path>/etc/swupd/mirror_versionurl
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-u, \-\-unset\fP
.INDENT 2.0
.INDENT 3.5
Remove the content and version URL configuration by removing
<path>/etc/swupd
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-p, \-\-path\fP
.INDENT 2.0
.INDENT 3.5
Optionally set the top\-level directory for the swupd\-managed system.
If not specified this will default to \(aq/\(aq
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBsearch {string}\fP
.INDENT 0.0
.INDENT 3.5
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.
.sp
If manifest data is not present in the state folder, it is
downloaded from the content url.
.sp
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.
.INDENT 0.0
.IP \(bu 2
\fI\-l, \-\-library\fP
.INDENT 2.0
.INDENT 3.5
Restrict search to designated dynamic shared library paths.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-b, \-\-binary\fP
.INDENT 2.0
.INDENT 3.5
Restrict search to designated program binary paths.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-i, \-\-init\fP
.INDENT 2.0
.INDENT 3.5
Perform collection and download of all required manifest
resources needed to perform the search, then exit.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-d, \-\-display\-files\fP
.INDENT 2.0
.INDENT 3.5
Do not search for any particular string, instead, print out all
files, paths, etc. listed in any manifest, and exit.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-s, \-\-scope={b|o}\fP
.INDENT 2.0
.INDENT 3.5
Restrict search to only list the first match found in \fBbundle\fP
or \fBos\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBupdate\fP
.INDENT 0.0
.INDENT 3.5
Performs a system software update.
.sp
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 \fI/var/lib/swupd\fP state path. Once all content
is downloaded and verified, the update is applied to the system.
.sp
In case any problem arises during a software update, the program
attempts to correct the issue, possibly by performing a \fIswupd verify \-\-fix\fP
operation, which corrects broken or missing files and other issues.
.sp
After the update is applied, the system performs an array of
post\-update actions. These actions are triggered through \fIsystemd(1)\fP
and reside in the \fIupdate\-triggers.target(4)\fP system target.
.INDENT 0.0
.IP \(bu 2
\fI\-m, \-\-manifest\fP
.INDENT 2.0
.INDENT 3.5
Update to a specific version, also accepts \(aqlatest\(aq (default).
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-s, \-\-status\fP
.INDENT 2.0
.INDENT 3.5
Do not perform an update, instead display whether an update is
available on the version url server, and what version number is
available.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-d, \-\-download\fP
.INDENT 2.0
.INDENT 3.5
Do not perform an update, instead download all resources needed
to perform the update, and exit.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-T, \-\-migrate\fP
.INDENT 2.0
.INDENT 3.5
Perform an update to the local user mix content, enabling swupd to
use content from both upstream, and the local system.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-a, \-\-allow\-mix\-collisions\fP
.INDENT 2.0
.INDENT 3.5
Ignore and continue if custom user content conflicts with upstream
provided content.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBverify\fP
.INDENT 0.0
.INDENT 3.5
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.).
.sp
After obtaining the proper resources, all files that are under
control of the software update program are verified according to the
manifest data
.INDENT 0.0
.IP \(bu 2
\fI\-m, \-\-manifest\fP
.INDENT 2.0
.INDENT 3.5
Verify against manifest version M.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-f, \-\-fix\fP
.INDENT 2.0
.INDENT 3.5
Correct any issues found. This will overwrite incorrect file
content, add missing files and do additional corrections, permissions
etc.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-Y, \-\-picky\fP
.INDENT 2.0
.INDENT 3.5
List (without \-\-fix) or remove (with \-\-fix) files which should
not exist. Only files listed in the manifests should exist.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-X, \-\-picky\-tree=[PATH]\fP
.INDENT 2.0
.INDENT 3.5
Selects the sub\-tree where \-\-picky looks for extra files. To be
specified as absolute path. The default is \fI/usr\fP\&.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-w, \-\-picky\-whitelist=[RE]\fP
.INDENT 2.0
.INDENT 3.5
Any path matching the POSIX extended regular expression is
ignored by \-\-picky. The given expression is always wrapped
in \fB^(\fP and \fB)$\fP and thus has to match the entire path.
Matched directories get skipped completely.
.sp
The default is to ignore \fB/usr/lib/kernel\fP,
\fB/usr/lib/modules\fP, and \fB/usr/local\fP\&.
.sp
Examples:
.INDENT 0.0
.IP \(bu 2
\fB/var|/etc/machine\-id\fP
.INDENT 2.0
.INDENT 3.5
Ignores \fB/var\fP or \fB/etc/machine\-id\fP, regardless of
whether they are directories or something else. In the
usual case that \fB/var\fP is a directory, also everything
inside it is ignored because the directory gets skipped
while scanning the directory tree.
.UNINDENT
.UNINDENT
.IP \(bu 2
empty string or \fB^$\fP
.INDENT 2.0
.INDENT 3.5
Matches nothing, because paths are never empty.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-i, \-\-install\fP
.INDENT 2.0
.INDENT 3.5
Install all files into {path} as specified by the \fI\-\-path={path}\fP
option. Useful to generate a new system root, or verify side
by side.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-q, \-\-quick\fP
.INDENT 2.0
.INDENT 3.5
Omit checking hash values. Instead only corrects missing files
and directories and/or symlinks.
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\-x, \-\-force\fP
.INDENT 2.0
.INDENT 3.5
Attempt to proceed even if non\-critical errors found.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH EXIT STATUS
.sp
On success, 0 is returned. A non\-zero return code signals a failure.
.sp
If the subcommand \fBcheck\-update\fP was specified, the program returns
\fB0\fP if an update is available, \fB1\fP if no update available, and a
return value higher than \fB1\fP signals a failure.
.sp
If the subcommand was \fBautoupdate\fP without options, then the program
returns \fB0\fP if automatic updating is enabled.
.sp
The non\-zero return codes for other operations are listed here:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fB2\fP: At least one local bundle could not be found in the MoM manifest
.IP \(bu 2
\fB3\fP: Unable to delete bundle
.IP \(bu 2
\fB4\fP: Unable to download or read MoM manifest
.IP \(bu 2
\fB5\fP, \fB6\fP, \fB7\fP: File staging error
.IP \(bu 2
\fB8\fP: Unable to recursively load included manifests
.IP \(bu 2
\fB9\fP: Unable to obtain lock on state directory
.IP \(bu 2
\fB11\fP: Unable to initialize curl agent
.IP \(bu 2
\fB12\fP: Initialization error
.IP \(bu 2
\fB13\fP: Bundle not tracked on system
.IP \(bu 2
\fB14\fP: Unable to load manifest into memory
.IP \(bu 2
\fB15\fP: Invalid command\-line option
.IP \(bu 2
\fB16\fP: Unable to connect to update server
.IP \(bu 2
\fB16\fP, \fB17\fP, \fB404\fP: File download issue
.IP \(bu 2
\fB18\fP: Unable to install bundles
.IP \(bu 2
\fB19\fP: Unable to create required directories
.IP \(bu 2
\fB20\fP: Unable to determine current version of the OS
.IP \(bu 2
\fB21\fP: Unable to initialize signature verification
.IP \(bu 2
\fB22\fP: System time is off by a large margin
.IP \(bu 2
\fB23\fP: Pack download issue
.IP \(bu 2
\fB24\fP: Unable to verify server SSL certificate
.UNINDENT
.UNINDENT
.UNINDENT
.SS SEE ALSO
.INDENT 0.0
.IP \(bu 2
\fBcheck\-update.service\fP(4)
.IP \(bu 2
\fBcheck\-update.timer\fP(4)
.IP \(bu 2
\fBswupd\-update.service\fP(4)
.IP \(bu 2
\fBswupd\-update.timer\fP(4)
.IP \(bu 2
\fBupdate\-triggers.target\fP(4)
.IP \(bu 2
\fI\%https://github.com/clearlinux/swupd\-client/\fP
.IP \(bu 2
\fI\%https://clearlinux.org/documentation/\fP
.UNINDENT
.SH COPYRIGHT
(C) 2017 Intel Corporation, CC-BY-SA-3.0
.\" Generated by docutils manpage writer.
.