mirror of
https://github.com/ostreedev/ostree.git
synced 2024-12-23 21:35:26 +03:00
8fbf19c9f5
Currently the API that allows P2P operations (e.g. pulling an ostree ref from a LAN or USB source) is hidden behind the configure flag --enable-experimental-api. This commit makes the API public and makes that flag essentially a no-op (leaving it in place in case we want to use it again in the future). The P2P API has been tested over the last several months and proven to work. This means that since we're no longer using the "experimental" feature flag, P2P builds of Flatpak will fail when using versions of OSTree from this commit onwards, until Flatpak is patched in the near future. If you want to build Flatpak < 0.11.8 with P2P enabled and link against OSTree 2018.6, you'll have to patch Flatpak. However, since Flatpak won't yet have a hard dependency on OSTree 2018.6, it needs a new way to determine if the P2P API in OSTree is available, so this commit adds a "p2p" feature flag. This way the feature set is more semantically correct than if we had continued to use the "experimental" feature flag. In addition to making the P2P API public, this commit makes the P2P unit tests run by default, removes the f27-experimental CI instance that's no longer needed, changes a few man pages to reflect the changes, and updates the bash completion script to accept the new commands and options. Closes: #1596 Approved by: cgwalters
479 lines
18 KiB
XML
479 lines
18 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 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>
|
|
</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>
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
Show and list the deployments.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-admin-switch</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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>
|
|
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>
|
|
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>
|
|
Concatenate contents of files
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-checkout</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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>
|
|
Gives checksum of any file.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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>
|
|
Change settings.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-create-usb</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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>
|
|
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>
|
|
Find remotes to serve the given refs.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-fsck</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Check a repository for consistency.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-init</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Initialize a new repository.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-log</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Show revision log.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-ls</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
List the contents of a given commit.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-prune</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Search for unreachable objects.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-pull-local</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Copy data from source-repo.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-pull</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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>
|
|
List refs.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-remote</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Manipulate remote archive configuration.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-reset</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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>
|
|
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>
|
|
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>
|
|
Manage static delta files.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-summary</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
Regenerate the repository summary metadata.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><citerefentry><refentrytitle>ostree-trivial-httpd</refentrytitle><manvolnum>1</manvolnum></citerefentry></term>
|
|
|
|
<listitem><para>
|
|
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 key.
|
|
</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>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|