link:++https://github.com/rpm-software-management/dnf-plugins-extras++[`dnf-plugin-system-upgrade`] is a plugin for the xref:dnf.adoc[DNF] package manager and is used to upgrade your system to the current release of Fedora Linux.
For Fedora Silverblue and Fedora CoreOS, which use rpm-ostree, you may refer to link:++https://coreos.github.io/rpm-ostree/administrator-handbook/++[rpm-ostree documentation] for details.
*Back up your data* before performing a system-wide upgrade as every system upgrade is potentially risky.
As a precaution, download the link:++https://getfedora.org/en/workstation/download/++[Fedora Workstation Live image] in the event something goes wrong.
*Important:* Do not skip this step. System updates are required to receive signing keys of higher-versioned releases, and they often fix problems related to the upgrade process.
Most people will want to upgrade to the latest stable release, which is `{MAJOROSVER}`, but in some cases, such as when you're currently running an older release than `{PREVVER}`, you may want to upgrade just to Fedora Linux `{PREVVER}`. System upgrade is only officially supported and tested over 2 releases at most (e.g. from `{PREVPREVVER}` to `{MAJOROSVER}`). If you need to upgrade over more releases, it is recommended to do it in several smaller steps (<<sect-how-many-releases-can-i-upgrade-across-at-once,read more>>).
You can also use `{NEXTVER}` to upgrade to a link:https://fedoraproject.org/wiki/Releases/Branched[Branched] release, or `rawhide` to upgrade to link:https://fedoraproject.org/wiki/Releases/Rawhide[Rawhide]. Note that neither of these two are stable releases. For details about the upgrade process and common issues related to those two releases, please look at appropriate sections on aforelinked pages.
. If some of your packages have unsatisfied dependencies, the upgrade will refuse to continue until you run it again with an extra `--allowerasing` option.
* In case of unsatisfied dependencies, you can sometimes see more details if you add `--best` option to the command line.
* If you want to remove/install some packages manually before running `dnf system-upgrade download` again, it is advisable to perform those operations with `--setopt=keepcache=1` dnf command line option.
. When the new GPG key is imported, you are asked to verify the key's fingerprint. Refer to link:https://fedoraproject.org/security[https://fedoraproject.org/security] to do so.
. Trigger the upgrade process. This will reboot your machine (immediately!, without a countdown or confirmation, so close other programs and save your work) into the upgrade process running in a console terminal:
Most configuration files are stored in the `/etc` folder.
If you have changed the package's configuration files, RPM creates new files with either `.rpmnew` (the new default config file), or `.rpmsave` (your old config file backed up).
You can search for these files, or use the `rpmconf` tool that simplifies this process. To install rpmconf, enter:
Some third-party packages drop edited configuration files in `/etc/yum.repos.d/` and reverting these files to their original versions may disable updates for the software.
If you use `rpmconf` to upgrade the system configuration files supplied with the upgraded packages then some configuration files may change. After the upgrade you should verify `/etc/ssh/sshd_config`, `/etc/nsswitch.conf`, `/etc/ntp.conf` and others are expected. For example, if OpenSSH is upgraded then `sshd_config` reverts to the default package configuration. The default package configuration *does not* enable public key authentication, and allows password authentication.
Systems with the link:++https://docs.fedoraproject.org/en-US/quick-docs/installing-grub2/#installing-grub-2-on-a-bios-system++[BIOS firmware] have the GRUB RPM packages updated. However, the installed or embedded bootloader is never updated automatically. It is a good idea to update it between Fedora Linux release versions.
If you upgrade across two releases (e.g. Fedora Linux {PREVPREVVER} to {MAJOROSVER}), you must supply the old release version to `remove-retired-packages`:
After you boot into the latest kernel and test the system you can remove previous kernels. Old kernels remain even after `dnf autoremove` to avoid unintentional removals.
One of the easier ways to remove old kernels is with a script that retains the latest kernel. The script below works whenever Fedora updates a kernel, and does not depend upon a system upgrade.
=== Clean-up old keys trusted for RPM package signing
Keys from older Fedora releases and third-party repositories will accumulate in the RPM database over time. You can remove keys no-longer referenced from `/etc/yum.repos.d/` with:
There may be some dangling symlinks in the filesystem after an upgrade. You can clean the dangling links by installing the symlinks utility and deleteing the old links.
The system upgrade tool uses `dnf distro-sync` by default.
If your system is partly upgraded or you see some package dependency issues, try running another distro-sync manually to see if this fixes the problem.
This will attempt to make your installed packages the same version in your currently enabled repositories, even if it must downgrade some packages:
. Search link:++https://bugzilla.redhat.com/buglist.cgi?component=dnf-plugins-core&list_id=13370526&product=Fedora&resolution=---++[Bugzilla for an existing bug report] filed against the system-upgrade plug-in.
Please follow the bug reporting instructions mentioned in the link:++https://github.com/rpm-software-management/dnf-plugin-system-upgrade/blob/master/README.md++[README from the GitHub repo] or in `man dnf.plugin.system-upgrade`.
The package signing keys for the newer Fedora Linux release are sent to older releases to allow DNF to verify the integrity of the downloaded packages.
Yes, if they are configured like regular DNF repositories and the version numbers are not hard-coded in the repository file (usually found in `/etc/yum.repos.d/`).
However, if attempting to upgrade prior to, or soon after, an official Fedora Linux release, they may not have updated their repository paths, and DNF may be unable to find their packages.
You may try to upgrade through intermediate releases until you reach a currently-supported release, or try to upgrade to a currently-supported release in a single operation.
Upgrades to the very next release (e.g. `{PREVVER}` to `{MAJOROSVER}`) as well as upgrades skipping one release (e.g. `{PREVPREVVER}` to `{MAJOROSVER}`) are both supported. However, it is highly recommended to perform the upgrade before your release reaches End of Life (EOL). That happens roughly a month after N+2 release has been released (when you're currently on release N). The link:https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle[Fedora Release Life Cycle] is specifically designed to provide this approximate one month "grace period" to allow users the choice to upgrade their systems on a yearly basis, i.e. once every two releases. You can study link:https://fedoraproject.org/wiki/Releases[Releases] to see the current release status and schedule. Around a month after the new release comes out, the last-but-one release becomes End of Life (EOL). The upgrade is likely to work successfully after the release goes EOL, but the time period after the new release may be uncertain.
