c84b8b81db
It's been in experimental for a while now, and we've had good feedback that it's working. With #1392 fixed, it seems in a good position to declare stable and commit to that API. This also helps empty out `ex` a bit. Closes: #1428 Approved by: cgwalters
690 lines
24 KiB
XML
690 lines
24 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. It is also possible to specify a
|
|
local RPM package that resides on the host. Overlayed
|
|
packages can later be removed with the
|
|
<command>uninstall</command> command.
|
|
</para>
|
|
|
|
<para>
|
|
rpm-ostree remembers these requests even if a later host
|
|
update includes those packages already: if the packages are
|
|
subsequently dropped out again, rpm-ostree will go back to
|
|
layering them.
|
|
</para>
|
|
|
|
<para>
|
|
Note that currently, you may specify a package that is
|
|
already in the base layer, though you should use the
|
|
<command>--allow-inactive</command> option to avoid a
|
|
warning. This option will become mandatory in the future.
|
|
</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>--allow-inactive</option> to allow requests for
|
|
packages that are already in the base layer.
|
|
</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. Using this flag will force an update
|
|
of the RPM metadata from the enabled repos in
|
|
<filename>/etc/yum.repos.d/</filename>, if there are any
|
|
layered packages.
|
|
</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>kargs</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Without options, display current default kernel arguments. Modify
|
|
arguments using <option>--append</option>,
|
|
<option>--replace</option>, <option>--delete</option>, or
|
|
<option>--editor</option>. This will create a new deployment with
|
|
the modified kernel arguments. Previous deployments are never
|
|
changed.
|
|
</para>
|
|
|
|
<para>
|
|
By default, modifications are applied to the kernel arguments of the
|
|
default deployment to get the final arguments. Use
|
|
<option>--deploy-index</option> or
|
|
<option>--import-proc-cmdline</option> to instead base them off of a
|
|
specific deployment or the current boot.
|
|
</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>
|