cdd3227f70
Very often when I have a pending deployment, I just want to find out
what the diff is before rebooting. We do print it after whatever
transaction laid down the new deployment, though we may not reboot right
away. It seems like a common enough operation to warrant some shortcuts.
This makes `db diff` more useful by automatically subbing in the booted
deployment if less arguments are given:
rpm-ostree db diff
<diff booted and pending deployment>
rpm-ostree db diff $csum
<diff booted and $csum>
rpm-ostree db diff $csum1 $csum2
<as before, diff $csum1 and $csum2>
As before, we never try to even load the sysroot in the last invocation,
so it still works equally well on non-OSTree systems/unprivileged.
Closes: #1294
Approved by: cgwalters
642 lines
22 KiB
XML
642 lines
22 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
Copyright 2011,2013,2014 Colin Walters <walters@verbum.org>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library; if not, write to the
|
|
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
Boston, MA 02111-1307, USA.
|
|
-->
|
|
|
|
<refentry id="rpm-ostree">
|
|
|
|
<refentryinfo>
|
|
<title>rpm-ostree</title>
|
|
<productname>rpm-ostree</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Jonathan</firstname>
|
|
<surname>Lebon</surname>
|
|
<email>jlebon@redhat.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Colin</firstname>
|
|
<surname>Walters</surname>
|
|
<email>walters@redhat.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>rpm-ostree</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>rpm-ostree</refname>
|
|
<refpurpose>
|
|
Hybrid image/package system for host operating system updates
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>rpm-ostree</command>
|
|
<arg choice="req">COMMAND</arg>
|
|
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
rpm-ostree is a hybrid image and package system; as the name suggests, it
|
|
uses OSTree for the image side, and RPM for the package side. It supports
|
|
composing RPMs server-side into an OSTree commit (like an image), and
|
|
clients can replicate that bit-for-bit, with fast incremental updates.
|
|
Additionally, the hybrid nature comes to the fore with client-side package
|
|
layering and overrides.
|
|
</para>
|
|
|
|
<para>
|
|
On an rpm-ostree managed system, the traditional
|
|
<literal>yum</literal> (if installed) and <literal>rpm</literal>
|
|
tools operate in a read-only state; the RPM database is stored
|
|
in <literal>/usr/share/rpm</literal> which is underneath a
|
|
read-only bind mount.
|
|
</para>
|
|
|
|
<para>
|
|
Instead of live package-by-package upgrades, the underlying
|
|
OSTree layer replicates a complete filesystem tree from a
|
|
compose server into a new deployment, available on the next
|
|
reboot. One benefit of this is that there will always be a
|
|
previous deployment, available for rollback. This also
|
|
makes it easier to reliably "queue" an update without destabilizing
|
|
the running system at all. (Currently though there's an experimental
|
|
<literal>livefs</literal> command that supports changing the
|
|
running filesystem).
|
|
</para>
|
|
|
|
<para>
|
|
Note in this "pure replication" model, there is no per-client
|
|
packaging overhead. Dependency resolution, SELinux labeling,
|
|
all of the scripts etc. were run on the server side and captured
|
|
in the OSTree commit.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Client side commands</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><command>cancel</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Cancel a pending transaction. Exits successfully and does
|
|
nothing if no transaction is running. Note that it is fully
|
|
safe to cancel transactions such as <command>upgrade</command>
|
|
in general.
|
|
</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>db</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Gives information pertaining to <literal>rpm</literal> data
|
|
within the file system trees within the ostree commits.
|
|
There are three sub-commands:
|
|
</para>
|
|
|
|
<para>
|
|
<command>diff</command> to see how the packages are
|
|
different between the trees in two revs. If no revs are
|
|
provided, the booted commit is compared to the pending
|
|
commit. If only a single rev is provided, the booted commit
|
|
is compared to that rev. The
|
|
<option>--format=diff</option> option uses
|
|
<literal>-</literal> for removed packages,
|
|
<literal>+</literal> for added packages, and finally
|
|
<literal>!</literal> for the old version of an updated
|
|
package, with a following <literal>=</literal> for the new
|
|
version.
|
|
</para>
|
|
|
|
<para>
|
|
<command>list</command> to see which packages are within the
|
|
commit(s) (works like yum list). At least one commit must be
|
|
specified, but more than one or a range will also work.
|
|
</para>
|
|
|
|
<para>
|
|
<command>version</command> to see the rpmdb version of the
|
|
packages within the commit (works like yum version
|
|
nogroups). At least one commit must be specified, but more
|
|
than one or a range will also work.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>deploy</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Takes version, branch, or commit ID as an argument, and
|
|
creates a new deployment using it, setting it up as the
|
|
default for the next boot. Unlike most other commands, this
|
|
will automatically fetch and traverse the origin history to
|
|
find the target. By design, this has no effect on your
|
|
running filesystem tree. You must reboot for any changes to
|
|
take effect.
|
|
</para>
|
|
|
|
<para>
|
|
In addition to exit status 0 for success and 1 for error,
|
|
this command also uses exit status 77 to indicate that the
|
|
system is already on the specified commit. This tristate
|
|
return model is intended to support idempotency-oriented
|
|
systems automation tools like Ansible.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--reboot</command> or <command>-r</command> to
|
|
initiate a reboot after the upgrade is prepared.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--preview</command> download enough metadata to
|
|
inspect the RPM diff, but do not actually create a new
|
|
deployment.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--cache-only</option> or <command>-C</command> to
|
|
perform the operation without trying to download the target
|
|
tree from the remote nor the latest packages.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--download-only</option> to only download the target
|
|
ostree and layered RPMs without actually performing the
|
|
deployment. This can be used with a subsequent
|
|
<option>--cache-only</option> invocation to perform the
|
|
operation completely offline.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>install</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Takes one or more packages as arguments. The packages are
|
|
fetched from the enabled repositories in
|
|
<filename>/etc/yum.repos.d/</filename> and are overlayed on
|
|
top of a new deployment.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--reboot</command> or <command>-r</command> to
|
|
initiate a reboot after the deployment is prepared.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--dry-run</command> or <command>-n</command> to
|
|
exit after printing the transaction rather than downloading
|
|
the packages and creating a new deployment.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--cache-only</option> or <command>-C</command> to
|
|
perform the operation without trying to download the latest
|
|
packages.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--download-only</option> to only download the target
|
|
layered RPMs without actually performing the deployment.
|
|
This can be used with a subsequent
|
|
<option>--cache-only</option> invocation to perform the
|
|
operation completely offline.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>uninstall</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Takes one or more packages as arguments. The packages are
|
|
removed from the set of packages that are currently
|
|
overlayed. The remaining packages in the set (if any) are
|
|
fetched from the enabled repositories in
|
|
<filename>/etc/yum.repos.d/</filename> and are overlayed on
|
|
top of a new deployment.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--reboot</command> or <command>-r</command> to
|
|
initiate a reboot after the deployment is prepared.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--dry-run</command> or <command>-n</command> to
|
|
exit after printing the transaction rather than downloading
|
|
the packages and creating a new deployment.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>override</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
<command>remove</command> Remove a package from the base
|
|
tree. Note that this is similar to layering in that
|
|
the original base is retained.
|
|
</para>
|
|
|
|
<para>
|
|
<command>replace</command> Replace a package in the base tree.
|
|
</para>
|
|
|
|
<para>
|
|
<command>reset</command> Undo a <literal>remove</literal> or
|
|
<literal>replace</literal> operation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>rebase</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Switch to a different branch (possibly using a new remote),
|
|
while preserving all of the state that <command>upgrade</command>
|
|
does, such as <literal>/etc</literal> changes, any layered RPM
|
|
packages, etc.
|
|
</para>
|
|
<para>
|
|
The full syntax is <literal>rebase REMOTENAME:BRANCHNAME</literal>.
|
|
Alternatively, you can use the <command>--branch</command> or
|
|
<command>--remote</command> options mentioned below. With the
|
|
argument syntax, specifying just <literal>BRANCHNAME</literal> will
|
|
reuse the same remote. You may also omit one of
|
|
<literal>REMOTENAME</literal> or <literal>BRANCHNAME</literal>
|
|
(keeping the colon). In the former case, the branch refers to a
|
|
local branch; in the latter case, the same branch will be used on a
|
|
different remote.
|
|
</para>
|
|
<para>
|
|
<command>--branch</command> or <command>-b</command> to
|
|
to pick a branch name.
|
|
</para>
|
|
<para>
|
|
<command>--remote</command> or <command>-m</command> to
|
|
to pick a remote name.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--cache-only</option> or <command>-C</command> to
|
|
perform the rebase without trying to download the target
|
|
tree from the remote nor the latest packages.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--download-only</option> to only download the target
|
|
ostree and layered RPMs without actually performing the
|
|
deployment. This can be used with a subsequent
|
|
<option>--cache-only</option> invocation to perform the
|
|
operation completely offline.
|
|
</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>rollback</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
OSTree manages an ordered list of bootloader entries, called
|
|
"deployments". The entry at index 0 is the default
|
|
bootloader entry. Each entry has a separate
|
|
<filename>/etc</filename>, but they all share a single
|
|
<filename>/var</filename>. You can use the bootloader to
|
|
choose between entries by pressing Tab to interrupt
|
|
startup.
|
|
</para>
|
|
|
|
<para>
|
|
This command then changes the default bootloader entry. If
|
|
the current default is booted, then set the default to the
|
|
previous entry. Otherwise, make the currently booted tree
|
|
the default.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--reboot</command> or <command>-r</command> to
|
|
initiate a reboot after rollback is prepared.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>status</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Gives information pertaining to the current deployment in
|
|
use. Lists the names and refspecs of all possible
|
|
deployments in order, such that the first deployment in the
|
|
list is the default upon boot. The deployment marked with *
|
|
is the current booted deployment, and marking with 'r'
|
|
indicates the most recent upgrade (the newest deployment
|
|
version).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>upgrade</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Download the latest version of the current tree, and deploy
|
|
it, setting it up as the default for the next boot. By
|
|
design, this has no effect on your running filesystem tree.
|
|
You must reboot for any changes to take effect.
|
|
</para>
|
|
|
|
<para>
|
|
In addition to exit status 0 for success and 1 for error,
|
|
this command also uses exit status 77 to indicate that no
|
|
upgrade is available.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--reboot</command> or <command>-r</command> to
|
|
initiate a reboot after upgrade is prepared.
|
|
</para>
|
|
|
|
<para>
|
|
<command>--allow-downgrade</command> to permit deployment of
|
|
chronologically older trees.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--preview</option> to download only /usr/share/rpm
|
|
in order to do a package-level diff between the two
|
|
versions.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--check</option> to just check if an upgrade is
|
|
available, without downloading it or performing a
|
|
package-level diff.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--cache-only</option> or <command>-C</command> to
|
|
perform the upgrade without trying to download the latest
|
|
tree from the remote nor the latest packages.
|
|
</para>
|
|
|
|
<para>
|
|
<option>--download-only</option> to only download the target
|
|
ostree and layered RPMs without actually performing the
|
|
deployment. This can be used with a subsequent
|
|
<option>--cache-only</option> invocation to perform the
|
|
operation completely offline.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>override</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Provides subcommands for overriding (modifying) the base
|
|
OSTree layer. Such modifications should be done with care
|
|
and are normally not intended to be long-lasting. For
|
|
example, one might replace a base package with its older
|
|
version to avoid a regression. Overrides are automatically
|
|
carried over during new deployments. The subcommands are:
|
|
</para>
|
|
|
|
<para>
|
|
<command>remove</command> to remove base packages.
|
|
</para>
|
|
|
|
<para>
|
|
<command>replace</command> to replace base packages.
|
|
Currently, only local RPM replacements are supported:
|
|
one must directly provide the RPMs to substitute in.
|
|
</para>
|
|
|
|
<para>
|
|
<command>reset</command> to reset previous overrides.
|
|
Currently, the full <literal>NEVRA</literal> of the target
|
|
packages must be specified.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>refresh-md</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Download the latest rpm repo metadata if necessary and generate the
|
|
cache.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>cleanup</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Commands such as <command>upgrade</command> create new deployments,
|
|
which affect the next boot, and take up additional storage space. In
|
|
some cases, you may want to undo and clean up these operations. This
|
|
command supports both removing additional deployments such as the
|
|
"pending" deployment (the next boot) as well as the default rollback
|
|
deployment. Use <option>-p/--pending</option> to remove the pending
|
|
deployment, and <option>-r/--rollback</option> to remove the
|
|
rollback.
|
|
</para>
|
|
|
|
<para>
|
|
The <option>-b/--base</option> option does not affect finished
|
|
deployments, but will clean up any transient allocated space that
|
|
may result from interrupted operations. If you want to free up disk
|
|
space safely, use this option first.
|
|
</para>
|
|
|
|
<para>
|
|
The <option>-m/--repomd</option> option cleans up cached RPM
|
|
repodata and any partially downloaded (but not imported) packages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>reload</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Some configuration and state data such as
|
|
<literal>/etc/ostree/remotes.d</literal> changes may not be
|
|
reflected until a daemon reload is invoked. Use this command to
|
|
initiate a reload.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>usroverlay</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Mount a writable overlay filesystem on <literal>/usr</literal> which
|
|
is active only for the remainder of the system boot. This is
|
|
intended for development, testing, and debugging. Changes will not
|
|
persist across upgrades, or rebooting in general.
|
|
</para>
|
|
|
|
<para>
|
|
One important goal of this is to support traditional <command>rpm
|
|
-Uvh /path/to/rpms</command> or equivalent where changes are applied
|
|
live. However, an intended future feature for
|
|
<command>rpm-ostree</command> will be a variant of
|
|
<command>rpm-ostree override</command> which also supports applying
|
|
changes live, for the cases which one wants persistence as well.
|
|
</para>
|
|
|
|
<para>
|
|
This command is equivalent to <command>ostree admin unlock</command>.
|
|
</para>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>initramfs</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
By default, the primary use case mode for rpm-ostree is to replicate
|
|
an initramfs as part of a base layer. However, some use cases
|
|
require locally regenerating it to add configuration or drivers. Use
|
|
<command>rpm-ostree initramfs</command> to inspect the current
|
|
status.
|
|
</para>
|
|
|
|
<para>
|
|
Use <command>--enable</command> to turn on client side initramfs
|
|
regeneration. A new deployment will be generated, and after reboot,
|
|
further upgrades will continue regenerating. You must reboot for the
|
|
new initramfs to take effect.
|
|
</para>
|
|
|
|
<para>
|
|
To append additional custom arguments to the initramfs program
|
|
(currently dracut), use <command>--arg</command>. For example,
|
|
<command>--arg=-I --arg=/etc/someconfigfile</command>.
|
|
</para>
|
|
|
|
<para>
|
|
The <command>--disable</command> option will disable
|
|
regeneration. You must reboot for the change to take effect.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>ex</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
This command offers access to experimental features; command line
|
|
stability is not guaranteed. The available subcommands will be listed
|
|
by invoking <command>rpm-ostree ex</command>. For example, there is
|
|
<command>rpm-ostree ex livefs</command> which is an experimental
|
|
interface for applying changes to the booted deployment.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Server side commands</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><command>compose</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Entrypoint for tree composition; most typically used on servers to
|
|
prepare trees for replication by client systems. The
|
|
<literal>tree</literal> subcommand processes a treefile, installs
|
|
packages, and commits the result to an OSTree repository. There are
|
|
also split commands <literal>install</literal>,
|
|
<literal>postprocess</literal>, and <literal>commit</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>rpm-ostreed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|