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
|
||||
assemble RPMs on a server side into an
|
||||
[OSTree](https://wiki.gnome.org/Projects/OSTree) repository. Then
|
||||
clients can update from that repository in a reliable image-like
|
||||
fashion, via `atomic upgrade`.
|
||||
The project aims to bring together a hybrid of image-like upgrade
|
||||
features (reliable replication, atomicity), with package-like
|
||||
flexibility (seeing package sets inside trees, layering, partial live
|
||||
updates).
|
||||
|
||||
Currently, rpm operates on a read-only mode on installed systems; it
|
||||
is not possible to add or remove anything on the client. In return,
|
||||
client systems are reliably synchronized with the server-provided
|
||||
tree. For example, if a package is removed in the server-composed
|
||||
set, when clients update, it also drops out of their tree.
|
||||
## rpm-ostree is in beta!
|
||||
While many of the underlying technologies here are stable,
|
||||
if you are considering using this in your organization, you
|
||||
should perform a careful evaluation of the whole stack. Software
|
||||
updates are obviously critical, and touch on many areas of concern.
|
||||
|
||||
This model works well in scenarios where one wants reliable state
|
||||
replication of master to many client machines.
|
||||
|
||||
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.
|
||||
### Contents
|
||||
* [Background and rationale](doc/background.md)
|
||||
* [Setting up and managing a compose server](doc/compose-server.md)
|
||||
* [Administering an rpm-ostree system](doc/administrator-handbook.md)
|
||||
|
||||
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