From 343ab1388a38dc622766a4a43e02c63e30096fe2 Mon Sep 17 00:00:00 2001
From: Xi Ruoyao <xry111@xry111.site>
Date: Fri, 2 Feb 2024 05:15:03 +0800
Subject: [PATCH] Add info about how to upgrade Glibc on a running system

Let's change our policy to match other "rolling release" distros and
ease the procedure to fix Glibc security vulnerabilities.

Squashed the commits in xry111/update-glibc branch to keep the history
clean.

Co-Authored-By: Pierre Labastie <pierre.labastie@neuf.fr>
Co-Authored-By: Douglas R. Reno <renodr@linuxfromscratch.org>
---
 chapter08/glibc.xml  | 115 +++++++++++++++++++++++++++++++++++++++++++
 chapter08/pkgmgt.xml |  18 ++-----
 2 files changed, 118 insertions(+), 15 deletions(-)

diff --git a/chapter08/glibc.xml b/chapter08/glibc.xml
index 86b830249..e09fe4900 100644
--- a/chapter08/glibc.xml
+++ b/chapter08/glibc.xml
@@ -201,6 +201,121 @@ esac</userinput></screen>
 
 <screen><userinput remap="install">sed '/test-installation/s@$(PERL)@echo not running@' -i ../Makefile</userinput></screen>
 
+    <important>
+      <para>
+        If upgrading Glibc to a new minor version (for example, from
+        Glibc-2.36 to Glibc-&glibc-version;) on a running LFS system, you
+        need to take some extra precautions to avoid breaking the system:
+      </para>
+
+      <itemizedlist>
+        <listitem>
+          <!-- There are two reasons we don't support this:
+               1. Upgrading on a system with separate /lib and /usr/lib is
+                  tricky.
+               2. With Glibc prior to 2.34 libc.so.6 etc. are symlinks to
+                  libc-2.33.so etc., again causing the upgradation tricky.
+                  The Glibc NEWS file explicit states they no longer use
+                  symlinks for the ABI names to avoid upgradation
+                  issues.  -->
+          <para>
+            Upgrading Glibc on a LFS system prior to 11.0 (exclusive) is
+            not supported.  Rebuild LFS if you are running such an old LFS
+            system but you need a newer Glibc.
+          </para>
+        </listitem>
+
+        <!-- https://sourceware.org/pipermail/libc-alpha/2024-January/154095.html -->
+        <listitem>
+          <para>
+            If upgrading on a LFS system prior to 12.0 (exclusive), install
+            <application>Libxcrypt</application> following
+            <xref role='.' linkend='ch-system-libxcrypt'/>  In addition to
+            a normal <application>Libxcrypt</application> installation,
+            <emphasis role='bold'>you MUST follow the note in Libxcrypt
+            section to install
+            <filename class='libraryfile'>libcrypt.so.1*</filename>
+            (overwritting
+            <filename class='libraryfile'>libcrypt.so.1</filename> from the
+            prior Glibc installation)</emphasis>.
+          </para>
+        </listitem>
+
+        <!-- Otherwise on lfs-systemd nscd will fail to start on boot,
+             and on both lfs-sysv and lfs-systemd useradd etc. will try
+             to start nscd, then nscd will fail to start as well and
+             produce some spurious error message.  -->
+        <listitem>
+          <para>
+            If upgrading on a LFS system prior to 12.1 (exclusive),
+            remove the <command>nscd</command> program:
+          </para>
+
+          <screen role='nodump'><userinput>rm -f /usr/sbin/nscd</userinput></screen>
+
+          <para>
+            If this system (prior to LFS 12.1, exclusive) is based on
+            Systemd, it's also needed to disable and stop the
+            <command>nscd</command> service now:
+          </para>
+
+          <screen revision='systemd' role='nodump'><userinput>systemctl disable --now nscd</userinput></screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Upgrade the kernel and reboot if it's older than &min-kernel;
+            (check the current version with <command>uname -r</command>)
+            or if you want to upgrade it anyway, following
+            <xref linkend='ch-bootable-kernel' role='.'/>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Upgrade the kernel API headers if it's older than &min-kernel;
+            (check the current version with
+            <command>cat /usr/include/linux/version.h</command>)
+            or if you want to upgrade it anyway, following
+            <xref linkend='ch-tools-linux-headers'/> (but removing
+            <envar>$LFS</envar> from the <command>cp</command> command).
+          </para>
+        </listitem>
+
+        <!-- This is to ensure we don't start a process at the time point
+             where some Glibc shared libraries are updated but the others
+             are not.  Such mismatches can cause programs crash on startup,
+             esp. a mismatch between ld-linux-x86-64.so.2 and
+             libc.so.6.  Note that a crash in the installation process
+             will leave the system in a state with the mismatch forever,
+             unrecoverable without the help of another distro.  -->
+        <listitem>
+          <para>
+            Perform a <envar>DESTDIR</envar> installation and upgrade
+            the Glibc shared libraries on the system using one single
+            <command>install</command> command:
+          </para>
+
+          <screen role='nodump'><userinput>make DESTDIR=$PWD/dest install
+install -vm755 dest/usr/lib/*.so.* /usr/lib</userinput></screen>
+        </listitem>
+      </itemizedlist>
+
+      <para>
+        It's imperative to strictly follow these steps above unless you
+        completely understand what you are doing.
+        <emphasis role='bold'>Any unexpected deviation may render the
+        system completely unusable.  YOU ARE WARNED.</emphasis>
+      </para>
+
+      <para>
+        Then continue to run the <command>make install</command> command
+        and the <command>sed</command> command against
+        <filename>/usr/bin/ldd</filename>.  Once they are finished, reboot
+        the system immediately.
+      </para>
+    </important>
+
     <para>Install the package:</para>
 
 <screen><userinput remap="install">make install</userinput></screen>
diff --git a/chapter08/pkgmgt.xml b/chapter08/pkgmgt.xml
index 4c7bb6dd7..10ec5d199 100644
--- a/chapter08/pkgmgt.xml
+++ b/chapter08/pkgmgt.xml
@@ -63,21 +63,9 @@
 
       <listitem>
         <para>If Glibc needs to be upgraded to a newer
-        version, (e.g.,  from Glibc-2.31 to Glibc-2.32), it is safer to
-        rebuild LFS.  Though you <emphasis>may</emphasis> be able to rebuild
-        all the packages in their dependency order, we do not recommend
-        it.  </para>
-      </listitem>
-
-      <listitem>
-        <para>Reinstalling the same version of Glibc (&glibc-version; for
-        this release of LFS) with patches should be safe when these patches
-        do not change ABI and API.  When a security vulnerability is found
-        in Glibc, we often need to apply such a patch to fix the
-        vulnerability and reinstall Glibc.  Consult
-        <ulink url='&lfs-root;lfs/advisories/'>LFS security
-        advisories</ulink> if you are alerted for a published Glibc security
-        vulnerability but unsure about the action to take.</para>
+        version, (e.g.,  from Glibc-2.36 to Glibc-&glibc-version;),
+        some extra steps are needed to avoid breaking the system.
+        Read <xref linkend='ch-system-glibc'/> for details.</para>
       </listitem>
 
       <listitem> <para>If a package containing a shared library is updated, and