fedup - the Fedora Upgrader

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: https://github.com/wgwoods/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 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 the fedup-dracut README for details, but roughly:

1. Install fedup-dracut and its dependencies

   • deps: dracut, rpm-devel, plymouth-devel, glib2-devel

2. make install

3. ./makefeduprepo REPODIR

   • this requires createrepo

4. Copy REPODIR somewhere HTTP-accessible

Upgrading old system using fedup

1. Install build requirements

   • python-devel, systemd-devel

2. Install frontend(s) and systemd support files

   • make install

3. 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.

4. Reboot

   • System Upgrade boot menu item will be chosen automatically

5. Wait 60-90 minutes for the upgrade to complete

6. 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:

1. The URLs in your .repo file must work for any valid $releasever, and

2. 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

fedup finds the boot images inside instrepo by reading the .treeinfo file and downloading the appropriate kernel and upgrade images. ^[1]

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.

---

1. See this example file or the fedup source for more information.