README.md: Add more docs
This commit is contained in:
Colin Walters
parent
66b0737720
commit
9e6231407c
72
README.md
72
README.md
@ -1,58 +1,20 @@
|
|||||||
rpm-ostree
|
# rpm-ostree (`/usr/bin/atomic`)
|
||||||
==========
|
An system to compose RPMs on a server side into an
|
||||||
|
[OSTree](https://wiki.gnome.org/Projects/OSTree)
|
||||||
|
repository, and a client side tool to perform updates.
|
||||||
|
|
||||||
RPM-OSTree (also nicknamed `/usr/bin/atomic`) is a mechanism to
|
The project aims to bring together a hybrid of image-like upgrade
|
||||||
assemble RPMs on a server side into an
|
features (reliable replication, atomicity), with package-like
|
||||||
[OSTree](https://wiki.gnome.org/Projects/OSTree) repository. Then
|
flexibility (seeing package sets inside trees, layering, partial live
|
||||||
clients can update from that repository in a reliable image-like
|
updates).
|
||||||
fashion, via `atomic upgrade`.
|
|
||||||
|
|
||||||
Currently, rpm operates on a read-only mode on installed systems; it
|
## rpm-ostree is in beta!
|
||||||
is not possible to add or remove anything on the client. In return,
|
While many of the underlying technologies here are stable,
|
||||||
client systems are reliably synchronized with the server-provided
|
if you are considering using this in your organization, you
|
||||||
tree. For example, if a package is removed in the server-composed
|
should perform a careful evaluation of the whole stack. Software
|
||||||
set, when clients update, it also drops out of their tree.
|
updates are obviously critical, and touch on many areas of concern.
|
||||||
|
|
||||||
This model works well in scenarios where one wants reliable state
|
### Contents
|
||||||
replication of master to many client machines.
|
* [Background and rationale](doc/background.md)
|
||||||
|
* [Setting up and managing a compose server](doc/compose-server.md)
|
||||||
Installing and setting up a repository
|
* [Administering an rpm-ostree system](doc/administrator-handbook.md)
|
||||||
--------------------------------------
|
|
||||||
|
|
||||||
First, unfortunately you must *disable* SELinux on the build host in
|
|
||||||
order to *support* SELinux on the built system. See:
|
|
||||||
https://bugzilla.redhat.com/show_bug.cgi?id=1060423
|
|
||||||
|
|
||||||
Once you have that done, choose a build directory. Here we'll use
|
|
||||||
/srv/rpm-ostree.
|
|
||||||
|
|
||||||
# cd /srv/rpm-ostree
|
|
||||||
# mkdir repo
|
|
||||||
# ostree --repo=repo init --mode=archive-z2
|
|
||||||
|
|
||||||
Running `rpm-ostree compose tree`
|
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
This program takes as input a manifest file that describes the target
|
|
||||||
system, and commits the result to an OSTree repository.
|
|
||||||
|
|
||||||
See also: https://github.com/projectatomic/rpm-ostree-toolbox
|
|
||||||
|
|
||||||
The input format is a JSON "treefile". See examples in
|
|
||||||
`doc/treefile-examples`, as well as `doc/treefile.md`.
|
|
||||||
|
|
||||||
# rpm-ostree compose tree --repo=/srv/rpm-ostree/repo --proxy=http://127.0.0.1:8123 sometreefile.json
|
|
||||||
|
|
||||||
All this does is use yum to download RPMs from the referenced repos,
|
|
||||||
and commit the result to the OSTree repository, using the ref named by
|
|
||||||
`ref`. Note that we've specified a local caching proxy (`polipo` in
|
|
||||||
this case) - otherwise we you will download the packages for each
|
|
||||||
treecompose.
|
|
||||||
|
|
||||||
You can export `/srv/rpm-ostree/repo` via any static webserver.
|
|
||||||
|
|
||||||
The use of `--proxy` is not mandatory but strongly recommended - with
|
|
||||||
this option you can avoid continually redownloading the packages every
|
|
||||||
compose. I personally use
|
|
||||||
[Polipo](http://www.pps.univ-paris-diderot.fr/~jch/software/polipo/),
|
|
||||||
but you can of course any HTTP proxy you wish.
|
|
||||||
|
|||||||
27
doc/administrator-handbook.md
Normal file
27
doc/administrator-handbook.md
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
## Administering an rpm-ostree based system
|
||||||
|
|
||||||
|
At the moment, there are two primary commands to be familiar with on
|
||||||
|
an rpm-ostree based system. Remember that `atomic` is an alias for
|
||||||
|
`rpm-ostree`. The author tends to use the former on client systems,
|
||||||
|
and the latter on compose servers.
|
||||||
|
|
||||||
|
# atomic upgrade
|
||||||
|
|
||||||
|
Will perform a system upgrade, creating a *new* chroot, and set it as
|
||||||
|
the default for the next boot. You should use `systemctl reboot`
|
||||||
|
shortly afterwards.
|
||||||
|
|
||||||
|
# atomic rollback
|
||||||
|
|
||||||
|
By default, the `atomic upgrade` will keep at most two bootable
|
||||||
|
"deployments", though the underlying technology supports more.
|
||||||
|
|
||||||
|
## Filesystem layout
|
||||||
|
|
||||||
|
The only writable directories are `/etc` and `/var`. In particular,
|
||||||
|
`/usr` has a read-only bind mount at all times. Any data in `/var` is
|
||||||
|
never touched, and is shared across upgrades.
|
||||||
|
|
||||||
|
At upgrade time, the process takes the *new default* `/etc`, and adds
|
||||||
|
your changes on top. This means that upgrades will receive new
|
||||||
|
default files in `/etc`, which is quite a critical feature.
|
||||||
59
doc/background.md
Normal file
59
doc/background.md
Normal file
@ -0,0 +1,59 @@
|
|||||||
|
## Package systems versus image systems
|
||||||
|
|
||||||
|
Broadly speaking, software update systems for operating systems tend
|
||||||
|
to fall cleanly into one of two camps: package-based or image-based.
|
||||||
|
|
||||||
|
### Package system benefits and drawbacks
|
||||||
|
|
||||||
|
* + Highly dynamic, fast access to wide array of software
|
||||||
|
* + State management in `/etc` and `/var` is well understood
|
||||||
|
* + Can swap between major/minor system states (`apt-get upgrade` is similar to `apt-get dist-upgrade`)
|
||||||
|
* + Work on top of any filesystem or partition layout
|
||||||
|
* - As package set grows, testing becomes combinatorially more expensive
|
||||||
|
* - Live system mutation, no rollbacks
|
||||||
|
|
||||||
|
### Image benefits and drawbacks
|
||||||
|
|
||||||
|
* + Ensures all users are running a known state
|
||||||
|
* + Rollback supported
|
||||||
|
* + Can achieve efficient security via things like [dm-verity](http://lwn.net/Articles/459420/)
|
||||||
|
* - Many image systems have a read-only `/etc`, and writable partitions elsewhere
|
||||||
|
* - Must reboot for updates
|
||||||
|
* - Usually operate at block level, so require fixed partition layout and filesystem
|
||||||
|
* - Often paired with a separate application mechanism, but misses out on things that aren't apps
|
||||||
|
* - Administrators still need to know content inside
|
||||||
|
|
||||||
|
## How RPM-OSTree provides a middle ground
|
||||||
|
|
||||||
|
rpm-ostree allows composing packages on a server, and clients can
|
||||||
|
replicate that state reliably. For example, if one adds a package on
|
||||||
|
the compose server, clients get it. If one removes a package, it's
|
||||||
|
also removed when clients upgrade.
|
||||||
|
|
||||||
|
One simple mental model for rpm-ostree is: imagine taking a set of
|
||||||
|
packages on the server side, install them to a chroot, then doing `git
|
||||||
|
commit` on the result. And imagine clients just `git pull -r` from
|
||||||
|
that. What OSTree to this picture is support for uid/gid, extended
|
||||||
|
attributes, handling of bootloader configuration, and merges of
|
||||||
|
`/etc`.
|
||||||
|
|
||||||
|
To emphasize, replication is at a filesystem level - that means that
|
||||||
|
that things like SELinux labels and uid/gid mappings are assigned on
|
||||||
|
the server side.
|
||||||
|
|
||||||
|
On the other hand, rpm-ostree works on top of any Unix filesystem. It
|
||||||
|
will not interfere with any filesystem or block-level snapshots or
|
||||||
|
backups such as LVM or BTRFS.
|
||||||
|
|
||||||
|
## Who should use this?
|
||||||
|
|
||||||
|
Currently, rpm operates on a read-only mode on installed systems; it
|
||||||
|
is not possible to add or remove anything on the client. If this
|
||||||
|
matches your deployment scenario, rpm-ostree is a good choice.
|
||||||
|
Classic examples of this are fixed purpose server farms, "corporate
|
||||||
|
standard build" laptop/desktops.
|
||||||
|
|
||||||
|
## Is it worth supporting composes both on client and server?
|
||||||
|
|
||||||
|
In short, our belief is yes. Long term, rpm-ostree offers a potential
|
||||||
|
unified tooling via package layering.
|
||||||
80
doc/compose-server.md
Normal file
80
doc/compose-server.md
Normal file
@ -0,0 +1,80 @@
|
|||||||
|
## Installing and setting up a repository
|
||||||
|
|
||||||
|
First, unfortunately you must *disable* SELinux on the build host in
|
||||||
|
order to *support* SELinux on the built system. See:
|
||||||
|
https://bugzilla.redhat.com/show_bug.cgi?id=1060423
|
||||||
|
|
||||||
|
Once you have that done, choose a build directory. Here we'll use
|
||||||
|
/srv/rpm-ostree.
|
||||||
|
|
||||||
|
# cd /srv/rpm-ostree
|
||||||
|
# mkdir repo
|
||||||
|
# ostree --repo=repo init --mode=archive-z2
|
||||||
|
|
||||||
|
## Running `rpm-ostree compose tree`
|
||||||
|
|
||||||
|
This program takes as input a manifest file that describes the target
|
||||||
|
system, and commits the result to an OSTree repository.
|
||||||
|
|
||||||
|
See also: https://github.com/projectatomic/rpm-ostree-toolbox
|
||||||
|
|
||||||
|
The input format is a JSON "treefile". See examples in
|
||||||
|
`doc/treefile-examples`, as well as `doc/treefile.md`.
|
||||||
|
|
||||||
|
# rpm-ostree compose tree --repo=/srv/rpm-ostree/repo --proxy=http://127.0.0.1:8123 sometreefile.json
|
||||||
|
|
||||||
|
All this does is use yum to download RPMs from the referenced repos,
|
||||||
|
and commit the result to the OSTree repository, using the ref named by
|
||||||
|
`ref`. Note that we've specified a local caching proxy (`polipo` in
|
||||||
|
this case) - otherwise we you will download the packages for each
|
||||||
|
treecompose.
|
||||||
|
|
||||||
|
You can export `/srv/rpm-ostree/repo` via any static webserver.
|
||||||
|
|
||||||
|
The use of `--proxy` is not mandatory but strongly recommended - with
|
||||||
|
this option you can avoid continually redownloading the packages every
|
||||||
|
compose. I personally use
|
||||||
|
[Polipo](http://www.pps.univ-paris-diderot.fr/~jch/software/polipo/),
|
||||||
|
but you can of course any HTTP proxy you wish.
|
||||||
|
|
||||||
|
## Treefile key documentation
|
||||||
|
|
||||||
|
* `ref`: string, mandatory: Holds a string which will be the name of
|
||||||
|
the branch for the content.
|
||||||
|
|
||||||
|
* `gpg_key` string, optional: Key ID for GPG signing; the secret key
|
||||||
|
must be in the home directory of the building user. Defaults to
|
||||||
|
none.
|
||||||
|
|
||||||
|
* `repos` array of strings, mandatory: Names of yum repositories to
|
||||||
|
use, from the system `/etc/yum.repos.d`.
|
||||||
|
|
||||||
|
* `selinux`: boolean, optional: Defaults to `true`. If `false`, then
|
||||||
|
no SELinux labeling will be performed on the server side.
|
||||||
|
|
||||||
|
* `boot_location`: string, optional: Historically, ostree put bootloader data
|
||||||
|
in /boot. However, this has a few flaws; it gets shadowed at boot time,
|
||||||
|
and also makes dealing with Anaconda installation harder. There are 3
|
||||||
|
possible values:
|
||||||
|
* "legacy": the default, data goes in /boot
|
||||||
|
* "both": Kernel data in /boot and /usr/lib/ostree-boot
|
||||||
|
* "new": Kernel data in /usr/lib/ostree-boot
|
||||||
|
|
||||||
|
* `bootstrap_packages`: Array of strings, mandatory: The `glibc` and
|
||||||
|
`nss-altfiles` packages (and ideally nothing else) must be in this
|
||||||
|
set; rpm-ostree will modify the `/etc/nsswitch.conf` in the target
|
||||||
|
root to ensure that `/usr/lib/passwd` is used.
|
||||||
|
|
||||||
|
* `packages`: Array of strings, mandatory: Set of installed packages.
|
||||||
|
Names prefixed with an `@` (e.g. `@core`) are taken to be the names
|
||||||
|
of comps groups.
|
||||||
|
|
||||||
|
* `units`: Array of strings, optional: Systemd units to enable by default
|
||||||
|
|
||||||
|
* `default_target`: String, optional: Set the default systemd target
|
||||||
|
|
||||||
|
* `include`: string, optional: Path to another treefile which will be
|
||||||
|
used as an inheritance base. The semantics for inheritance are:
|
||||||
|
Non-array values in child values override parent values. Array
|
||||||
|
values are concatenated. Filenames will be resolved relative to
|
||||||
|
the including treefile.
|
||||||
@ -1,42 +0,0 @@
|
|||||||
Treefile
|
|
||||||
--------
|
|
||||||
|
|
||||||
* `ref`: string, mandatory: Holds a string which will be the name of
|
|
||||||
the branch for the content.
|
|
||||||
|
|
||||||
* `gpg_key` string, optional: Key ID for GPG signing; the secret key
|
|
||||||
must be in the home directory of the building user. Defaults to
|
|
||||||
none.
|
|
||||||
|
|
||||||
* `repos` array of strings, mandatory: Names of yum repositories to
|
|
||||||
use, from the system `/etc/yum.repos.d`.
|
|
||||||
|
|
||||||
* `selinux`: boolean, optional: Defaults to `true`. If `false`, then
|
|
||||||
no SELinux labeling will be performed on the server side.
|
|
||||||
|
|
||||||
* `boot_location`: string, optional: Historically, ostree put bootloader data
|
|
||||||
in /boot. However, this has a few flaws; it gets shadowed at boot time,
|
|
||||||
and also makes dealing with Anaconda installation harder. There are 3
|
|
||||||
possible values:
|
|
||||||
* "legacy": the default, data goes in /boot
|
|
||||||
* "both": Kernel data in /boot and /usr/lib/ostree-boot
|
|
||||||
* "new": Kernel data in /usr/lib/ostree-boot
|
|
||||||
|
|
||||||
* `bootstrap_packages`: Array of strings, mandatory: The `glibc` and
|
|
||||||
`nss-altfiles` packages (and ideally nothing else) must be in this
|
|
||||||
set; rpm-ostree will modify the `/etc/nsswitch.conf` in the target
|
|
||||||
root to ensure that `/usr/lib/passwd` is used.
|
|
||||||
|
|
||||||
* `packages`: Array of strings, mandatory: Set of installed packages.
|
|
||||||
Names prefixed with an `@` (e.g. `@core`) are taken to be the names
|
|
||||||
of comps groups.
|
|
||||||
|
|
||||||
* `units`: Array of strings, optional: Systemd units to enable by default
|
|
||||||
|
|
||||||
* `default_target`: String, optional: Set the default systemd target
|
|
||||||
|
|
||||||
* `include`: string, optional: Path to another treefile which will be
|
|
||||||
used as an inheritance base. The semantics for inheritance are:
|
|
||||||
Non-array values in child values override parent values. Array
|
|
||||||
values are concatenated. Filenames will be resolved relative to
|
|
||||||
the including treefile.
|
|
||||||
Loading…
Reference in New Issue
Block a user