doc updates

README.md

@@ -65,7 +65,10 @@ ready for the script to run. The `Master.sh` script calls the `CH06.*` scripts.
 Chapter 07 Building
 -------------------
 
-__PAY ATTENTION__: First, the `root` user must execute the `CHROOT.sh` script.
+__PAY ATTENTION__: First, the `root` user must execute the `CHROOT.sh` script:
+
+    root# bash CHROOT.sh
+
 That script will copy `CH7Build` and `CH8Build` into `/mnt/newlfs/sources` and
 then fix some permissions and set up `/mnt/newlfs` for the `chroot`
 environment.
@@ -75,16 +78,16 @@ Finally, it echoes the command that the `root` user must execute to enter the
 
 Once in the `chroot`:
 
-    cd /sources/CH7Build
+    root# cd /sources/CH7Build
-    bash 0-CH07-Prep.sh
+    root# bash 0-CH07-Prep.sh
 
 After executing `0-CH07-Prep.sh` reload `bash` with the following:
 
-    exec /usr/bin/bash --login
+    root# exec /usr/bin/bash --login
 
 Then, still inside the `chroot` at `/sources/CH7Build`, execute:
 
-    bash Master.sh
+    root# bash Master.sh
 
 The script works but is not finished. To do, it needs to verify the system is
 ready for the script to run. The `Master.sh` script calls the `CH07.*` scripts.
@@ -103,16 +106,23 @@ instructions for creating the backup involved deleted the `/mnt/newlfs/sources`
 directory.
 
 As the `lfs` user, re-run the `CH03-get-sources.sh` script to restore the
-sources. The script will restore them from backup, it will not need to fetch
+sources:
-them again.
+
+    lfs$ bash CH03-get-sources.sh
+
+The script will restore the sources from the backup it made the first time it
+ran, it will not need to fetch them again.
 
 Then as the `root` user, once again execute the `CHROOT.sh` script to set up
-the `chroot` environment and copy the build scripts into it. Again, the script
+the `chroot` environment and copy the build scripts into it:
-will echo the command to enter the `chroot`. Execute it as `root` and then
-once in the `chroot` environment:
 
-    cd /sources/CH8Build
+    root# bash CHROOT.sh
-    bash Master.sh
+
+Again, the script will echo the command to enter the `chroot`. Execute it as
+`root` and then once in the `chroot` environment:
+
+    root# cd /sources/CH8Build
+    root# bash Master.sh
 
 That will run many of the `CH08.*` scripts, building the LFS system through
 `CH08.34-bash`. Note that when it builds the `shadow` package, it first builds
@@ -125,12 +135,16 @@ the freshly rebuilt `bash` will be loaded.
 
 Once in the `chroot` environment again:
 
-    cd /sources/CH8Build
+    root# cd /sources/CH8Build
-    bash Master2.sh
+    root# bash Master2.sh
 
 That will run the rest of the `CH08.*` scripts. Assuming all goes well, the
 system will be ready for LFS Chapter 9 configuration.
 
+It also builds several packages from BLFS, specifically enough so that `wget`
+and `curl` are built, along with the TLS certificate bundles needed for those
+tools to make TLS (HTTPS) connections.
+
 Note that `Master2.sh` does have a major deviation from the LFS book. It builds
 LibreSSL to provide the OpenSSL API (e.g. as used by the `kmod` package). Most
 software that builds against OpenSSL will build against LibreSSL and I have

TLS-README.md

@@ -53,6 +53,46 @@ maintained but until then, YJL can still use LibreSSL for *most* OpenSSL API
 needs and use OpenSSL exclusively for Python3.
 
 
+Important Concept
+-----------------
+
+On YJL, `/usr/bin/libressl` is guaranteed to exist. It is a required package and
+is always there.
+
+On YJL, `/usr/bin/openssl` *might* exist but may not be present. When it is
+present, it *might* be a symbolic link to `/usr/bin/openssl` or it *might* be
+the binary built from OpenSSL.
+
+Scripts that ordinarily call the `openssl` binary should call the `libressl`
+binary instead and should not use features of OpenSSL newer than what was
+present in OpenSSL 1.0.1g which is the version that LibreSSL forked.
+
+When a script genuinely needs to use the `openssl` binary with newer features,
+then (and only then) the script should be packaged via RPM with:
+
+    Requires: /usr/bin/openssl >= n
+
+where `n` is the minimum version of OpenSSL that provides the needed feature.
+YJL will maintain an RPM package for a recent versions of OpenSSL to meet that
+requirement.
+
+If (like Python 3) all you need is the shared library from the recent version of
+OpenSSL, RPM will take of the shared library resolution but the RPM spec file
+should have:
+
+    BuildRequires: openssl-devel
+
+so that the proper devel package is present on the system when the package
+builds.
+
+On the other hand, packages that build just fine against LibreSSL should have:
+
+    BuildRequires: libressl-devel
+
+so that the proper devel package is present on the system when the package
+builds.
+
+
 LibreSSL Build Notes
 --------------------
 
@@ -111,3 +151,14 @@ This method also allows generation of the initial certificate bundles even from
 within the `chroot` being used to build the LFS system before the system has
 ever booted so that the certificate bundles are there even on the very first
 boot, allowing both `wget` and `curl` to work properly with TLS connections.
+
+Most users will never have to do anything. As long as the machine has a network
+connection, once a week `make-ca` will check for a new `certdata.txt` file and
+securely retrieve it if found, regenerating the TLS certificate bundles.
+
+Users who do not trust all of the certificate authorities Mozilla does, or who
+do trust certificate authorities Mozilla does not trust, can (assuming `root`
+privilege) adjust the generation of the certificate bundles as needed.
+
+The BLFS mechanism for maintaining TLS certificate bundles really is superior to
+what is in the vast majority of GNU/Linux distributions. I like it.