From Fedora Project Wiki

(add note on third party repos)
m (→‎Network: fixed numbering)
(47 intermediate revisions by 24 users not shown)
Line 1: Line 1:
{{autolang|base=yes}}
{{autolang|base=yes}}
{{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 performing a upgrade with Fedup via media or ISO images methods to workaround this issue however a network upgrade is still the recommended option since it can handle updated packages better.  Note that neither Anaconda or 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, has no built-in upgrade functionality in Fedora 18 or above releases.  It has been completely delegated to Fedup.
FedUp (FEDora UPgrader) is the official tool for upgrading Fedora installations. Anaconda, the Fedora installer, has no built-in upgrade functionality in Fedora 18 or later.  It has been completely delegated to FedUp. FedUp is capable of handling upgrades between all current Fedora releases using a network repository or a DVD image as the package source.
 
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.}}


= 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 consists 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 /var/lib/fedora-upgrade and will be automatically cleaned up after the upgrade process is finished.


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 the fedup command-line interface is implemented but a GUI interface is expected sooner or later.
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 ==


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.
== 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 return to the upgraded system, but if you leave any bootable media attached to the system during the upgrade process, the system may boot from that medium instead of the hard disk once the upgrade is complete. If you leave your system upgrading, come back, and see the Fedora installer or something similar...that's probably what happened!


= Frequently Asked Questions =
= Frequently Asked Questions =
== Can I upgrade a Fedora 16 system with FedUp? ==
== Why does my upgrade to Fedora 20 fail (immediately reboot to my old Fedora)? ==
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.
Because we messed up! Sorry about that. FedUp 0.7, which was in the Fedora 18 and 19 stable repositories at the time of Fedora 20's release, cannot successfully upgrade to Fedora 20. FedUp 0.8, though, can do it just fine. You should use FedUp 0.8 to upgrade to Fedora 20. If you're upgrading from Fedora 18, you'll need to pass <tt>--nogpgcheck</tt>. See [[Common_F20_bugs#fedup-07-fail|the Common Bugs page]] for all the details.


== How do I report issues that I find with upgrades? ==
== 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:
First see [[Common F20 bugs]] or [[Common F21 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 ===
=== Issues with upgrade preparation ===
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'''.
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 ===
Line 42: Line 39:
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? ==
== 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.
Since version 0.8, it does so by default. The package signing keys for newer Fedora releases are now 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? ==
== Will packages in third party repositories be upgraded? ==


Yes, if they are setup like regular yum repositories and do not hard core the repository path. The typical third party repositories like RPM Fusion work fine.
Yes, if they are set up like regular yum 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)? ==
== 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.
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 any other aspect of a pre-release.


See this [http://lists.fedoraproject.org/pipermail/devel/2013-May/183508.html email to the Fedora devel mailing list] for more details.
See this [http://lists.fedoraproject.org/pipermail/devel/2013-May/183508.html email to the Fedora devel mailing list] for more details.


== Where can I ask Questions ==
= How Can I Upgrade My System with FedUp? =
For now, the best place to ask questions is probably {{fpchat|#fedora-qa}} on Freenode IRC or the {{fplist|test}} mailing list.
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 F20 bugs#Upgrade_issues]] or [[Common F21 bugs#Upgrade_issues]] and read about the most common bugs found.


= How Can I Upgrade My System with FedUp? =
==Important Changes in the Upgrade process to Fedora 21==
In order to select one of the new Fedora flavors, FedUp has new option, "--product=<PRODUCT>". To upgrade to the new Fedora Workstation, use <code>--product=workstation</code>. (This will also '''install ''all'' packages from the default Workstation installation''', including the GNOME 3 desktop environment, in addition to upgrading the packages you already had installed.)
 
If you would prefer to remain on the general, custom "track", use <code>--product=nonproduct</code>.
 
Upgrading to one of the "products" (other than "nonproduct") may also drastically modify your firewall settings. For example upgrading to product=workstation will practically disable the firewall.
 
Here is the explanation given in the source code of fedup (https://github.com/wgwoods/fedup/blob/master/fedup/commandline.py):
<pre>
This installation of Fedora does not belong to a product, so you
must provide the --product=PRODUCTNAME option to specify what product
you want to upgrade to. PRODUCTNAME should be one of:
 
workstation: the default Fedora experience for laptops and desktops,
powered by GNOME.


As alluded to above, there are three parts to upgrading with FedUp - preparation, execution and cleanup.
server: the default Fedora experience for servers


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.
cloud: a base image for use on public and private clouds
 
nonproduct: choose this if none of the above apply; in particular,
choose this if you are using an alternate-desktop spin of Fedora
Selecting a product will also install its standard package-set in
addition to upgrading the packages already on your system. If you
prefer to maintain your current set of packages, select 'nonproduct'
</pre>


== Preparing for the Upgrade ==
== 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 (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 (2014-12-09), that is fedup-0.9.0-2. Ensure you have fedup at level 0.9.0.2 or higher. Lower version of fedup were affected by BZ#1159292}}
# 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 ('''<code>yum --enablerepo=updates-testing install fedup</code>''' in 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}} at 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.).
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/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 Fedora 19. If you use local media containing old Fedora 19 packages, you might end up with a mixture of Fedora 18 and Fedora 19 packages and the system might not work properly until you fully update it after reboot (if it boots at all).}}
{{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).}}


=== Network ===
=== 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.
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
# Start the upgrade prep by executing following commands
#* {{command|sudo fedup-cli --network 19}}
#* {{command|sudo yum update fedup fedora-release}}
# Once the preparations have completed, check the {{filename|/var/log/fedup.log}} file if any errors show up in the output from {{command|fedup-cli}}
#* sudo fedup --network 21 --product=[workstation | server| cloud | nonproduct]
# 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 ===
=== 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-19.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.
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 F17, and using the image for upgrades with Fedup was supported until Fedora 20. That universal DVD image is not produced for Fedora 21 and later releases; as of now, there is no media available for offline upgrades.
 
# Download the Fedora {{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-19.iso}} but it can be anywhere in the filesystem as long as you alter the path below to reflect the actual location of the ISO. Make sure you have downloaded Fedora DVD ISO image otherwise you will get an error "The given ISO probably isn't an install DVD image" when run {{command|fedup-cli}} command.
# Start the upgrade prep by executing the following command
#* <nowiki>sudo fedup-cli --iso /home/user/fedora-19.iso</nowiki>
# Once the preparations have completed, check the {{filename|/var/log/fedup.log}} file if any errors show up in the output from {{command|fedup-cli}}


=== Other Device ===
=== Other Device ===
Line 99: Line 114:
#* 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.
#* 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
# Start the upgrade preparations by executing the following command
#* <nowiki>sudo fedup-cli --device /mnt/fedora --debuglog=fedupdebug.log</nowiki>
#* {{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-cli}}
# 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 ==
== Executing the Upgrade ==
{{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'''}}.
#* 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
# 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 a different grub, most often installed by another Linux distribution you may have in multiboot. To correct this quickly: reinstall grub:
#*'''Remark:''' If the {{command|'''System Upgrade'''}} item is not shown in the grublist at boot, it is most often caused by having a different grub, most often installed by another Linux distribution you may have in multiboot. To correct this quickly: reinstall grub:
Line 113: Line 125:
#*# grub2-install /dev/sda '''(replace /dev/sda by any other device you prefer to boot from)'''
#*# 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
#* 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'''
#* There is a root shell on VT2 so you can tinker with the system if something goes wrong. (To disable this, boot with <code>rd.upgrade.noshell</code>)
#* Press 'esc' to see 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
# 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 ==
== Cleaning Up Post Upgrade ==
{{admon/warning|Needs update|This part of the documentation is '''updating'''.}}


{{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}}
<!-- 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 -->


=== Updating GRUB2 (BIOS systems) ===
It is worth rebuilding the RPM DB to prevent RPMDB checksum error when doing a distribution sync:
 
* '''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
 
=== Updating GRUB (UEFI systems) ===
 
Grub2 is not installed as part of the upgrade process, so you'll have to install it:
<pre>
sudo yum install grub2-efi
</pre>
 
==== Migrating Grub Configuration ====
Unfortunately, most boot settings are not migrated to grub2 without manual intervention. To migrate these settings, you will need to look the existing grub configuration to migrate settings. Open the {{filename|/boot/efi/EFI/redhat/grub.conf}} and find the most recent boot entry. The version numbers don't need to exactly match the example, just find the most recent one.
 
<pre>
title Fedora (3.6.11-1.fc17.x86_64)
        root (hd0,2)
        kernel /vmlinuz-3.6.11-1.fc17.x86_64 rd.luks.uuid=luks-f664c3a9-e939-410e-8478-891f48b80f12
                rd.md=0 rd.dm=0  KEYTABLE=us SYSFONT=True rd.lvm.lv=vg_test/lv_root
                root=/dev/mapper/vg_test-lv_root ro rd.lvm.lv=vg_test/lv_swap
                LANG=en_US.UTF-8 rhgb quiet
        initrd /initramfs-3.6.11-1.fc17.x86_64.img
</pre>
 
We are '''not''' interested in all of the arguments following {{filename|kernel}}, mostly arguments which start with {{filename|rd.}} and a few other specific arguments. In the example listed above, we're interested in:
<pre>
rd.luks.uuid=luks-f664c3a9-e939-410e-8478-891f48b80f12
rd.md=0
rd.dm=0
rd.lvm.lv=vg_test/lv_root
root=/dev/mapper/vg_test-lv_root
ro
rd.lvm.lv=vg_test/lv_swap
rhgb
quiet
</pre>


{{command|sudo rpm --rebuilddb}}


To migrate the configuration, open {{filename|/etc/default/grub}} with sudo or as root and paste the following template in:
There are a collection of post-upgrade things to do. Some of which are fixed by doing a distro sync:
<pre>
GRUB_TIMEOUT=5
GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"
GRUB_DEFAULT=saved
GRUB_CMDLINE_LINUX=""
GRUB_DISABLE_RECOVERY="true"
GRUB_THEME="/boot/grub2/themes/system/theme.txt"
</pre>


{{admon/note|non-us keymaps and languages|Need to write docs on how to figure out the vconsole lang and keymap args}}
{{command|sudo yum distro-sync --setopt<nowiki>=</nowiki>deltarpm<nowiki>=</nowiki>0}}
 
Take the kernel args that we extracted before and insert them inside the quotes following '''GRUB_CMDLINE_LINUX'''. In this example, it would look like the following. Note that formatting has been slightly altered for the wiki - there should be no newlines in the text following '''GRUB_CMDLINE_LINUX'''.
<pre>
GRUB_TIMEOUT=5
GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"
GRUB_DEFAULT=saved
GRUB_CMDLINE_LINUX="rd.luks.uuid=luks-f664c3a9-e939-410e-8478-891f48b80f12
rd.md=0 rd.dm=0 rd.lvm.lv=vg_test/lv_root root=/dev/mapper/vg_test-lv_root
ro rd.lvm.lv=vg_test/lv_swap rhgb quiet"
GRUB_DISABLE_RECOVERY="true"
GRUB_THEME="/boot/grub2/themes/system/theme.txt"
</pre>
 
Now that we've migrated the required grub settings, we can wrap up by generating a new grub configuration using these new settings and symlinking this new configuration to {{filename|/etc/grub2-efi.cfg}}.
<pre>
grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
ln -s /boot/efi/EFI/fedora/grub.cfg /etc/grub2-efi.cfg
</pre>
 
==== Updating the EFI boot entry ====
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>
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>:
<pre>
efibootmgr -v
</pre>
 
You are looking for a line similar to:
<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.
 
Remove the old boot entry using the following command, note that '''<nowiki><boot number></nowiki>''' is the boot number you found above:
<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}}
 
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:
<pre>
sudo efibootmgr -c -w -L Fedora -d /dev/sdX -p Y -l '\EFI\fedora\grubx64.efi' -b <boot number>
</pre>
 
Now your system should have a working grub2-efi bootloader and it should be loaded when you reboot.
 
== 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 -->
 
Relevant Bugs: [https://bugzilla.redhat.com/show_bug.cgi?id=888085 Bug 888085]; [https://bugzilla.redhat.com/show_bug.cgi?id=981135 Bug 981135]
 
It is worth rebuilding the RPM DB to prevent RPMDB checksum error when doing a distribution sync:


rpm --rebuilddb
This tool search for .rpmnew, .rpmsave and .rpmorig files and ask you what to do with them: Keep current version, place back old version, watch the diff or merge.


There are a collection of post-upgrade things to do. Some of which are fixed by doing a distro sync (NB disablepresto is not a valid option on LXDE spin):
{{command|sudo yum install rpmconf}}


yum distribution-synchronization --disablepresto
{{command|sudo rpmconf -a}}


If you are using google-chrome from the google repository, you must re-install google-chrome due to a packing bug on the Google side of things. Make sure to adjust the command to the build type you would like to install:
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:


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


= Docs TODO =
= Docs TODO =
* Write fedup troubleshooting and debug guide
* 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 note about blob drivers if needed
* add notes about how to use other repos or link to discussion/instructions

Revision as of 13:24, 11 March 2015

What is FedUp?

FedUp (FEDora UPgrader) is the official tool for upgrading Fedora installations. Anaconda, the Fedora installer, has no built-in upgrade functionality in Fedora 18 or later. It has been completely delegated to FedUp. FedUp is capable of handling upgrades between all current Fedora releases using a network repository or a DVD image as the package source.

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 which does the actual upgrade using systemd and 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 return to the upgraded system, but if you leave any bootable media attached to the system during the upgrade process, the system may boot from that medium instead of the hard disk once the upgrade is complete. If you leave your system upgrading, come back, and see the Fedora installer or something similar...that's probably what happened!

Frequently Asked Questions

Why does my upgrade to Fedora 20 fail (immediately reboot to my old Fedora)?

Because we messed up! Sorry about that. FedUp 0.7, which was in the Fedora 18 and 19 stable repositories at the time of Fedora 20's release, cannot successfully upgrade to Fedora 20. FedUp 0.8, though, can do it just fine. You should use FedUp 0.8 to upgrade to Fedora 20. If you're upgrading from Fedora 18, you'll need to pass --nogpgcheck. See the Common Bugs page for all the details.

How do I report issues that I find with upgrades?

First see Common F20 bugs or Common F21 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 (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 at some point and linked to from here.

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

Since version 0.8, it does so by default. The package signing keys for newer Fedora releases are now 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 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 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 F20 bugs#Upgrade_issues or Common F21 bugs#Upgrade_issues and read about the most common bugs found.

Important Changes in the Upgrade process to Fedora 21

In order to select one of the new Fedora flavors, FedUp has new option, "--product=<PRODUCT>". To upgrade to the new Fedora Workstation, use --product=workstation. (This will also install all packages from the default Workstation installation, including the GNOME 3 desktop environment, in addition to upgrading the packages you already had installed.)

If you would prefer to remain on the general, custom "track", use --product=nonproduct.

Upgrading to one of the "products" (other than "nonproduct") may also drastically modify your firewall settings. For example upgrading to product=workstation will practically disable the firewall.

Here is the explanation given in the source code of fedup (https://github.com/wgwoods/fedup/blob/master/fedup/commandline.py): 

This installation of Fedora does not belong to a product, so you
must provide the --product=PRODUCTNAME option to specify what product
you want to upgrade to. PRODUCTNAME should be one of:

workstation: the default Fedora experience for laptops and desktops,
powered by GNOME.

server: the default Fedora experience for servers

cloud: a base image for use on public and private clouds

nonproduct: choose this if none of the above apply; in particular,
choose this if you are using an alternate-desktop spin of Fedora
Selecting a product will also install its standard package-set in
addition to upgrading the packages already on your system. If you
prefer to maintain your current set of packages, select 'nonproduct'

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 (2014-12-09), that is fedup-0.9.0-2. Ensure you have fedup at level 0.9.0.2 or higher. Lower version of fedup were affected by BZ#1159292
  1. Do a full system update and reboot to ensure that any kernel changes are running
  2. Install Package-x-generic-16.pngfedup
    • 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 at 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 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.

  1. Start the upgrade prep by executing following commands
    • sudo yum update fedup fedora-release
    • sudo fedup --network 21 --product=[workstation | server| cloud | nonproduct]
  2. 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 F17, and using the image for upgrades with Fedup was supported until Fedora 20. That universal DVD image is not produced for Fedora 21 and later releases; 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 a different grub, most often installed by another Linux distribution you may have in multiboot. 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 VT2 so you can tinker with the system if something goes wrong. (To disable this, boot with rd.upgrade.noshell)
    • Press 'esc' to see 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 39 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

This tool search for .rpmnew, .rpmsave and .rpmorig files and ask you what to do with them: Keep current version, place back old version, watch the diff or merge.

sudo yum 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]

Docs TODO

  • Write fedup troubleshooting and debug guide
  • add note about blob drivers if needed
Retrieved from "https://fedoraproject.org/w/index.php?title=FedUp&oldid=406187"