From 9e6231407c216e374c429e593db7686862fdc31a Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 31 Oct 2014 14:39:57 -0400 Subject: [PATCH] README.md: Add more docs --- README.md | 72 ++++++++----------------------- doc/administrator-handbook.md | 27 ++++++++++++ doc/background.md | 59 ++++++++++++++++++++++++++ doc/compose-server.md | 80 +++++++++++++++++++++++++++++++++++ doc/treefile.md | 42 ------------------ 5 files changed, 183 insertions(+), 97 deletions(-) create mode 100644 doc/administrator-handbook.md create mode 100644 doc/background.md create mode 100644 doc/compose-server.md diff --git a/README.md b/README.md index 13a04764..ec3dae02 100644 --- a/README.md +++ b/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) diff --git a/doc/administrator-handbook.md b/doc/administrator-handbook.md new file mode 100644 index 00000000..ac1c1b01 --- /dev/null +++ b/doc/administrator-handbook.md @@ -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. diff --git a/doc/background.md b/doc/background.md new file mode 100644 index 00000000..f45d306d --- /dev/null +++ b/doc/background.md @@ -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. diff --git a/doc/compose-server.md b/doc/compose-server.md new file mode 100644 index 00000000..94859a29 --- /dev/null +++ b/doc/compose-server.md @@ -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. diff --git a/doc/treefile.md b/doc/treefile.md index 0a18e45e..e69de29b 100644 --- a/doc/treefile.md +++ b/doc/treefile.md @@ -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.