From: Ralph Ronnquist <rrq@rrq.au>
Date: Fri, 8 Mar 2024 13:27:45 +0000 (+1100)
Subject: adding some basic documentation
X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=d3c0d6890a7770a94b6463da39f5ba613b02cb3a;p=rrq%2Frescue-boot.git

adding some basic documentation
---

diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..f0e6f44
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,49 @@
+= rescue-boot
+
+This project holds scripts that prepares a "rescue" boot image file
+with a Devuan ceres minbase filesystem.
+
+* +./minbase-strap.sh+ prepares boot-ceres-$ARCH.img
+
+  - +./minbase-strap-bios.sh+ include fragment preparing bios boot equipment
+
+  - +./minbase-strap-uefi.sh+ include fragment preparing uefi boot equipment
+
+  - +./minbase-strap-mkimg.sh+ include fragment packaging into disk file
+
+* +./run.sh boot-ceres-$ARCH.img+ boots it up in a virtual machine.
+
+== About the boot image preparation
+
+The rescue boot image is a full disk image with two partitions. The
+first is a FAT partition that contains a linux kernel and initrd for
+the kernel and boot equipments using syslinux for both legacy bios and
+UEFI bios boot.
+
+The initrd.gz file is quite large makign the partition somewhat larger
+than 100M and this makes it less ameniable as boot image for a hybrid
+ISO (which has a 32M limit).
+
+The preparation populates a root filesystem in the FS directory by
+using debootstrap followed by certain "Captain's Picks" to include
+partcular choice software.
+
+The scripting asks firstly for a kernel choice and then an init script
+choice to optionally replace the "standard" initrd init script with
+some rescue variant.
+
+== About the virtual machine setup
+
+The run.sh script starts a QEMU system emulator for the boot image
+given on the command line. E.g.,
+
+    $ ./run.sh boot-ceres-amd64.img
+
+With environment setting EFI=yes, the emulation uses UEFI boot. E.g.
+
+    $ EFI=yes ./run.sh boot-ceres-amd64.img
+
+The script assumes the host has a "vde2" setup with a "vde-switch"
+using control directory "/run/vde.ctl". Any alternatie network setup
+needs script hands-on to change the "NET=.." variable.
+