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.
For Fedora Silverblue and Fedora CoreOS, which use rpm-ostree, you may refer to link:++https://rpm-ostree.readthedocs.io/en/latest/manual/administrator-handbook/++[Read The Docs: rpm-ostree] 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.
Change the `--releasever=` number if you want to upgrade to a different release.
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 Fedora `27`, you may want to upgrade just to Fedora `28`.
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.
+
If you are upgrading to Rawhide, you will need to import the RPM GPG key for it.
This will be the highest numbered key version in `/etc/pki/rpm-gpg/`.
For example, if there is a Branched release that is `30`, then you should look for a `31`, and if there is currently no Branched release, it will be `30`:
. If some of your packages have unsatisfied dependencies, the upgrade will refuse to continue until you run it again with an extra `--allowerasing` option.
This often happens with packages installed from third-party repositories for which an updated repositories hasn't been yet published.
Study the output very carefully and examine which packages are going to be removed.
None of them should be essential for system functionality, but some of them might be important for your productivity.
+
* 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.
Otherwise the whole package cache will be removed after your operation, and you will need to download all the packages once again.
. Once the upgrade process to complete, your system will reboot into the updated release version of Fedora.
[[sect-optional-post-upgrade-tasks]]
== Optional Post-Upgrade Tasks
These are some of the tasks you can do after a successful upgrade.
[NOTE]
====
This section is mainly intended for power users. If you are a general user who doesn't use the terminal daily, you may skip this section.
====
[[sect-update-system-configuration-files]]
=== Update System Configuration Files
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:
[source,bash]
----
dnf install rpmconf
----
Once the install is complete enter:
[source,bash]
----
sudorpmconf-a
----
For more information you can refer to the man pages (`man rpmconf`).
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.
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.
=== Using distro-sync To Resolve Dependency Issues
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:
[source,bash]
----
sudodnfdistro-sync
----
You can also use the `--allowerasing` option will remove packages with dependencies that can not be satisfied.
Always review which packages will be removed before confirming this:
This may happen if SELinux was disabled at some point in the past.
To relabel the entire system run:
[source,bash]
----
sudotouch/.autorelabel
----
and reboot.
The boot process may take a long time as it is checking and fixing all SELinux permission labels on all the files in your system.
[[sect-frequently-asked-questions]]
== Frequently Asked Questions
[[sect-how-do-i-report-issues-with-the-upgrades]]
=== How Do I Report Issues With The Upgrade?
. See link:++https://fedoraproject.org/wiki/Bugs/Common++[Common bugs] to check if it is a known problem the community is already aware of.
. Search link:++https://bugzilla.redhat.com/buglist.cgi?product=Fedora&component=dnf-plugin-system-upgrade&resolution=---++[Bugzilla for an existing bug report].
If you do not see a report that matches your symptoms, you can file a new report from the search page.
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`.
If you encounter any issues after the upgrade with a specific package, file a bug against the package with which you are having issues.
=== Does DNF System Upgrade Verify The Software It Runs or Installs During An Upgrade?
Yes.
The package signing keys for the newer Fedora release are sent to older Fedora releases to allow DNF to verify the integrity of the downloaded packages.
You can disable this function if needed, but is not recommended as you will be open to attacks from malicious software.
=== Will Packages In Third-Party Repositories Be Upgraded?
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/`.)
Commonly used third-party repositories like RPM Fusion should work.
However, if attempting to upgrade prior to, or soon after, an official Fedora release, they may not have updated their repository paths, and DNF may be unable to find their packages.
Usually, this should not prevent the upgrade from running successfully.
Also, you can update packages from the third-party repository later.
=== Can I upgrade from an End-Of-Life (EOL) Release?
It is strongly recommended to upgrade an EOL release on any production system, or any system connected to the public internet.
Any upgrade from Fedora 20 or earlier is done *at your own risk* as DNF was not the default package management tool.
However, if you do have a release newer than Fedora 20 that is EOL, you can attempt to do an upgrade, but this method is *not supported*.
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.
Again this is un-supported and is *at your own risk*.
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, or once every two releases.