path: root/man/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 Colin Walters <walters@verbum.org>

SPDX-License-Identifier: LGPL-2.0+

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="ostree">

    <refentryinfo>
        <title>ostree</title>
        <productname>OSTree</productname>

        <authorgroup>
            <author>
                <contrib>Developer</contrib>
                <firstname>Colin</firstname>
                <surname>Walters</surname>
                <email>walters@verbum.org</email>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>ostree</refentrytitle>
        <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
        <refname>ostree</refname>
        <refpurpose>Manage multiple bootable versioned filesystem trees</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
            <cmdsynopsis>
                <command>ostree</command>
		<arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">OPTIONS</arg>
            </cmdsynopsis>
    </refsynopsisdiv>

    <refsect1>
        <title>Description</title>

        <para>
            OSTree is a tool for managing multiple bootable
            versioned filesystem trees, or just "tree" for
            short.  In the OSTree model, operating systems no
            longer live in the physical "/" root directory.
            Instead, they parallel install to the new toplevel
            <filename>/ostree</filename> directory.  Each
            installed system gets its own
            <filename>/ostree/deploy/<replaceable>stateroot</replaceable></filename>
            directory.  (<literal>stateroot</literal> is the
            newer term for <literal>osname</literal>).
        </para>
        <para>
            Unlike <literal>rpm</literal> or
            <literal>dpkg</literal>, OSTree is only aware of
            complete filesystem trees.  It has no built-in
            knowledge of what components went into creating the
            filesystem tree.
        </para>
        <para>
            It is possible to use OSTree in several modes; the
            most basic form is to replicate pre-built trees from
            a build server.  Usually, these pre-built trees are
            derived from packages.  You might also be using
            OSTree underneath a higher level tool which computes
            filesystem trees locally.
        </para>
        <para>
            It must be emphasized that OSTree only supports
            <emphasis>read-only</emphasis> trees.  To change to
            a different tree (upgrade, downgrade, install
            software), a new tree is checked out, and a 3-way
            merge of configuration is performed.  The currently
            running tree is not ever modified; the new tree will
            become active on a system reboot.
        </para>

        <para>
              To see the man page for a command run <command>man ostree <replaceable>COMMAND</replaceable></command> or <command>man ostree-admin <replaceable>COMMAND</replaceable></command>
        </para>
    </refsect1>

    <refsect1>
        <title>Options</title>

        <para>The following options are understood:</para>

        <variablelist>
            <varlistentry>
                <term><option>--repo</option></term>

                <listitem><para>
                    For most commands, a repository is
                    required.  If unspecified, the current
                    directory is used if it appears to be an
                    OSTree repository. If it isn't, either
                    the <envar>OSTREE_REPO</envar>
                    environment variable is used, or the
                    system repository located at
                    <filename>/sysroot/ostree/repo</filename>.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>-v, --verbose</option></term>

                <listitem><para>
                    Produce debug level output.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--version</option></term>

                <listitem><para>
                    Print version information, including the features enabled
                    at compile time, and exit.
                </para></listitem>
            </varlistentry>
        </variablelist>
    </refsect1>

    <refsect1>
        <title>Commands</title>

        <para>System administrators will primarily interact
        with OSTree via the subcommand <command>ostree
        admin</command>.</para>

        <variablelist>
            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-admin-cleanup</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Delete untagged
                    deployments and repository objects.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                 <term><citerefentry><refentrytitle>ostree-admin-config-diff</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;See changes to
                    <filename>/etc</filename> as compared
                    to the current default (from
                    <filename>/usr/etc</filename>).
                </para></listitem>
            </varlistentry>

            <varlistentry>
                 <term><citerefentry><refentrytitle>ostree-admin-deploy</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Takes a particular
                    commit or revision, and sets it up for
                    the next boot.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                 <term><citerefentry><refentrytitle>ostree-admin-init-fs</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Initialize a root filesystem
                    in a specified path.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-admin-instutil</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Utility functions intended primarily for operating system installation programs
                </para></listitem>
            </varlistentry>

            <varlistentry>
                 <term><citerefentry><refentrytitle>ostree-admin-os-init</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Initialize the
                    deployment location for an operating
                    system with  a specified name.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-admin-status</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Show and list the deployments.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-admin-switch</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Choose a different ref
                    to track from the same remote as the
                    current tree.
                </para></listitem>
            </varlistentry>   

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-admin-undeploy</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Remove the previously
                    <replaceable>INDEX</replaceable>
                    deployed tree from the bootloader
                    configuration.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-admin-upgrade</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Download the latest version for the
                    current ref, and deploy it.
                </para></listitem>
            </varlistentry>
        </variablelist>

        <para>Both administrators and operating system
        builders may interact with OSTree via the regular
        filesystem manipulation commands.  
        </para>
    
        <variablelist>
            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Concatenate contents of files
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-checkout</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Check out a commit into a filesystem tree.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-checksum</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Gives checksum of any file.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Given one or more
                    trees, create a new commit using those contents.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-config</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Change settings.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-create-usb</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Put the given refs on an external drive for P2P distribution.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-diff</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Concisely list
                    differences between the given refs.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-find-remotes</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Find remotes to serve the given refs.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-fsck</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Check a repository for consistency.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-init</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Initialize a new repository.
                </para></listitem>
            </varlistentry>
            
            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-log</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Show revision log.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-ls</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;List the contents of a given commit.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-prune</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Search for unreachable objects.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-pull-local</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Copy data from source-repo.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-pull</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Download data from remote repo.  If you have libsoup.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-refs</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;List refs.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-remote</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Manipulate remote archive configuration.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-reset</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Reset a ref to a previous commit.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-rev-parse</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Show the SHA256 corresponding to a given rev.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-show</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Given an OSTree SHA256 checksum, display its contents.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-static-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Manage static delta files.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-summary</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>

                <listitem><para>
                    &nbsp;Regenerate the repository summary metadata.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><citerefentry><refentrytitle>ostree-trivial-httpd</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
                
                <listitem><para>
                    &nbsp;Simple webserver.
                </para></listitem>
            </varlistentry>
        </variablelist>
    </refsect1>

    <refsect1>
        <title>Examples</title>

        <para>
            For specific examples, please see the man page regarding the specific ostree command.  For example:
        </para>
        <para> 
            <command>man ostree init</command> or <command>man ostree-admin status</command> 
        </para> 
    </refsect1>

    <refsect1>
        <title>GPG verification</title>

        <para>
          OSTree supports signing commits with GPG.  Operations on the system
          repository by default use keyring files in
          <filename>/usr/share/ostree/trusted.gpg.d</filename>.  Any
          public key in a keyring file in that directory will be
          trusted by the client.  No private keys should be present
          in this directory.
        </para>
        <para>
          In addition to the system repository, OSTree supports two
          other paths.  First, there is a
          <literal>gpgkeypath</literal> option for remotes, which must point
          to the filename of an ASCII-armored GPG key, or a directory containing
          ASCII-armored GPG keys to import.  Multiple file and directory paths
          to import from can be specified, as a comma-separated list of paths.  This option
          may be specified by using <command>--set</command> in <command>ostree remote add</command>.
        </para>
        <para>
          Second, there is support for a per-remote
          <filename><replaceable>remotename</replaceable>.trustedkeys.gpg</filename>
          file stored in the toplevel of the repository (alongside
          <filename>objects/</filename> and such).  This is
          particularly useful when downloading content that may not
          be fully trusted (e.g. you want to inspect it but not
          deploy it as an OS), or use it for containers.  This file
          is written via <command>ostree remote add
          --gpg-import</command>.
        </para>
    </refsect1>

    <refsect1>
        <title>Terminology</title>
        <para>
            The following terms are commonly used throughout the man pages. Terms in upper case letters
            are literals used in command line arguments.
        </para>
        <glosslist>
            <glossentry><glossterm><literal>BRANCH</literal></glossterm>
                <glossdef>
                    <para>
                        Branch name. Part of a <glossterm><literal>REF</literal></glossterm>.
                    </para>
                </glossdef>
            </glossentry>
            <glossentry><glossterm><literal>CHECKSUM</literal></glossterm>
                <glossdef>
                    <para>
                        A SHA256 hash of a object stored in the OSTree repository. This can be a content,
                        a dirtree, a dirmeta or a commit object. If the SHA256 hash of a commit object is
                        meant, the term <glossterm><literal>COMMIT</literal></glossterm> is used.
                    </para>
                </glossdef>
            </glossentry>
            <glossentry><glossterm><literal>COMMIT</literal></glossterm>
                <glossdef>
                    <para>
                        A SHA256 hash of a commit object.
                    </para>
                </glossdef>
            </glossentry>
            <glossentry><glossterm><literal>REF</literal></glossterm>
                <glossdef>
                    <para>
                        A reference to a particular commit. References are text files stored in
                        <filename>refs/</filename> that name (refer to) a particular commit. A
                        reference can only be the branch name part, in which case a local reference
                        is used (e.g. <literal>mybranch/stable</literal>). If a remote branch
                        is referred to, the remote name followed by a colon and the branch name
                        needs to be used (e.g. <literal>myremote:mybranch/stable</literal>).
                    </para>
                </glossdef>
            </glossentry>
            <glossentry><glossterm><literal>REV</literal></glossterm> <glossterm><literal>REFSPEC</literal></glossterm>
                <glossdef>
                    <para>
                        A specific revision, a commit. This can be anything which can be resolved to a
                        commit, e.g. a <glossterm><literal>REF</literal></glossterm> or a
                        <glossterm><literal>COMMIT</literal></glossterm>.
                    </para>
                </glossdef>
            </glossentry>
            <glossentry><glossterm>SHA256</glossterm>
                <glossdef>
                    <para>
                        A cryptographic hash function used to store objects in the OSTree
                        repository. The hashes have a length of 256 bites and are typically
                        shown and passed to ostree in its 64 ASCII character long hexadecimal
                        representation
                        (e.g. 0fc70ed33cfd7d26fe99ae29afb7682ddd0e2157a4898bd8cfcdc8a03565b870).
                    </para>
                </glossdef>
            </glossentry>
        </glosslist>
    </refsect1>
    <refsect1>
        <title>See Also</title>
        <para>
            <citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        </para>
    </refsect1>
</refentry>