mirror of
https://github.com/ostreedev/ostree.git
synced 2025-03-28 02:50:37 +03:00
doc: Add some docs about adapting existing package managers
This commit is contained in:
Colin Walters
parent
db4aecee44
commit
84f2cd249a
@ -78,6 +78,7 @@ content_files= \
|
||||
repo.xml \
|
||||
deployment.xml \
|
||||
atomic-upgrades.xml \
|
||||
adapting-existing.xml \
|
||||
$(NULL)
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
|
||||
204
doc/adapting-existing.xml
Normal file
204
doc/adapting-existing.xml
Normal file
@ -0,0 +1,204 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||
<!ENTITY version SYSTEM "../version.xml">
|
||||
]>
|
||||
<part id="adapting-existing">
|
||||
<title>Adapating existing mainstream distributions</title>
|
||||
<chapter id="layout">
|
||||
<title>System layout</title>
|
||||
<para>
|
||||
First, OSTree encourages systems to implement <ulink
|
||||
url="http://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge/">UsrMove</ulink>.
|
||||
This is simply to avoid the need for more bind mounts. By
|
||||
default OSTree's dracut hook creates a read-only bind mount over
|
||||
<filename class='directory'>/usr</filename>; you can of course
|
||||
generate individual bind-mounts for <filename
|
||||
class='directory'>/bin</filename>, all the <filename
|
||||
class='directory'>/lib</filename> variants, etc. So it is not
|
||||
intended to be a hard requirement.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename class='directory'>/sysroot</filename> directory is
|
||||
a new OS-level directory that OSTree expects to use as a bind
|
||||
mount target to the physical <filename
|
||||
class='directory'>/</filename> root directory. Remember,
|
||||
because by default the system is booted into a
|
||||
<literal>chroot</literal> equivalent, there has to be some way
|
||||
to refer to the actual physical root filesystem, and there is
|
||||
precedent for this name in the initramfs context. This
|
||||
directory must exist; for example, the OSTree tool at runtime
|
||||
expects that <filename
|
||||
class='directory'>/sysroot/ostree/repo</filename> refers to the
|
||||
system repository.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Because OSTree only preserves <filename
|
||||
class='directory'>/var</filename> across upgrades, it is very
|
||||
strongly recommended for systems which want to preserve
|
||||
compatibility with the <ulink
|
||||
url="http://www.pathname.com/fhs/">Filesystem Hierarchy
|
||||
Standard</ulink> to create the following symbolic links:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<filename class='directory'>/home</filename> to <filename class='directory'>/var/home</filename>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<filename class='directory'>/opt</filename> to <filename class='directory'>/var/opt</filename>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<filename class='directory'>/usr/local</filename> to <filename class='directory'>/var/local</filename>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<filename class='directory'>/mnt</filename> to <filename class='directory'>/var/mnt</filename>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<filename class='directory'>/tmp</filename> to <filename class='directory'>/sysroot/tmp</filename>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Furthermore, since <filename class='directory'>/var</filename>
|
||||
is empty by default, your operating system will need to
|
||||
dynamically create these directories at boot. A good way to do
|
||||
this is using <command>systemd-tmpfiles</command>, if your OS
|
||||
uses systemd. For example:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
d /var/log/journal 0755 root root -
|
||||
L /var/home - - - - ../sysroot/home
|
||||
d /var/opt 0755 root root -
|
||||
d /var/srv 0755 root root -
|
||||
d /var/roothome 0700 root root -
|
||||
d /var/usrlocal 0755 root root -
|
||||
d /var/usrlocal/bin 0755 root root -
|
||||
d /var/usrlocal/etc 0755 root root -
|
||||
d /var/usrlocal/games 0755 root root -
|
||||
d /var/usrlocal/include 0755 root root -
|
||||
d /var/usrlocal/lib 0755 root root -
|
||||
d /var/usrlocal/man 0755 root root -
|
||||
d /var/usrlocal/sbin 0755 root root -
|
||||
d /var/usrlocal/share 0755 root root -
|
||||
d /var/usrlocal/src 0755 root root -
|
||||
d /var/mnt 0755 root root -
|
||||
d /run/media 0755 root root -
|
||||
]]>
|
||||
</programlisting>
|
||||
</chapter>
|
||||
|
||||
<chapter id="booting">
|
||||
<title>Booting and initramfs technology</title>
|
||||
<para>
|
||||
OSTree comes with optional dracut+systemd integration code that
|
||||
parses the <literal>ostree=</literal> kernel command line
|
||||
argument in the initramfs, and then sets up the read-only bind
|
||||
mount on <filename class='directory'>/usr</filename>, a bind
|
||||
mount on the deployment's <filename
|
||||
class='directory'>/sysroot</filename> to the physical <filename
|
||||
class='directory'>/</filename>, and then finally uses
|
||||
<literal>mount(MS_MOVE)</literal> to make the deployment root appear to be the
|
||||
root filesystem before telling systemd to switch root.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are not using dracut or systemd, using OSTree should still
|
||||
be possible, but you will have to write the integration code. Patches
|
||||
to support other initramfs technologies and init systems, if sufficiently
|
||||
clean, will likely be accepted upstream.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A further specific note regarding <command>sysvinit</command>:
|
||||
OSTree used to support recording device files such the
|
||||
<filename>/dev/initctl</filename> FIFO, but no longer does.
|
||||
It's recommended to just patch your initramfs to create this at
|
||||
boot.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="adapting-package-manager">
|
||||
<title>Adapting existing package managers</title>
|
||||
<para>
|
||||
The largest endeavor is likely to be redesigning your
|
||||
distribution's package manager to be on top of OSTree,
|
||||
particularly if you want to keep compatibility with the "old
|
||||
way" of installing into the physical <filename
|
||||
class='directory'>/</filename>. This section will use examples
|
||||
from both <command>dpkg</command> and <command>rpm</command> as
|
||||
the author has familiarity with both; but the abstract concepts
|
||||
should apply to most traditional package managers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There are many levels of possible integration; initially, we
|
||||
will describe the most naive implementation which is the
|
||||
simplest but also the least efficient. We will assume here that
|
||||
the admin is booted into an OSTree-enabled system, and wants to
|
||||
add a set of packages.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Many package managers store their state in <filename
|
||||
class='directory'>/var</filename>; but since in the OSTree model
|
||||
that directory is shared between independent versions, the
|
||||
package database must first be found in the per-deployment
|
||||
<filename class='directory'>/usr</filename> directory. It
|
||||
becomes read-only; remember, all upgrades involve constructing a
|
||||
new filesystem tree, so your package manager will also need to
|
||||
create a copy of its database. Most likely, if you want to
|
||||
continue supporting non-OSTree deployments, simply have your
|
||||
package manager fall back to the legacy <filename
|
||||
class='directory'>/var</filename> location if the one in
|
||||
<filename class='directory'>/usr</filename> is not found.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To install a set of new packages (without removing any existing
|
||||
ones), enumerate the set of packages in the currently booted
|
||||
deployment, and perform dependency resolution to compute the
|
||||
complete set of new packages. Download and unpack these new
|
||||
packages to a temporary directory.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now, because we are merely installing new packages and not
|
||||
removing anything, we can make the major optimization of reusing
|
||||
our existing filesystem tree, and merely
|
||||
<emphasis>layering</emphasis> the composed filesystem tree of
|
||||
these new packages on top. A command lke this: <command>ostree
|
||||
commit -b osname/releasename/description
|
||||
--tree=ref=<replaceable>osname/releasenamename/description</replaceable>
|
||||
--tree=dir=/var/tmp/newpackages.13A8D0/</command> will create a
|
||||
new commit in the
|
||||
<replaceable>osname/releasename/description</replaceable>
|
||||
branch. The OSTree SHA256 checksum of all the files in
|
||||
/var/tmp/newpackages.13A8D0/ will be computed, but we will not
|
||||
re-checksum the present existing tree. In this layering model,
|
||||
earlier directories will take precedence, but files in later
|
||||
layers will silently override earlier layers.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Then to actually deploy this tree for the next boot:
|
||||
<command>ostree admin deploy
|
||||
<replaceable>osname/releasenamename/description</replaceable></command>
|
||||
</para>
|
||||
|
||||
</chapter>
|
||||
|
||||
</part>
|
||||
@ -82,24 +82,15 @@
|
||||
"live" on the currently booted filesystem. The way they could
|
||||
work with OSTree is instead to take the list of installed
|
||||
packages in the currently booted tree, and compute a new
|
||||
filesystem from that.
|
||||
filesystem from that. A later chapter describes in more details
|
||||
how this could work: <xref linkend="adapting-existing"/>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The most basic implementation of this would be something like
|
||||
taking the result of <command>rpm -qa</command>, and doing
|
||||
<command>yum --installroot=/var/tmp/newroot install
|
||||
<replaceable>package1</replaceable>
|
||||
<replaceable>package2</replaceable> ...</command>. Then,
|
||||
<command>ostree commit -b osname/localtree
|
||||
--tree=dir=/var/tmp/newroot</command>. This would checksum all
|
||||
of the input files and store them in local <filename
|
||||
class='directory'>/ostree/repo</filename> repository, creating
|
||||
a new commit.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Now, we can move on to deployment.
|
||||
For the purposes of this section, let's assume that we have a
|
||||
newly generated filesystem tree stored in the repo (which shares
|
||||
storage with the existing booted tree). We can then move on to
|
||||
checking it back out of the repo into a deployment.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
|
||||
@ -15,6 +15,7 @@
|
||||
<xi:include href="repo.xml"/>
|
||||
<xi:include href="deployment.xml"/>
|
||||
<xi:include href="atomic-upgrades.xml"/>
|
||||
<xi:include href="adapting-existing.xml"/>
|
||||
|
||||
<chapter xml:id="reference">
|
||||
<title>API Reference</title>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user