rpm-ostree/man/rpm-ostree.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 <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">OPTIONS</arg></command>
    </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>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>
          <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>
      </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>rollback</command></term>
	
	<listitem><para>OSTree mananges 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>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 current tree.</para>
	</listitem>
      </varlistentry>

      <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>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>rpm</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.
        </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>

    </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>