From Fedora Project Wiki

(don't create grub2-efi.cfg symlink - it is created by the rpm)
m (remove misleading reference to F23. DNF works on F21 too.)
 
(138 intermediate revisions by 53 users not shown)
Line 1: Line 1:
{{admon/note|New Software and Documentation|FedUp is new for Fedora 18 and as such, will be changing before Fedora 18 is released. If you find this documentation to be wrong or out of date, please fix it or let someone know}}
{{autolang|base=yes}}


{{admon/caution|Draft Page|This page is still a draft and is being actively edited, it should be mostly complete but will likely change some in the next day or so}}
{{deprecated|FedUp (FEDora UPgrader) was the official tool for upgrading between Fedora releases, until the introduction of the [[DNF_system_upgrade|DNF system upgrade plugin]]. FedUp is now obsolete and should not be used in any circumstances.}}


== What is FedUp? ==


FedUp (FEDora UPgrader) is the name of a new system for upgrading Fedora installs starting with Fedora 18. It will be replacing all of the currently recommended upgrade methods ([[PreUpgrade]] and DVD) that have been used in previous Fedora releases.
= What is FedUp? =


Currently, FedUp is capable of upgrading Fedora 17 installs to Fedora 18 using a networked repository, similar to how [[PreUpgrade]] worked. More methods for upgrade are currently planned and this page will be updated as those features are completed.
FedUp (FEDora UPgrader) is the official tool for upgrading Fedora installations. Anaconda, the Fedora installer program, has no built-in upgrade functionality. Upgrade from one release of Fedora to the immediate successor has been completely delegated to FedUp. Fedup may use a network repository or a DVD image for the package sources.


{{admon/warning|Fedora 16 and Older|The FedUp client does not build or run on anything older than Fedora 17. If you want to upgrade an older Fedora installation, please [[Upgrade|upgrade]] to Fedora 17 before continuing}}
= What Does FedUp do? =


== What Does FedUp do? ==
The FedUp system consists of two parts - the client, used to download packages and prepare for the upgrade and a pre-boot environment. The pre-boot environment does the actual upgrade using [[Systemd|systemd]] and [[dnf]] (or yum). More details are available in [http://ohjeezlinux.wordpress.com/2012/11/13/fedup-a-little-background/ a blog post written by FedUp's primary author].


The FedUp system consistes of two parts - the client used to download packages and prepare for the upgrade and a pre-boot environment which does the actual upgrade using [[Systemd|systemd]] and yum. More details are available in [http://ohjeezlinux.wordpress.com/2012/11/13/fedup-a-little-background/ a blog post written by FedUp's primary author]
Files are downloaded to <code>/var/cache/system-upgrade</code> and will be automatically cleaned up after the upgrade process is finished.


=== The FedUp Client ===
== The FedUp Client ==


The FedUp client runs on the system to be upgraded. It gathers the packages needed for upgrade in addition to downloading the required initramfs and kernel needed for the actual upgrade. At this time, only fedup-cli is implemented but a GUI interface is expected before Fedora 18 is released.
The FedUp client runs on the system to be upgraded. It gathers the packages needed for upgrade in addition to downloading the required initramfs and kernel needed for the actual upgrade. At this time, only the fedup command-line interface is implemented but a GUI interface is expected...sometime.


=== The Upgrade ===
== The Upgrade ==


{{admon/note|Plymouth Theme During Upgrade|Unfortnately, the FedUp plymouth theme is not used when upgrading with the initramfs distributed with Fedora 18 beta. This is a known issue and will be fixed before Fedora 18 is released}}
The actual upgrade takes place when the system has been rebooted after running the FedUp client. The filesystems are mounted during boot, the already downloaded packages are installed and some upgrade-related tasks are performed. During the upgrade process, a special plymouth theme is used which has a progress bar to indicate current upgrade progress.
 
== The Aftermath ==
 
Once the upgrade is complete, FedUp will reboot the system automatically. This is so you can run this part of the process unattended and later return to the upgraded system, if you leave any bootable media attached to the system during the upgrade process, once the upgrade has completed, the system may boot from that medium instead of the hard disk. If you return to see the Fedora installer or something similar...that's probably what happened!


The actual upgrade takes place when the system has been rebooted after running the FedUp client. The filesystems are mounted during boot, the already downloaded packages are installed and some upgrade-related tasks are performed. During the upgrade process, a special plymouth theme is used which has a progress bar to indicate current upgrade progress.
= Frequently Asked Questions =


== Frequently Asked Questions ==
== How do I report issues that I find with upgrades? ==
=== Can I upgrade a Fedora 16 system with FedUp? ===
First see [[Common F21 bugs]] or [[Common F22 bugs]] to check if the problem is a very prominent issue we already know of. If it is not there, the component for reporting problems depends on the exact issue that you hit:
No, this is not currently possible. The FedUp client does not currently build or run on Fedora 16 and you need to be running at least Fedora 17 in order to run the client?
=== How do I report issues that I find with upgrades? ===
The answer to this depends on the exact issue that you hit.


==== Issues with upgrade preparation ====
=== Issues with upgrade preparation ===
If you hit issues when using the FedUp client ({{package|fedup}}) before reboot, search for or file a bug against fedup using the version you are upgrading '''from'''.
If you hit issues when using the FedUp client ({{package|fedup}}) before reboot, [https://bugzilla.redhat.com/buglist.cgi?product=Fedora&component=fedup&resolution=--- search] or file a bug against FedUp using the version you are upgrading '''from'''.


==== Issues During Upgrade ====
=== Issues During Upgrade ===
If you hit issues after upgrade preparation and the initial reboot, search for or file a bug against {{package|fedup-dracut}} using the version you are upgrading '''to'''.
If you hit issues after upgrade preparation and the initial reboot, [https://bugzilla.redhat.com/buglist.cgi?product=Fedora&component=fedup-dracut&resolution=--- search] or file a bug against {{package|fedup-dracut}} using the version you are upgrading '''to'''.


==== Issues After Upgrade ====
=== Issues After Upgrade ===
If you hit issues after upgrade with a specific package, file a bug against the package with which you are having issues.
If you hit issues after upgrade with a specific package, file a bug against the package with which you are having issues.


=== How do I Debug Issues During Upgrade ===
== How do I Debug Issues During Upgrade? ==
A troubleshooting and debug guide will be written soon and linked to from here.
A troubleshooting and debug guide will be written at some point and linked to from here.
 
== Does FedUp verify the software it runs or installs during upgrade? ==
 
Yes. The package signing keys for newer Fedora releases are sent to older Fedora releases in order to allow FedUp to verify the integrity of the packages it downloads. You can disable this function with the --nogpgcheck parameter if you need to do so for any reason.
 
== Will packages in third party repositories be upgraded? ==
 
Yes, if they are set up like regular yum/dnf repositories and do not hard code the repository path. Commonly-used third party repositories usually work fine, but if you attempt to upgrade prior to or soon after an official Fedora release, they may not have updated their repository paths yet, and FedUp may be unable to find their packages. This will usually not prevent the upgrade running successfully, though, and you can update the packages from the third-party repository later.


=== Where can I ask Questions ===
== Can I use FedUp to upgrade to a pre-release (e.g. a beta)? ==
For now, the best place to ask questions is probably #fedora-qa on Freenode IRC or the [https://admin.fedoraproject.org/mailman/listinfo/test Fedora Test list].


== How Can I Upgrade My System with FedUp? ==
Yes. After a Fedora release has been branched, it should be possible to upgrade to it using FedUp. It should also work after the Alpha and Beta releases. Of course, this function is as subject to temporary breakage as is any other aspect of a pre-release.


{{admon/note|Upgrading to Pre-Release|These instructions are currently written for upgrading to Fedora 18 beta. If you want to try upgrading to the final pre-release, check out the [[QA:Testcase_upgrade_fedup_cli_previous_desktop|upgrade test case]]. However, there may be bugs in the newer process if you use it before the release of Fedora 18 - if you try it, be aware that you may run into problems}}
See this [http://lists.fedoraproject.org/pipermail/devel/2013-May/183508.html email to the Fedora devel mailing list] for more details.


= How Can I Upgrade My System with FedUp? =
As alluded to above, there are three parts to upgrading with FedUp - preparation, execution and cleanup.
As alluded to above, there are three parts to upgrading with FedUp - preparation, execution and cleanup.


=== Preparing for the Upgrade ===
Before you start doing anything, be sure to have a look at [[Common F21 bugs#Upgrade_issues]] or [[Common F22 bugs#Upgrade_issues]] and read about the most common bugs found.
 
== Upgrading from Fedora 20 or earlier: Products ==
In order to select one of the new Fedora flavors, FedUp has a new option, {{code|<nowiki>--product=<PRODUCT></nowiki>}}. When upgrading from Fedora 20 or earlier to Fedora 21 or later, you must pass this {{code|--product}} option.
 
You can use the values {{code|workstation}}, {{code|server}}, {{code|cloud}} or {{code|nonproduct}}. If you upgrade to [[Workstation]] or [[Server]], all the packages that are included in a default installation of that flavor will be installed after the upgrade (that is, any that are not currently installed will be added). Your firewall configuration will also be reset to the default for that flavor (in the Workstation case, this is a fairly open configuration). If you do not wish these things to happen, use the value {{code|nonproduct}}.
 
== Preparing for the Upgrade ==


{{admon/important|Latest fedup|Make sure that you install the latest version of the fedup client on the system to be upgraded. At the time of this writing (2012-11-26), that is fedup-0.7.1-1.fc17}}
# Do a full system update and reboot to ensure that any kernel changes are running
# Do a full system update and reboot to ensure that any kernel changes are running
# Install {{package|fedup}}
# Install/Update {{package|fedup}}
#* Be sure to get the latest release, this may involve enabling updates-testing (put <code>--enablerepo=updates-testing</code> between {{command|yum}} and {{command|install}} on the command line)
# Usually, it is best to try first with the latest fedup available in the stable update repository for the release you are running. If you encounter problems with the upgrade, and a newer fedup is available in the updates-testing repository for your current release, you may wish to try with this newer version: {{command|yum --enablerepo<nowiki>=</nowiki>updates-testing install fedup}} or with dnf: {{command|dnf --enablerepo<nowiki>=</nowiki>updates-testing install fedup}} at the command line)
# Find the URL of the branched TC or RC under test. For Fedora 18 beta, this URL would be <nowiki>http://dl.fedoraproject.org/pub/fedora/linux/releases/test/18-Beta/Fedora/<arch>/os</nowiki>. You can also substitute the root of a local mirror instead of using the main download site.
# Make sure the system is running a Fedora issued kernel if possible -- if you use your own kernel and it does not have a corresponding initramfs, the upgrade will fail.
#* <arch> is the name of the arch running on the install to be upgraded (i386, x86_64 ...)
# Start the upgrade prep by executing following command
#* {{command|sudo fedup-cli --network 18 --debuglog fedupdebug.log --instrepo <URL>}}
#* <URL> is the location found in the previous step
# Check the {{filename|fedupdebug.log}} file if any errors show up in the output from {{command|fedup-cli}}


=== Executing the Upgrade ===
There are three options for sourcing the packages needed for upgrade - using a network repository, a local ISO file or a local device (hard drive, optical disk etc).
{{admon/note|Monitoring Upgrade Progress|At this time, the FedUp progress during the actual upgrade is not shown automatically, but you can trigger it manually}}


# Reboot the system if {{command|fedup-cli}} has completed without error.
{{admon/important|Network upgrade is strongly recommended|It is strongly recommended to use the network upgrade instead of offline update modes (ISO, local device). Network upgrade will ensure you receive the latest packages from the target release. If you use local media containing older packages, you might end up with a mixture of packages from your former and target release, and the system might not work properly until you fully update it after reboot (if it boots at all).}}
# Once the system reboots, there should be a new entry in the GRUB menu titled {{command|System Upgrade}}.
 
# Select the {{command|System Upgrade}} option from the GRUB menu
=== Network ===
#* If you want to be able to see progress during the upgrade, append <code>plymouth.splash=fedup</code> to the end of the kernel parameters (line starting with <code>linux</code>)
Using a network source is the easiest method of upgrading and will pull in updates while upgrading - eliminating the potential issue if your current system has a newer kernel version than the Fedora release to which you are upgrading.
 
Start the upgrade prep by executing following command:
 
* {{command|sudo yum update fedup fedora-release}}
 
or with dnf for Fedora 22 and later versions:
 
* {{command|sudo dnf upgrade fedup fedora-release}}
 
If you are upgrading from Fedora 20 to Fedora 21, run the following command:
 
* <code>sudo fedup --network 21 --product=[workstation | server| cloud | nonproduct]</code>
 
If you are upgrading from Fedora 21 to Fedora 22 or above, run the following command:
 
* {{command|sudo fedup --network 22}}
 
Once the preparations have completed, check the {{filename|/var/log/fedup.log}} file if any errors show up in the output from {{command|fedup}}
 
=== ISO File ===
Older Fedora releases included an installation image with a large number of packages, making it suitable for upgrading some systems.  Upgrading by booting this image was possible until Fedora 17, and using the image for upgrades with Fedup was supported until Fedora 20. Beginning with Fedora 21, the universal DVD image is not produced; as of now, there is no media available for offline upgrades.
 
=== Other Device ===
Optical drives and other mountable storage can also be used as a package source for upgrade preparations.
 
# Mount the source material
#* For the sake of example, we will assume that this source is mounted at {{filename|/mnt/fedora}} but you can mount it anywhere as long as you replace {{filename|/mnt/fedora}} in the command below with the actual mounted location of the upgrade source.
# Start the upgrade preparations by executing the following command
#* {{command|sudo fedup --device /mnt/fedora --debuglog<nowiki>=</nowiki>fedupdebug.log}}
# Once the preparations have completed, check the {{filename|fedupdebug.log}} file if any errors show up in the output from {{command|fedup}}
 
== Executing the Upgrade ==
# Reboot the system if {{command|fedup}} has completed without error.
# Once the system reboots, there should be a new entry in the GRUB menu titled {{command|'''System Upgrade'''}}.
# Select the {{command|'''System Upgrade'''}} option from the GRUB menu
#*'''Remark:''' If the {{command|'''System Upgrade'''}} item is not shown in the grublist at boot, it is most often caused by having an incompatible grub, most often installed by another Linux distribution you may have in your multiboot environment. To correct this quickly: reinstall grub:
#*# grub2-mkconfig -o /boot/grub2/grub.cfg
#*# grub2-install /dev/sda '''(replace /dev/sda by any other device you prefer to boot from)'''
# The system should boot into the upgrade process and a plymouth boot screen should be displayed
# The system should boot into the upgrade process and a plymouth boot screen should be displayed
#* Do not press any key, otherwise the progress screen will be killed and you will have no information about the process
#* There is a root shell on virtual terminal two (VT2) so you can tinker with the system if something goes wrong. (To disable this, boot with <code>rd.upgrade.noshell</code>)
# Once the upgrade process has completed, the system will reboot and an option to boot {{FedoraVersion|long|next}} will be on the grub menu
#* Press 'esc' to view a more detailed log. If you switch back to the graphical progress indicator, it may show 0% for the remainder of the upgrade but that does not mean the upgrade has stopped.
# Once the upgrade process has completed, the system will reboot and an option to boot {{FedoraVersion|long|current}} will be on the grub menu
 
== Cleaning Up Post Upgrade ==
 
<!-- Some of the stuff from [https://fedoraproject.org/wiki/User:Fenris02/Distribution_upgrades_and_cleaning_up_after_them] this post upgrade cleanup guide] might be wise -->


=== GRUB Updates ===
It is worth rebuilding the RPM DB to prevent RPMDB checksum error when doing a distribution sync:
{{admon/note|Somewhat Optional|While updating GRUB on your upgraded system isn't strictly required, it is recommended for BIOS systems and '''very strongly''' recommended for UEFI systems due to the transition from grub-efi to grub2-efi}}


==== Updating GRUB2 (BIOS systems) ====
{{command|sudo rpm --rebuilddb}}


* After upgrade, the grub2 you're booting from will still be the F17 version; upgrading must be done manually
There are a collection of post-upgrade things to do. Some of which are fixed by doing a distro sync:
* Follow the steps in [[GRUB_2|this grub2 page]] to reinstall and update grub


==== Updating GRUB (UEFI systems) ====
{{command|sudo yum distro-sync --setopt<nowiki>=</nowiki>deltarpm<nowiki>=</nowiki>0}}
{{admon/note|Secure Boot| Secure Boot functionality was not completed in time for Fedora 18 beta and these instructions do not cover using {{package|shim}} or the signed kernel. Once Secure Boot functionality is available, these instructions will be updated.}}


{{admon/note|Grub Theme|With the migration to grub2-efi in Fedora 18, you will see no grub splash after initial upgrade nor after upgrading to grub2-efi}}
If you have upgraded to Fedora 22 or above, run the following command instead: 


Grub2 is not installed as part of the upgrade process, so you'll have to install it:
(If you run {{command|dnf}} the first time and you're behind a proxy add your proxy settings to {{command|/etc/dnf/dnf.conf}}) 
<pre>
sudo yum install grub2-efi
</pre>


Once the {{package|grub2-efi}} package is installed, we need to add a new EFI boot entry. The easiest way to do this is to just modify the command used when Fedora was first installed. This command can be found in <nowiki>/var/log/anaconda/anaconda.program.log</nowiki> and should end with a command similar to:
{{command|sudo dnf distro-sync --setopt<nowiki>=</nowiki>deltarpm<nowiki>=</nowiki>0}}
<pre>
efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l \EFI\redhat\grub.efi
</pre>


Find the current boot number for fedora using <code>efibootmgr</code>:
The rpmconf tool searches for .rpmnew, .rpmsave and .rpmorig files and asks you what to do with them: Keep current version, place back old version, watch the diff or merge.
<pre>
efibootmgr -v
</pre>


You are looking for a line similar to:
{{command|sudo yum install rpmconf}}
<pre>
Boot0004* Fedora  HD(1,800,34800,6733749f-b42a-4b8c-a0de-5a1d3505f8af)File(\EFI\redhat\grub.efi)
</pre>


The boot number in this example is 0004.
If you have upgraded to Fedora 22 or above, run the following command instead:


Remove the old boot entry using the following command (<nowiki><boot number></nowiki>) is the boot number you found above:
{{command|sudo dnf install rpmconf}}
<pre>
efibootmgr -b <boot number> -B
</pre>


{{admon/warning|Using Quotes|Make sure you put quotes around '\EFI\fedora\grubx64.efi' or bash will interpret \E, \f and \g as control characters and your system will not boot properly}}
{{command|sudo rpmconf -a}}


Once you have the command that was used and the boot number of the old boot entry, you can change it to use the new grub2-efi installation:
If you are using google-chrome from the Google repository, you must re-install google-chrome due to a packaging bug on the Google side of things. Make sure to adjust the command to the build type you would like to install:
<pre>
sudo efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l '\EFI\fedora\grubx64.efi' -b <boot number>
</pre>


In order to get a bootable UEFI system, you need to regenerate the grub configuration and symlink it to <code>/etc/grub2-efi.cfg</code>
{{command|sudo yum remove google-chrome-\* && sudo yum install google-chrome-[beta,stable,unstable]}}
<pre>
grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
</pre>


Once the system reboots, you should be using grub2-efi instead of grub-efi
If you have upgraded to Fedora 22 or above, run the following command instead:


=== Cleaning Up Post Upgrade ===
{{command|sudo dnf remove google-chrome-\* && sudo dnf install google-chrome-[beta,stable,unstable]}}


Some of the stuff from [http://fedorasolved.org/Members/fenris02/post_upgrade_cleanup this post upgrade cleanup guide] might be wise
= Docs TODO =
* Write fedup troubleshooting and debug guide
* add note about blob drivers if needed

Latest revision as of 01:57, 6 November 2015


This page is outdated and is only retained for historical reference
FedUp (FEDora UPgrader) was the official tool for upgrading between Fedora releases, until the introduction of the DNF system upgrade plugin. FedUp is now obsolete and should not be used in any circumstances.



What is FedUp?

FedUp (FEDora UPgrader) is the official tool for upgrading Fedora installations. Anaconda, the Fedora installer program, has no built-in upgrade functionality. Upgrade from one release of Fedora to the immediate successor has been completely delegated to FedUp. Fedup may use a network repository or a DVD image for the package sources.

What Does FedUp do?

The FedUp system consists of two parts - the client, used to download packages and prepare for the upgrade and a pre-boot environment. The pre-boot environment does the actual upgrade using systemd and dnf (or yum). More details are available in a blog post written by FedUp's primary author.

Files are downloaded to /var/cache/system-upgrade and will be automatically cleaned up after the upgrade process is finished.

The FedUp Client

The FedUp client runs on the system to be upgraded. It gathers the packages needed for upgrade in addition to downloading the required initramfs and kernel needed for the actual upgrade. At this time, only the fedup command-line interface is implemented but a GUI interface is expected...sometime.

The Upgrade

The actual upgrade takes place when the system has been rebooted after running the FedUp client. The filesystems are mounted during boot, the already downloaded packages are installed and some upgrade-related tasks are performed. During the upgrade process, a special plymouth theme is used which has a progress bar to indicate current upgrade progress.

The Aftermath

Once the upgrade is complete, FedUp will reboot the system automatically. This is so you can run this part of the process unattended and later return to the upgraded system, if you leave any bootable media attached to the system during the upgrade process, once the upgrade has completed, the system may boot from that medium instead of the hard disk. If you return to see the Fedora installer or something similar...that's probably what happened!

Frequently Asked Questions

How do I report issues that I find with upgrades?

First see Common F21 bugs or Common F22 bugs to check if the problem is a very prominent issue we already know of. If it is not there, the component for reporting problems depends on the exact issue that you hit:

Issues with upgrade preparation

If you hit issues when using the FedUp client (fedup) before reboot, search or file a bug against FedUp using the version you are upgrading from.

Issues During Upgrade

If you hit issues after upgrade preparation and the initial reboot, search or file a bug against fedup-dracut using the version you are upgrading to.

Issues After Upgrade

If you hit issues after upgrade with a specific package, file a bug against the package with which you are having issues.

How do I Debug Issues During Upgrade?

A troubleshooting and debug guide will be written at some point and linked to from here.

Does FedUp verify the software it runs or installs during upgrade?

Yes. The package signing keys for newer Fedora releases are sent to older Fedora releases in order to allow FedUp to verify the integrity of the packages it downloads. You can disable this function with the --nogpgcheck parameter if you need to do so for any reason.

Will packages in third party repositories be upgraded?

Yes, if they are set up like regular yum/dnf repositories and do not hard code the repository path. Commonly-used third party repositories usually work fine, but if you attempt to upgrade prior to or soon after an official Fedora release, they may not have updated their repository paths yet, and FedUp may be unable to find their packages. This will usually not prevent the upgrade running successfully, though, and you can update the packages from the third-party repository later.

Can I use FedUp to upgrade to a pre-release (e.g. a beta)?

Yes. After a Fedora release has been branched, it should be possible to upgrade to it using FedUp. It should also work after the Alpha and Beta releases. Of course, this function is as subject to temporary breakage as is any other aspect of a pre-release.

See this email to the Fedora devel mailing list for more details.

How Can I Upgrade My System with FedUp?

As alluded to above, there are three parts to upgrading with FedUp - preparation, execution and cleanup.

Before you start doing anything, be sure to have a look at Common F21 bugs#Upgrade_issues or Common F22 bugs#Upgrade_issues and read about the most common bugs found.

Upgrading from Fedora 20 or earlier: Products

In order to select one of the new Fedora flavors, FedUp has a new option, --product=<PRODUCT>. When upgrading from Fedora 20 or earlier to Fedora 21 or later, you must pass this --product option.

You can use the values workstation, server, cloud or nonproduct. If you upgrade to Workstation or Server, all the packages that are included in a default installation of that flavor will be installed after the upgrade (that is, any that are not currently installed will be added). Your firewall configuration will also be reset to the default for that flavor (in the Workstation case, this is a fairly open configuration). If you do not wish these things to happen, use the value nonproduct.

Preparing for the Upgrade

  1. Do a full system update and reboot to ensure that any kernel changes are running
  2. Install/Update fedup
  3. Usually, it is best to try first with the latest fedup available in the stable update repository for the release you are running. If you encounter problems with the upgrade, and a newer fedup is available in the updates-testing repository for your current release, you may wish to try with this newer version: yum --enablerepo=updates-testing install fedup or with dnf: dnf --enablerepo=updates-testing install fedup at the command line)
  4. Make sure the system is running a Fedora issued kernel if possible -- if you use your own kernel and it does not have a corresponding initramfs, the upgrade will fail.

There are three options for sourcing the packages needed for upgrade - using a network repository, a local ISO file or a local device (hard drive, optical disk etc).

Network upgrade is strongly recommended
It is strongly recommended to use the network upgrade instead of offline update modes (ISO, local device). Network upgrade will ensure you receive the latest packages from the target release. If you use local media containing older packages, you might end up with a mixture of packages from your former and target release, and the system might not work properly until you fully update it after reboot (if it boots at all).

Network

Using a network source is the easiest method of upgrading and will pull in updates while upgrading - eliminating the potential issue if your current system has a newer kernel version than the Fedora release to which you are upgrading.

Start the upgrade prep by executing following command:

  • sudo yum update fedup fedora-release

or with dnf for Fedora 22 and later versions:

  • sudo dnf upgrade fedup fedora-release

If you are upgrading from Fedora 20 to Fedora 21, run the following command:

  • sudo fedup --network 21 --product=[workstation | server| cloud | nonproduct]

If you are upgrading from Fedora 21 to Fedora 22 or above, run the following command:

  • sudo fedup --network 22

Once the preparations have completed, check the /var/log/fedup.log file if any errors show up in the output from fedup

ISO File

Older Fedora releases included an installation image with a large number of packages, making it suitable for upgrading some systems. Upgrading by booting this image was possible until Fedora 17, and using the image for upgrades with Fedup was supported until Fedora 20. Beginning with Fedora 21, the universal DVD image is not produced; as of now, there is no media available for offline upgrades.

Other Device

Optical drives and other mountable storage can also be used as a package source for upgrade preparations.

  1. Mount the source material
    • For the sake of example, we will assume that this source is mounted at /mnt/fedora but you can mount it anywhere as long as you replace /mnt/fedora in the command below with the actual mounted location of the upgrade source.
  2. Start the upgrade preparations by executing the following command
    • sudo fedup --device /mnt/fedora --debuglog=fedupdebug.log
  3. Once the preparations have completed, check the fedupdebug.log file if any errors show up in the output from fedup

Executing the Upgrade

  1. Reboot the system if fedup has completed without error.
  2. Once the system reboots, there should be a new entry in the GRUB menu titled System Upgrade.
  3. Select the System Upgrade option from the GRUB menu
    • Remark: If the System Upgrade item is not shown in the grublist at boot, it is most often caused by having an incompatible grub, most often installed by another Linux distribution you may have in your multiboot environment. To correct this quickly: reinstall grub:
      1. grub2-mkconfig -o /boot/grub2/grub.cfg
      2. grub2-install /dev/sda (replace /dev/sda by any other device you prefer to boot from)
  4. The system should boot into the upgrade process and a plymouth boot screen should be displayed
    • There is a root shell on virtual terminal two (VT2) so you can tinker with the system if something goes wrong. (To disable this, boot with rd.upgrade.noshell)
    • Press 'esc' to view a more detailed log. If you switch back to the graphical progress indicator, it may show 0% for the remainder of the upgrade but that does not mean the upgrade has stopped.
  5. Once the upgrade process has completed, the system will reboot and an option to boot Fedora 41 will be on the grub menu

Cleaning Up Post Upgrade

It is worth rebuilding the RPM DB to prevent RPMDB checksum error when doing a distribution sync:

sudo rpm --rebuilddb

There are a collection of post-upgrade things to do. Some of which are fixed by doing a distro sync:

sudo yum distro-sync --setopt=deltarpm=0

If you have upgraded to Fedora 22 or above, run the following command instead:

(If you run dnf the first time and you're behind a proxy add your proxy settings to /etc/dnf/dnf.conf)

sudo dnf distro-sync --setopt=deltarpm=0

The rpmconf tool searches for .rpmnew, .rpmsave and .rpmorig files and asks you what to do with them: Keep current version, place back old version, watch the diff or merge.

sudo yum install rpmconf

If you have upgraded to Fedora 22 or above, run the following command instead:

sudo dnf install rpmconf

sudo rpmconf -a

If you are using google-chrome from the Google repository, you must re-install google-chrome due to a packaging bug on the Google side of things. Make sure to adjust the command to the build type you would like to install:

sudo yum remove google-chrome-\* && sudo yum install google-chrome-[beta,stable,unstable]

If you have upgraded to Fedora 22 or above, run the following command instead:

sudo dnf remove google-chrome-\* && sudo dnf install google-chrome-[beta,stable,unstable]

Docs TODO

  • Write fedup troubleshooting and debug guide
  • add note about blob drivers if needed