swift 13/04/06 12:07:40 Modified: gentoo-upgrading.xml Log: Fix bug #457148 - Add instructions for potentially upgrading very old systems; thanks to Migal Gorny for the instructions
Revision Changes Path 1.46 xml/htdocs/doc/en/gentoo-upgrading.xml file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml?rev=1.46&view=markup plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml?rev=1.46&content-type=text/plain diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml?r1=1.45&r2=1.46 Index: gentoo-upgrading.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml,v retrieving revision 1.45 retrieving revision 1.46 diff -u -r1.45 -r1.46 --- gentoo-upgrading.xml 9 Feb 2013 08:46:08 -0000 1.45 +++ gentoo-upgrading.xml 6 Apr 2013 12:07:40 -0000 1.46 @@ -1,6 +1,6 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml,v 1.45 2013/02/09 08:46:08 swift Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-upgrading.xml,v 1.46 2013/04/06 12:07:40 swift Exp $ --> <guide> <title>Gentoo Upgrading Guide</title> @@ -23,8 +23,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>5</version> -<date>2013-02-09</date> +<version>6</version> +<date>2013-04-06</date> <chapter> <title>Gentoo and Upgrades</title> @@ -208,6 +208,25 @@ </body> </section> +<section> +<title>Upgrading from (too) old systems</title> +<body> + +<p> +Sometimes, systems are too old to easily upgrade. The upgrade path might need +intermediate versions of software (such as portage) that does not exist anymore, +and you might need to update the portage tree in steps (for instance incremental +tree updates with steps of 3 to 4 months). +</p> + +<p> +To upgrade such systems, you can use a recent stage3 to update the system. +Instructions for that are given in the <uri link="#old_system">Updating old +systems</uri> section. +</p> + +</body> +</section> </chapter> <chapter id="instructions"> @@ -683,4 +702,84 @@ </section> </chapter> +<chapter id="old_system"> +<title>Updating old systems</title> +<section> +<title>Idea of the upgrade</title> +<body> + +<p> +The idea with this upgrade approach is that we create an intermediate build +chroot in which a recent stage3 is extracted. Then, using the tools available in +the stage3 chroot we upgrade the packages on the live system. +</p> + +</body> +</section> +<section> +<title>Preparing the intermediate build chroot</title> +<body> + +<p> +Let's first create the intermediate build chroot location, say +<path>/mnt/build</path>, and extract a recent stage3 archive into it. +</p> + +<pre caption="Preparing the intermediate build chroot"> +# <i>mkdir /mnt/build</i> +# <i>tar -xf -C /mnt/build /path/to/stage3-somearch-somedate.tar.bz2</i> +# <i>mount --rbind /dev /mnt/build/dev</i> +# <i>mount --rbind /proc /mnt/build/proc</i> +# <i>mount --rbind /sys /mnt/build/sys</i> +</pre> + +<p> +Next, we create a mount point inside this chroot environment, on which we then +bind-mount the live (old) environment. +</p> + +<pre caption="Create host mountpoint"> +# <i>mkdir /mnt/build/mnt/host</i> +# <i>mount --rbind / /mnt/build/mnt/host</i> +</pre> + +<p> +So now the live (old) system is also reachable within +<path>/mnt/build/mnt/host</path>. This will allow us to reach the live (old) +system and update the packages even when chrooted inside the intermediate build +chroot. +</p> + +</body> +</section> +<section> +<title>Chroot and update</title> +<body> + +<p> +We now chroot into the intermediate build location, and start updating vital +packages on the live system, until we can continue updating the live system from +within the live system (rather than through the intermediate build chroot). +</p> + +<pre caption="Chrooting and updating important packages"> +# <i>chroot /mnt/build</i> +# <i>source /etc/profile</i> + +<comment># Now we start building packages onto the live system</comment> +# <i>ROOT=/mnt/host emerge -1v portage</i> +</pre> + +<p> +Keep this chrooted session open and try to update the live system. When you hit +failures, you can use this chrooted session to update packages using the build +tools available in the intermediate build chroot (which includes recent glibc, +gcc, etc.) Don't forget to prefix all <c>emerge</c> commands with +<c>ROOT=/mnt/host</c> within the chroot! +</p> + +</body> +</section> +</chapter> + </guide>
