cac4522e5b
Currently we push for a model where the initramfs is generated (in non-hostonly mode), and merely replicated. However, to support a few unfortunate corner cases like dm-multipath which wants to inject a config file into the initramfs, we need to support regenerating it client side too. Down the line, we'll need this to support overriding the kernel too. This changes things in the core to add the concept of an "empty" `RpmOstreeContext`. I initially tried skipping it, but that was too much duplication. We still want all of the core ostree-related logic that lives in that code too. The treespec bits barfed if the spec didn't have a `tree/packages` key. It was simplest to change that to allow it - and because that was the only case where we errored out in parsing, I dropped the error handling. There was another place in the upgrader that now needed to be fixed to handle transitioning from just regenerating initramfs to not. Closes: #574 Approved by: jlebon
382 lines
13 KiB
XML
382 lines
13 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>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>
|
|
Operating system upgrade and software management tool
|
|
</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 (also called "atomic" if configured) is a system
|
|
software management tool that combines features of both
|
|
traditional RPM and OSTree. It has support for both server-side
|
|
composing of trees, as well as client-side upgrading and
|
|
management of deployments.
|
|
</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.
|
|
</para>
|
|
|
|
<para>
|
|
Note in this "pure replication" model, at present there is no
|
|
dependency resolution on the client machines, nor any ability to
|
|
add or remove packages. You may however use /usr/local/bin, or
|
|
an application mechanism such as
|
|
<citerefentry>
|
|
<refentrytitle>docker</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>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.
|
|
Currently has two subcommands, <literal>tree</literal> and
|
|
<literal>sign</literal>.
|
|
</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 commits. 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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>install (pkg-add)</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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>uninstall (pkg-remove)</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>rebase</command></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Switch to a different remote, or a different tree, while
|
|
preserving local state in <literal>/var</literal> and
|
|
configuration in <literal>/etc</literal>. This is an
|
|
extension of <literal>upgrade</literal> which switches to
|
|
a newer version of the current tree.
|
|
</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>
|
|
</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>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|