How to use PreUpgrade

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Rewording and adding troubleshoot section)
Line 1: Line 1:
 
[[Category:Documentation]][[Category:How to]][[Category:PreUpgrade]]
 
[[Category:Documentation]][[Category:How to]][[Category:PreUpgrade]]
  
PreUpgrade is an application users run on an existing Fedora 8 or above installation, that resolves and downloads packages required to upgrade Fedora. While PreUpgrade downloads the necessary packages, users are free to continue using their systems. This gives an experience similar to a live upgrade.  
+
PreUpgrade is an application users run on an existing Fedora 8 or above installation, that resolves and downloads packages required to upgrade Fedora. While PreUpgrade downloads the necessary packages, users are free to continue using their systems. This gives an experience similar to a live upgrade. For additional information, please refer to the [[Features/PreUpgrade|PreUpgrade feature page]].</ref>
  
{{admon/tip|PreUpgrade provides an upgrade directly to the latest version of Fedora.  It is not necessary to upgrade to intermediate versions.  (For example, it is possible to go from Fedora 9 to 11 directly.)}}
+
{{admon/tip|Upgrade to current|Preupgrade provides an upgrade directly to the latest version of Fedora.  It is not necessary to upgrade to intermediate versions.  For example, it is possible to go from {{FedoraVersion|long|previous2}} to {{FedoraVersion|long|current}} directly.}}
  
To use PreUpgrade to upgrade to a newer Fedora release:
+
= Prepare the system =
  
# Back up all important data before upgrading as a general best practice.  
+
While preupgrade provides a generally hassle free upgrade experience.  The following steps are recommended before proceeding.
# Run the <code>yum update</code> command as root to make sure all packages are updated to their latest versions.
+
 
# Preupgrade is installed by default in recent versions. Run the <code>yum install preupgrade</code> command as root to install PreUpgrade otherwise.  
+
# ''Backup'' - Before performing any system maintenance, it is recommended that you back up all important data before proceeding.  
# Run the <code>preupgrade</code> command as root to start the PreUpgrade application. If you prefer a command line application, run <code> preupgrade-cli </code> instead.  
+
# ''Update'' - Apply available updates Fedora updates before proceeding.  As the root user, issue the following command. <pre>yum update</pre>
# Select the Fedora release you want to upgrade to on the ''Choose desired release'' screen, and click the ''Apply'' button.
+
# ''Install'' - As of {{FedoraVersion|long|10}}, the preupgrade utility is included in a default Fedora install. However, the package can be installed manually using the {{command|yum}} command. <pre>yum install preupgrade</pre>
 +
 
 +
= Perform the upgrade =
 +
 
 +
Typically, you will be prompted by {{package|PackageKit}} when upgrades are available for your system.  However, if you choose to manually upgrade using {{command|preupgrade}}, the steps are listed below.
 +
 
 +
# As the root user, run the command {{command|preupgrade}} to start the Preupgrade application. If you prefer a command line application, the command {{command|preupgrade-cli}} is available.
 +
# On the ''Choose desired release'' screen, select the Fedora release you want to upgrade to , and click the ''Apply'' button.
 
# When all of the packages have downloaded, reboot your system to start the Fedora installer and upgrade to the next release.  
 
# When all of the packages have downloaded, reboot your system to start the Fedora installer and upgrade to the next release.  
  
After the upgrade is complete:
+
= Common post-upgrade tasks =
* Some packages may no longer be supported by the new release.  These can be identified with:
+
 
::<code>package-cleanup --orphans</code>
+
After the upgrade is complete, additional steps are recommended to complete the process.
:You may wish to remove these packages because they will no longer get security updates, and they may cause later conflicts with supported packages.
+
 
* You should examine all ".rpmsave" and ".rpmnew" files created by the upgrade.  You may need to manually merge configuration files.
+
== Removing unsupported packages ==
 +
 
 +
Some packages may no longer be supported by the new release.  You may wish to remove these packages because they will no longer get security updates, and they may cause later conflicts with supported packages. These can be identified with the following command: <pre>package-cleanup --orphans</pre>
 +
 
 +
== Examine {{filename|.rpmsave}} and {{filename|.rpmnew}} files ==
 +
 
 +
After completing the upgrade process, you may notice file names ending with {{filename|.rpmsave}} and {{filename|.rpmnew}}.  Don't be alarmed.  The upgrade process will always preserve any locally modified configuration files.  The file names ending with {{filename|.rpmsave}} contain your local configuration changes.  While the file names ending with {{filename|.rpmnew}} represent the configuration file originally packages with the software.
 +
 
 +
You should examine all {{filename|.rpmsave}} and {{filename|.rpmnew}} files created by the upgrade.  Depending on the differences, you may need to manually merge configuration files. You can locate all matching files using the {{command|find}} command.
 +
 
 +
<pre>find / -print | egrep "rpmnew$|rpmsave$"</pre>
 +
 
 +
= Troubleshooting =
 +
 
 +
== Not enough space in /boot ==
 +
 
 +
The default {{filename|/boot}} filesystem size of 200MB may not be sufficient to perform a preupgrade.  This section outlines several tips that have been known to work.  As always when performing administrative tasks, be sure to back-up any data before proceeding.
 +
 
 +
'''First''', try to remove any kernel packages not currently in use on your system.  The [http://skvidal.fedorapeople.org/misc/kernel-prune.py kernel-prune.py] script can be used to identify kernels that may be safely removed.  If you choose to remove additional kernels, be prepared with [http://fedoraproject.org/en/get-fedora installation media] should you be unable to return to your previously installed system.
 +
 
 +
'''Next''', adjust the number of reserved filesystem blocks using the command {{command|tune2fs}}.  You'll first need to identify the block device for your {{filename|/boot}} file system.  In the example below, {{filename|/dev/sda1}} is the block device for the {{filename|/boot}} filesystem.
 +
<pre># mount | grep "/boot"
 +
/dev/sda3 on /boot type ext4 (rw)</pre>
 +
Now, adjust the number of reserved blocks for the {{filename|/boot}} filesystem using the command {{command|tune2fs}}. Normally, a small amount of space on ext filesystem formatted partitions is 'reserved' and can only be used by the system administrator; this is to prevent an entirely full partition from rendering a system unbootable, and allow the administrator some space in which to work in order to clean up 'full' partitions. However, neither of this cases really applies to the {{filename|/boot}} filesystem, so removing this reserved space is safe.
 +
<pre># tune2fs -r 0 /dev/sda3</pre>
  
For further information, refer to the [[Features/PreUpgrade|PreUpgrade feature page]].
+
'''Last''', try removing unnecessary files from the {{filename|/boot}} filesystem.  This will largely depend on how your system is set up.  Removing the incorrect files may result in a unbootable system.  Some candidates for removal include {{filename|/boot/efi}} and {{filename|/boot/grub/splash.xpm.gz}}.

Revision as of 19:12, 16 November 2009


PreUpgrade is an application users run on an existing Fedora 8 or above installation, that resolves and downloads packages required to upgrade Fedora. While PreUpgrade downloads the necessary packages, users are free to continue using their systems. This gives an experience similar to a live upgrade. For additional information, please refer to the PreUpgrade feature page.</ref>

Idea.png
Upgrade to current
Preupgrade provides an upgrade directly to the latest version of Fedora. It is not necessary to upgrade to intermediate versions. For example, it is possible to go from Fedora 19 to Fedora 21 directly.

Contents

Prepare the system

While preupgrade provides a generally hassle free upgrade experience. The following steps are recommended before proceeding.

  1. Backup - Before performing any system maintenance, it is recommended that you back up all important data before proceeding.
  2. Update - Apply available updates Fedora updates before proceeding. As the root user, issue the following command.
    yum update
  3. Install - As of Fedora 10, the preupgrade utility is included in a default Fedora install. However, the package can be installed manually using the yum command.
    yum install preupgrade

Perform the upgrade

Typically, you will be prompted by Package-x-generic-16.pngPackageKit when upgrades are available for your system. However, if you choose to manually upgrade using preupgrade, the steps are listed below.

  1. As the root user, run the command preupgrade to start the Preupgrade application. If you prefer a command line application, the command preupgrade-cli is available.
  2. On the Choose desired release screen, select the Fedora release you want to upgrade to , and click the Apply button.
  3. When all of the packages have downloaded, reboot your system to start the Fedora installer and upgrade to the next release.

Common post-upgrade tasks

After the upgrade is complete, additional steps are recommended to complete the process.

Removing unsupported packages

Some packages may no longer be supported by the new release. You may wish to remove these packages because they will no longer get security updates, and they may cause later conflicts with supported packages. These can be identified with the following command:
package-cleanup --orphans

Examine .rpmsave and .rpmnew files

After completing the upgrade process, you may notice file names ending with .rpmsave and .rpmnew. Don't be alarmed. The upgrade process will always preserve any locally modified configuration files. The file names ending with .rpmsave contain your local configuration changes. While the file names ending with .rpmnew represent the configuration file originally packages with the software.

You should examine all .rpmsave and .rpmnew files created by the upgrade. Depending on the differences, you may need to manually merge configuration files. You can locate all matching files using the find command.

find / -print | egrep "rpmnew$|rpmsave$"

Troubleshooting

Not enough space in /boot

The default /boot filesystem size of 200MB may not be sufficient to perform a preupgrade. This section outlines several tips that have been known to work. As always when performing administrative tasks, be sure to back-up any data before proceeding.

First, try to remove any kernel packages not currently in use on your system. The kernel-prune.py script can be used to identify kernels that may be safely removed. If you choose to remove additional kernels, be prepared with installation media should you be unable to return to your previously installed system.

Next, adjust the number of reserved filesystem blocks using the command tune2fs. You'll first need to identify the block device for your /boot file system. In the example below, /dev/sda1 is the block device for the /boot filesystem.

# mount | grep "/boot"
/dev/sda3 on /boot type ext4 (rw)

Now, adjust the number of reserved blocks for the /boot filesystem using the command tune2fs. Normally, a small amount of space on ext filesystem formatted partitions is 'reserved' and can only be used by the system administrator; this is to prevent an entirely full partition from rendering a system unbootable, and allow the administrator some space in which to work in order to clean up 'full' partitions. However, neither of this cases really applies to the /boot filesystem, so removing this reserved space is safe.

# tune2fs -r 0 /dev/sda3

Last, try removing unnecessary files from the /boot filesystem. This will largely depend on how your system is set up. Removing the incorrect files may result in a unbootable system. Some candidates for removal include /boot/efi and /boot/grub/splash.xpm.gz.