mirror of
https://pagure.io/fedora-docs/quick-docs.git
synced 2024-11-25 13:44:51 +00:00
328 lines
No EOL
10 KiB
Text
Executable file
328 lines
No EOL
10 KiB
Text
Executable file
[[chap-dnf-system-upgrade]]
|
||
= DNF System Upgrade
|
||
|
||
link:++https://github.com/rpm-software-management/dnf-plugin-system-upgrade++[`dnf-plugin-system-upgrade`] is a plugin for the link:++dnf.html++[DNF] package manager and is used to upgrade your system to the current release of Fedora.
|
||
For Atomic Host, which uses rpm-ostree, you may refer to link:++https://rpm-ostree.readthedocs.io/en/latest/manual/administrator-handbook/++[Read The Docs: rpm-ostree] for details.
|
||
|
||
This is the recommended command-line upgrade method for Fedora 21 and later and works as follows:
|
||
|
||
. Packages are downloaded while the system is running normally
|
||
|
||
. The system reboots into a special environment (implemented as a systemd target) to install them
|
||
|
||
. Upon completion, the system reboots into the new Fedora release
|
||
|
||
[[sect-performing-system-upgrade]]
|
||
== Performing System Upgrade
|
||
|
||
[WARNING]
|
||
====
|
||
|
||
*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.
|
||
|
||
====
|
||
|
||
. To update your Fedora release from the command-line do:
|
||
+
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf upgrade --refresh
|
||
|
||
----
|
||
+
|
||
and reboot your computer.
|
||
|
||
. Install the dnf-plugin-system-upgrade package if it is not currently installed:
|
||
+
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf install dnf-plugin-system-upgrade
|
||
|
||
----
|
||
|
||
. Download the updated packages (replace N with the release version):
|
||
+
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf system-upgrade download --refresh --releasever=N
|
||
|
||
----
|
||
|
||
. Trigger the upgrade process. This will restart your machine into the upgrade process:
|
||
+
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf system-upgrade reboot
|
||
|
||
----
|
||
|
||
. 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]
|
||
|
||
----
|
||
|
||
sudo rpmconf -a
|
||
|
||
----
|
||
|
||
For more information you can refer to the man pages (`man rpmconf`).
|
||
|
||
[[sect-clean-up-old-packages]]
|
||
=== Clean-Up Old Packages
|
||
|
||
You can see a list of packages with broken dependencies by typing:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf repoquery --unsatisfied
|
||
|
||
----
|
||
|
||
The list should be empty, but if this is not the case consider removing them as they are not likely to work.
|
||
|
||
You can see duplicate packages (packages with multiple versions installed) with:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf repoquery --duplicated
|
||
|
||
----
|
||
|
||
For packages from the official repositories, the latest version should be installed.
|
||
However, some packages that are still on your system may no longer be in the repositories.
|
||
To see a list of these packages do:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf list extras
|
||
|
||
----
|
||
|
||
If you see a package you do not need, or use, you can remove it with:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf remove $(dnf repoquery --extras --exclude=kernel,kernel-\*)
|
||
|
||
----
|
||
|
||
[NOTE]
|
||
|
||
====
|
||
|
||
Run `sudo dnf update` first, as this list is only valid if you have a fully updated system.
|
||
Otherwise, you will see a list of installed packages that are no longer in the repositories because an update is available.
|
||
This list may also contain packages installed from third-party repositories who may not have updated their repositories.
|
||
|
||
====
|
||
|
||
You can safely remove packages no longer in use with:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf autoremove
|
||
|
||
----
|
||
|
||
[WARNING]
|
||
|
||
====
|
||
|
||
DNF decides that a package is no longer needed if you haven't explicitly asked to install it and nothing else requires it.
|
||
However, that doesn't mean that the package is not useful or that you don't use it.
|
||
*Only remove what you are sure you don't need*.
|
||
|
||
====
|
||
|
||
[[sect-resolving-post-upgrade-issues]]
|
||
== Resolving Post-Upgrade Issues
|
||
|
||
[NOTE]
|
||
|
||
====
|
||
|
||
Only follow these steps if you encounter problems with your upgraded system.
|
||
|
||
====
|
||
|
||
[[sect-rebuilding-rpm-database]]
|
||
=== Rebuilding the RPM Database
|
||
|
||
If you see warnings when working with RPM/DNF tools, your database might be corrupt.
|
||
It is possible to rebuild it to see if resolves your issues. Always back up `/var/lib/rpm/` first.
|
||
To rebuild the database, run:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo rpm --rebuilddb
|
||
|
||
----
|
||
|
||
[[sect-using-distro-sync-to-resolve-dependency-issues]]
|
||
=== 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]
|
||
|
||
----
|
||
|
||
sudo dnf distro-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:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo dnf distro-sync --allowerasing
|
||
|
||
----
|
||
|
||
[[sect-relabel-files-with-the-latest-selinux-policy]]
|
||
=== Relabel Files With The Latest SELinux Policy
|
||
|
||
If you encounter any warnings regarding policies with SELinux, some files may have incorrect SELinux permissions.
|
||
This may happen if SELinux was disabled at some point in the past.
|
||
To relabel the entire system run:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
sudo touch /.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.
|
||
|
||
[[sect-does-dnf-system-upgrade-verify-the-software-it-runs-or-installs-during-an-upgrade]]
|
||
=== 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.
|
||
|
||
[[sect-will-packages-in-third-party-repositories-be-upgraded]]
|
||
=== 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.
|
||
|
||
[[sect-can-i-upgrade-from-an-end-of-life-release]]
|
||
=== 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*.
|
||
|
||
[[sect-how-many-releases-can-i-upgrade-across-at-once]]
|
||
=== Can I do a single upgrade across many releases (i.e. 20-27)?
|
||
|
||
It is highly recommended to upgrade across just one release (e.g. 27 to 28).
|
||
However, for the first month or so after a new release, upgrades from the last-but-one release are 'supported' (N-2, where N is the current release).
|
||
The link:fedora-life-cycle.html++[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.
|
||
|
||
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 end-of-life, but the time period after the new release may be uncertain.
|
||
|
||
Upgrades across more than two releases are *not supported*, and issues encountered with such upgrades may not be considered significant bugs.
|
||
|
||
When upgrading across multiple releases, you may need to import the GPG key for the release you want to update to. You can do this with:
|
||
|
||
[source,bash]
|
||
|
||
----
|
||
|
||
gpg --quiet --with-fingerprint /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-N-primary
|
||
|
||
----
|
||
|
||
(where N is the Fedora version.)
|
||
|
||
Refer to the link:++https://getfedora.org/keys/faq/++[getfedora.org FAQ on Keys] for details.
|
||
|
||
[[sect-can-i-use-dnf-system-upgrade-to-upgrade-to-a-pre-release]]
|
||
=== Can I Use DNF System Upgrade To Upgrade To A Pre-Release (e.g. a Beta)?
|
||
|
||
Yes, but this is subject to temporary breakage as with any other aspect of a pre-release. |