FedUp

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Preparing for the Upgrade: updating current fedup version)
(Updating Fedup docs to draft that is more appropriate to current version. it's not done yet but better than the version which was written for beta)
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}}
 
{{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}}
 +
 +
{{admon/caution|Upgrading before F18 GA|Some parts of fedup rely on variables which are not set until Fedora 18 is released. There are other side-effects of upgrading before GA (currently scheduled for 2013-01-15) which can cause minor issues on your system including not upgrading the kernel and not upgrading various Fedora 17 packages. This does not mean that the upgrade didn't work - you'll just have to either update to updates-testing or wait until the Fedora 18 updates repo is populated}}
  
 
{{admon/warning|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 [[rhbug:877623|Bugzilla: #877623]] for more details.  You can download the ISO release image and verify the authenticity independently before perfoming 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. }}
 
{{admon/warning|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 [[rhbug:877623|Bugzilla: #877623]] for more details.  You can download the ISO release image and verify the authenticity independently before perfoming 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? ==
+
= 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.
 
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.
Line 9: Line 11:
 
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.
 
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.
  
{{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. This limitation is planned to be fixed in a future release of Fedup}}
+
{{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 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]
 
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]
  
=== 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 the fedup command-line interface 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 before Fedora 18 is released.
  
=== 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 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 =
=== Can I upgrade a Fedora 16 system with FedUp? ===
+
== 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.  
+
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? ===
+
 
 +
== How do I report issues that I find with upgrades? ==
 
The answer to this depends on the exact issue that you hit.
 
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, search for 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, search for 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 soon and linked to from here.
  
=== Does FedUp verify the software it runs or installs during upgrade? ===
+
== Does FedUp verify the software it runs or installs during upgrade? ==
 
This is a planned feature. See [https://bugzilla.redhat.com/show_bug.cgi?id=877623 Bug 877623] for a status update.
 
This is a planned feature. See [https://bugzilla.redhat.com/show_bug.cgi?id=877623 Bug 877623] for a status update.
  
=== Where can I ask Questions ===
+
== Where can I ask Questions ==
 
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].
 
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? ==
+
= How Can I Upgrade My System with FedUp? =
 
+
{{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}}
+
  
 
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 ===
+
== Preparing for the Upgrade ==
{{admon/caution|URL|The URL listed here will work with FedUp, but it will not get the latest upgrade initramfs. New instructions are being written but there are some complications which make it unwise to update the docs here until F18 final is released. If you're following these instructions before F18 is released, use http://dl.fedoraproject.org/pub/fedora/linux/development/18/<arch>/os (or your [https://mirrors.fedoraproject.org local mirror]) for the <code>--instrepo</code> arg value}}
+
{{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 (2013-01-08), that is fedup-0.7.2-1.fc17}}
{{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 (2013-01-10), that is fedup-0.7.2-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 {{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)
 
#* 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)
# 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.
+
 
#* If you're upgrading before Fedora 18 is actually released - please read the above warning about the URL for --instrepo. Yes, you will need to use it until GA. These instructions will be changed by the time that all the backend mirroring is updated.
+
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.).
#* <arch> is the name of the arch running on the install to be upgraded (i386, x86_64 ...)
+
 
 +
=== Network ===
 +
Using a network source is the easiest method of upgrading and will pull in updates while upgrading - eliminating the potential issue if {{FedoraVersion|previous}} has a newer kernel version than {{FedoraVersion}}.
 +
 
 +
{{admon/caution|Upgrading Before F18 Final GA|If you're following these instructions before F18 goes GA (currently scheduled for 2013-01-15), you '''do''' need to use the --instrepo argument as shown here. You may also end up with many fc17 packages on your system after upgrade - this is not a bug with fedup but a side effect of the release process. Once F18 goes GA, the updates repository will be available and this problem should go away}}
 +
 
 
# Start the upgrade prep by executing following command
 
# Start the upgrade prep by executing following command
#* {{command|sudo fedup --network 18 --debuglog fedupdebug.log --instrepo <URL>}}
+
#* {{command|sudo fedup --network 18 --debuglog fedupdebug.log --instrepo http://dl.fedoraproject.org/pub/alt/qa/fedup/f18-RC4/<arch>/}}
#* <URL> is the location found in the previous step
+
#* <arch> is the arch of the system that you are upgrading - either i386 or x86_64
# Check the {{filename|fedupdebug.log}} file if any errors show up in the output from {{command|fedup}}
+
# Once the preparations have completed, check the {{filename|fedupdebug.log}} file if any errors show up in the output from {{command|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.
 +
 
 +
# Download the {{FedoraVersion}} iso appropriate for the arch that you are running
 +
#* For the sake of example, we will assume that the iso exists at {{filename|/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.
 +
# Start the upgrade prep by executing the following command
 +
#* <nowiki>sudo fedup --iso /home/user/fedora-18.iso --debuglog=fedupdebug.log</nowiki>
 +
# Once the preparations have completed, check the {{filename|fedupdebug.log}} file if any errors show up in the output from {{command|fedup-cli}}
 +
 
 +
=== 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
 +
#* <nowiki>sudo fedup --device /mnt/fedora --debuglog=fedupdebug.log</nowiki>
 +
# Once the preparations have completed, check the {{filename|fedupdebug.log}} file if any errors show up in the output from {{command|fedup-cli}}
  
=== Executing the Upgrade ===
+
== Executing the Upgrade ==
{{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}}
+
{{admon/warning|Needs Reference|This section still needs a reference to the 'esc kills plymouth' bug once a suitable summary has been written}}
  
 
# Reboot the system if {{command|fedup}} has completed without error.
 
# 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}}.
 
# Once the system reboots, there should be a new entry in the GRUB menu titled {{command|System Upgrade}}.
 +
#* Adding <nowiki>rd.upgrade.debugshell</nowiki> would be a decent idea
 
# Select the {{command|System Upgrade}} option from the GRUB menu
 
# Select the {{command|System Upgrade}} option from the GRUB menu
#* 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>)
 
 
# 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
+
#* 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|next}} will be on the grub menu
 
# Once the upgrade process has completed, the system will reboot and an option to boot {{FedoraVersion|long|next}} will be on the grub menu
  
=== GRUB Updates ===
+
== GRUB Updates ==
 
{{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}}
 
{{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) ====
+
=== Updating GRUB2 (BIOS systems) ===
  
 
* After upgrade, the grub2 you're booting from will still be the F17 version; upgrading must be done manually
 
* After upgrade, the grub2 you're booting from will still be the F17 version; upgrading must be done manually
 
* Follow the steps in [[GRUB_2|this grub2 page]] to reinstall and update grub
 
* Follow the steps in [[GRUB_2|this grub2 page]] to reinstall and update grub
  
==== Updating GRUB (UEFI systems) ====
+
=== Updating GRUB (UEFI systems) ===
 +
{{admon/caution|Intel Macs|These instructions will not work for Fedora installs on Intel macs. We're still working out separate instructions but for now, just continue to use grub-efi and upgrade to grub2 later.}}
 
{{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|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.}}
  
Line 98: Line 120:
 
</pre>
 
</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:
+
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. Note that you will not be using the exact same command when upgrading to grub2 as the location of some files has changed. The older reference command can be found in <nowiki>/var/log/anaconda/anaconda.program.log</nowiki> and should end with a command similar to:
 
<pre>
 
<pre>
 
efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l \EFI\redhat\grub.efi
 
efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l \EFI\redhat\grub.efi
Line 134: Line 156:
 
Once the system reboots, you should be using grub2-efi instead of grub-efi
 
Once the system reboots, you should be using grub2-efi instead of grub-efi
  
=== Cleaning Up Post Upgrade ===
+
== Cleaning Up Post Upgrade ==
 +
 
 +
{{admon/warning|Pending|This part of the documentation is still being written }}
 +
<!-- Some of the stuff from [http://fedorasolved.org/Members/fenris02/post_upgrade_cleanup this post upgrade cleanup guide] might be wise -->
  
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 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

Revision as of 02:19, 11 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
Stop (medium size).png
Upgrading before F18 GA
Some parts of fedup rely on variables which are not set until Fedora 18 is released. There are other side-effects of upgrading before GA (currently scheduled for 2013-01-15) which can cause minor issues on your system including not upgrading the kernel and not upgrading various Fedora 17 packages. This does not mean that the upgrade didn't work - you'll just have to either update to updates-testing or wait until the Fedora 18 updates repo is populated
Warning (medium size).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 perfoming 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.

Contents

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 (medium size).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?

The answer to this 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 for 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 for 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 Fedora Test 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.

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 (put --enablerepo=updates-testing between yum and install on 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.).

Network

Using a network source is the easiest method of upgrading and will pull in updates while upgrading - eliminating the potential issue if 21 has a newer kernel version than 21.

Stop (medium size).png
Upgrading Before F18 Final GA
If you're following these instructions before F18 goes GA (currently scheduled for 2013-01-15), you do need to use the --instrepo argument as shown here. You may also end up with many fc17 packages on your system after upgrade - this is not a bug with fedup but a side effect of the release process. Once F18 goes GA, the updates repository will be available and this problem should go away
  1. Start the upgrade prep by executing following command
  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 21 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 --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 --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 (medium size).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.
    • Adding rd.upgrade.debugshell would be a decent idea
  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 22 will be on the grub menu

GRUB Updates

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)

Stop (medium size).png
Intel Macs
These instructions will not work for Fedora installs on Intel macs. We're still working out separate instructions but for now, just continue to use grub-efi and upgrade to grub2 later.
Note.png
Secure Boot
Secure Boot functionality was not completed in time for Fedora 18 beta and these instructions do not cover using Package-x-generic-16.pngshim or the signed kernel. Once Secure Boot functionality is available, these instructions will be updated.
Note.png
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

Grub2 is not installed as part of the upgrade process, so you'll have to install it:

sudo yum install grub2-efi

Once the Package-x-generic-16.pnggrub2-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. Note that you will not be using the exact same command when upgrading to grub2 as the location of some files has changed. The older reference command can be found in /var/log/anaconda/anaconda.program.log and should end with a command similar to:

efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l \EFI\redhat\grub.efi

Find the current boot number for fedora using efibootmgr:

efibootmgr -v

You are looking for a line similar to:

Boot0004* Fedora  HD(1,800,34800,6733749f-b42a-4b8c-a0de-5a1d3505f8af)File(\EFI\redhat\grub.efi)

The boot number in this example is 0004.

Remove the old boot entry using the following command (<boot number>) is the boot number you found above:

efibootmgr -b <boot number> -B
Warning (medium size).png
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

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:

sudo efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l '\EFI\fedora\grubx64.efi' -b <boot number>

In order to get a bootable UEFI system, you need to regenerate the grub configuration and symlink it to /etc/grub2-efi.cfg

grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg

Once the system reboots, you should be using grub2-efi instead of grub-efi

Cleaning Up Post Upgrade

Warning (medium size).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