From Fedora Project Wiki

(Undo revision 319619 by Le0villems (talk) This is wrong and removed valid documentation, reverting back to previous version)
(Undo revision 319620 by Le0villems (talk) this is incorrect, reverting)
Line 92: Line 92:


== Executing the Upgrade ==
== Executing the Upgrade ==
# Open Terminal and run '''<code>su -c "fedup-cli --network 18 --debuglog fedupdebug.log""</code>'''.
{{admon/warning|Needs Reference|This section still needs a reference to the 'esc kills plymouth' bug once a suitable summary has been written}}
# Reboot your system.
# Once you Reboot, you'll see the option 'System Upgrade' on the GRUB prompt. Just press Enter.
# The system will boot into a special environment to perform the upgrade. The screen will show a graphical progress screen during upgrade.


{{admon/note|Go get some coffee|The upgrade process usually takes a while (anywhere from 45-90 minutes, depending on the system), be patient and wait for it to finish. The system will boot into the new version of Fedora when the upgrade is complete.}}
# 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'''}}.
#* If you add <code>rd.upgrade.debugshell</code> boot argument, you will get a login shell on VT2, allowing you to tinker with the system in case something goes wrong
# Select the {{command|'''System Upgrade'''}} option from the GRUB menu
# The system should boot into the upgrade process and a plymouth boot screen should be displayed
#* If you press 'esc', a more detailed log of progress will be desplayed but if you switch back to the graphical progress indicator, it will remain at 0% for the remainder of the upgrade but that does not mean the upgrade has stopped. See '''Need section reference here once it's written'''
# Once the upgrade process has completed, the system will reboot and an option to boot {{FedoraVersion|long|current}} will be on the grub menu


== GRUB Updates ==
== GRUB Updates ==

Revision as of 16:56, 19 January 2013

Note.png
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
Warning.png
Security Considerations
FedUp does not yet ensure that only trusted software from Fedora is run on your system when you are doing upgrade over the network. Refer to Bugzilla: #877623 for more details. You can download the ISO release image and verify the authenticity independently before performing a upgrade with Fedup via media or ISO images methods to workaround this issue. Note that neither Anaconda not Preupgrade verified the authenticity of the source either and this is not a regression.

What is FedUp?

FedUp (FEDora UPgrader) is the name of a new system for upgrading Fedora installs in Fedora 18 and above releases. It replaces all of the currently recommended upgrade methods (PreUpgrade and DVD) that have been used in previous Fedora releases. Anaconda, the Fedora installer does have not any in-built upgrade functionality in Fedora 18 or above releases. It has been completely delegated to 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.

Warning.png
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 to Fedora 17 before continuing.

What Does FedUp do?

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 and yum. More details are available in a blog post written by FedUp's primary author

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 before Fedora 18 is released.

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.

Frequently Asked Questions

Can I upgrade a Fedora 16 system with FedUp?

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. If you are upgrading from Fedora 16, use Preupgrade to upgrade to Fedora 17 first.

How do I report issues that I find with upgrades?

First see Common F18 bugs#Upgrade_issues whether the problem is not one of 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 (Package-x-generic-16.pngfedup) 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 Package-x-generic-16.pngfedup-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 soon and linked to from here.

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

This is a planned feature. See Bug 877623 for a status update.

Where can I ask Questions

For now, the best place to ask questions is probably #fedora-qa[?] on Freenode IRC or the test mailing list.

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 F18 bugs#Upgrade_issues and read about the most common bugs found.

Preparing for the Upgrade

Important.png
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 (2013-01-08), that is fedup-0.7.2-1.fc17
  1. Do a full system update and reboot to ensure that any kernel changes are running
  2. Install Package-x-generic-16.pngfedup
    • Be sure to get the latest release, this may involve enabling updates-testing (yum --enablerepo=updates-testing install fedup in the command line)

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

Important.png
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 Fedora 18. If you use local media containing old Fedora 18 packages, you might end up with a mixture of Fedora 17 and Fedora 18 packages 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.

  1. Start the upgrade prep by executing following command
    • sudo fedup-cli --network 18 --debuglog fedupdebug.log
  2. Once the preparations have completed, check the fedupdebug.log file if any errors show up in the output from fedup-cli

ISO File

In order to use an ISO file, it needs to exist locally on the filesystem of the system to be upgraded. The documentation is written as if that file is /home/user/fedora-18.iso but you will need to replace all instances of that path with the actual path of the ISO. Updates will be pulled in if you have network access on the machine to be upgraded.

  1. Download the Fedora 39 ISO appropriate for the arch that you are running
    • For the sake of example, we will assume that the ISO exists at /home/user/fedora-18.iso but it can be anwhere in the filesystem as long as you alter the path below to reflect the actual location of the ISO.
  2. Start the upgrade prep by executing the following command
    • sudo fedup-cli --iso /home/user/fedora-18.iso --debuglog=fedupdebug.log
  3. Once the preparations have completed, check the fedupdebug.log file if any errors show up in the output from fedup-cli

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-cli --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-cli

Executing the Upgrade

Warning.png
Needs Reference
This section still needs a reference to the 'esc kills plymouth' bug once a suitable summary has been written
  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.
    • If you add rd.upgrade.debugshell boot argument, you will get a login shell on VT2, allowing you to tinker with the system in case something goes wrong
  3. Select the System Upgrade option from the GRUB menu
  4. The system should boot into the upgrade process and a plymouth boot screen should be displayed
    • If you press 'esc', a more detailed log of progress will be desplayed but if you switch back to the graphical progress indicator, it will remain at 0% for the remainder of the upgrade but that does not mean the upgrade has stopped. See Need section reference here once it's written
  5. Once the upgrade process has completed, the system will reboot and an option to boot Fedora 39 will be on the grub menu

GRUB Updates

Warning.png
Needs update
This part of the documentation is outdated. Update it or tell someone to do it.
Note.png
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)

  • After upgrade, the grub2 you're booting from will still be the F17 version; upgrading must be done manually
  • Follow the steps in this grub2 page to reinstall and update grub

Updating GRUB (UEFI systems)

Note.png
Problems Upgrading Grub on UEFI
Late in testing, we found some potentially serious problems with manually upgrading grub-efi to grub2-efi. Until this is figured out, we recommend that users continue to use grub-efi as it should work for the near future

Cleaning Up Post Upgrade

Warning.png
Pending
This part of the documentation is still being written

Docs TODO

  • Write fedup troubleshooting and debug guide
  • add details for secureboot/shim installation
  • write commonbugs entries and link to them from this page
  • add note about blob drivers if needed
  • add notes about how to use other repos or link to discussion/instructions