fedup - the Fedora Upgrader

Will Woods [email protected] :fedup_dracut: https://github.com/wgwoods/fedup-dracut/ :fedup_fedora: http://fedoraproject.org/wiki/FedUp :fedup_treeinfo: https://github.com/wgwoods/fedup/blob/master/fedup/treeinfo.py :example_treeinfo: http://download.fedoraproject.org/pub/fedora/linux/releases/20/Fedora/x86_64/os/.treeinfo

This is 'fedup', the Fedora Upgrade tool. This repo/package has the following contents:

Frontend / pre-upgrade:: This is the GUI/CLI frontend. It's responsible for setting up the system to be upgraded: downloading packages, modifying the bootloader, etc. * Files: fedup/, fedup.py, fedup-gtk.py (and ui/)

Upgrade services:: Part of a distro-neutral framework for performing major system upgrades using 'systemd' and 'dracut', with a 'plymouth' progress screen. This part lets your system switch back to the upgrade initramfs after setting up your disks. * Files: systemd/

The actual upgrade is handled inside the initramfs by 'fedup-dracut', which can be found here: {fedup_dracut}

How to test (for Fedora users)

fedup is packaged in Fedora 17 and later; to upgrade to the most recent released version of Fedora 18 over the network, do:

fedup --network 18

NOTE: if you're upgrading to Fedora 21, you'll need to add an appropriate --product option. See https://fedoraproject.org/wiki/Upgrading for more information.

If you want to use upgrade images from a test tree that's not in the Fedora mirror system, do:

fedup --network 18 --instrepo TEST-TREE-URL

The URL should be the directory that contains .treeinfo (usually the /os/ dir.)

If you want to install from media, make sure it's mounted and then run

fedup --device

More information for Fedora users and testers can be found on the {fedup_fedora}[Fedora wiki].

Building it yourself

For you brave pioneers who want to do it all yourselves, you will need at least two systems: one with the new release (to build upgrade images), and then any old systems you want to upgrade.

Building upgrade images

You'll need a system running the _new_ release for this.

See {fedup_dracut}[the fedup-dracut README] for details, but roughly:

. Install 'fedup-dracut' and its dependencies
    * deps: 'dracut', 'rpm-devel', 'plymouth-devel', 'glib2-devel'
. `make install`
. `./makefeduprepo REPODIR`
    * this requires 'createrepo'
. Copy REPODIR somewhere HTTP-accessible

Upgrading old system using `fedup`

. Install build requirements * 'python-devel', 'systemd-devel' . Install frontend(s) and systemd support files * make install . Run fedup to prepare system * fedup --network 18 --instrepo http://your-repo.host/REPODIR ** This will take a while. Be patient. ** You can cancel it and it'll resume downloading where it left off. . Reboot * System Upgrade boot menu item will be chosen automatically . Wait 60-90 minutes for the upgrade to complete . Enjoy your newly-upgraded system * upgrade logs are in /var/log/upgrade.log

How network upgrades work

There's two simple rules that control where fedup looks for packages and boot images when doing network upgrades.

Given fedup --network $VERSION, fedup will:

1. Use the existing repo configuration, with $releasever set to $VERSION
2. Add an extra 'instrepo' for fetching boot images; this repo defaults to roughly the following config:

[instrepo] name=instrepo metalink=https://mirrors.fedoraproject.org/metalink/repo=fedora-install-$releasever&arch=$basearch gpgcheck=1 gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$releasever-$basearch

$VERSION could be any string; currently fedup accepts "rawhide" or numbers greater than the current system version. No explicit validation of $VERSION is done beyond that.

If the user gives an invalid version (e.g. fedup --network 31337), fedup will still set up repos and attempt to contact them, but they won't be found, which will cause the upgrade to fail. So invalid versions are implicitly rejected.

For repo maintainers

There's two basic requirements for your repos to work with `fedup`:

. The URLs in your `.repo` file must work for any valid `$releasever`, and
. The GPG key for the _new_ `$releasever` needs to be in your `-release`
  package.

Details on these requirements are below.

Upgradable URLs
^^^^^^^^^^^^^^^
For fedup to be able to find the new version of your repo, the URLs in your
`.repo` file must work for any valid `$releasever` (including "rawhide", if
that's a release you care about.)

Conversely, you should also ensure that the URLs _don't_ work for _invalid_
versions - avoid wildcard redirects, or URLs without `$releasever`. This is
needed to make `fedup` reject invalid `$releasever` values.

This also means that if you change the layout of your repos, you should set up
symlinks/redirects for the old URL schemes, or push out an update that moves
existing `.repo` files to the new scheme.

Signature checking and GPG keys
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When `fedup` encounters a package that was signed with an untrusted key, it
will automatically import the `gpgkey` listed in the associated `.repo` file
if _all_ the following conditions are met:

* The key exists on the local disk (i.e. `gpgkey=file:///.../gpgkey-$releasever`
  exists),
* the keyfile belongs to an installed package,
* that package was signed by a key that is trusted by RPM, and
* the keyfile has not been modified since being installed.

For example, Fedora 19's `fedora.repo` file has

  gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$releasever-$basearch

and the `fedora-release-19` packages also contain GPG keys for Fedora 20.

The `fedora-release-19` package is signed with the Fedora 19 key, so if the
system administrator has "trusted" that key, we can assume that the Fedora 20
key provided by that package is equally trustworthy, and automatically import
it.

This lets fedup verify the authenticity of all the _packages_ shipped in the
new repos.

Verifying boot images
^^^^^^^^^^^^^^^^^^^^^
// Apologies for the weird formatting in the next paragraph but
// mixing footnotes and backticks makes some asciidoc formatters weird :/

+fedup+ finds the boot images inside +instrepo+ by reading the +.treeinfo+ file
and downloading the appropriate +kernel+ and +upgrade+ images.
footnote:[See {example_treeinfo}[this example file] or
          {fedup_treeinfo}[the fedup source] for more information.]

To ensure the boot images are authentic, `fedup` downloads
`$INSTREPO/.treeinfo.signed`, and verifies it using `instrepo`'s GPG key. If
the signature is OK, and the boot images match the checksums in that file,
the boot images are considered authentic. Otherwise `fedup` refuses to proceed
with the upgrade.

So: if you're responsible for creating your own `instrepo`, you'll need to
make sure it has a signed copy of `.treeinfo` at `.treeinfo.signed`.
// vim: syntax=asciidoc tw=78: