From b21be9fefe11d2c626e34aaf8e44c310040fcb90 Mon Sep 17 00:00:00 2001 From: YellowJacketLinux Date: Thu, 10 Oct 2024 06:16:13 -0700 Subject: [PATCH] doc updates --- README.md | 42 ++++++++++++++++++++++++++++-------------- TLS-README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index f6ec5ba..640ce15 100644 --- a/README.md +++ b/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 - bash 0-CH07-Prep.sh + root# cd /sources/CH7Build + 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 -them again. +sources: + + 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 -will echo the command to enter the `chroot`. Execute it as `root` and then -once in the `chroot` environment: +the `chroot` environment and copy the build scripts into it: - cd /sources/CH8Build - bash Master.sh + root# bash CHROOT.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 - bash Master2.sh + root# cd /sources/CH8Build + 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 diff --git a/TLS-README.md b/TLS-README.md index 17843cc..ef72b59 100644 --- a/TLS-README.md +++ b/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.