POSIXify, add docs, other changes

1 files changed, 56 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..4630f38
--- /dev/null
+++ b/README
@@ -0,0 +1,56 @@
+This is my initramfs generator. I use this on my desktop Gentoo system. For my
+laptop Arch system, I use mkinitcpio.
+
+Basically, it's a suckless initramfs generator: it does exactly what I need.
+You need something else? Patch it, it's only 117 lines.
+
+Features:
+
+- password LUKS unlock
+- SSH remote unlock
+- firmware loading
+- extremely fast initramfs creation: compression off: ~70ms cold cache, ~30ms
+  warm; lz4 --best: 1.6s
+- extremely fast initramfs runtime: ~zero overhead compared to direct kernel
+  loading
+- minimal code: 117 SLOC total (init + make + Makefile + unlock)
+- pure POSIX shell + POSIX Makefile
+
+Drawbacks:
+
+- no modprobe support. custom kernel is required to use myinitramfs. if you
+  want configurability, probably better to use mkinitcpio or dracut.
+- pure POSIX shell + POSIX Makefile
+
+Usage:
+
+0. Read (skim) https://wiki.gentoo.org/wiki/Custom_Initramfs.
+
+1. Install busybox, dropbear, e2fsprogs (if you use ext4).
+
+2. Adjust ./init as required:
+   a) Adjust networking as required (e.g. maybe static IP instead of DHCP, or
+      you don't use eth0)
+   b) Adjust UUID (probably yours is not the same as mine)
+   c) Adjust fsck as needed (if you are not using ext4)
+   d) Put whatever you want:
+
+3. Adjust ./make as required:
+   a) Put your needed commands in gen_cpio_list.
+   b) Select your desired compressor at the end. Try make comp_bench for a comparison.
+      summary: lz4 is usually best, xz if storage is important above all (saves
+      a few MB but adds ~0.5s to boot), gzip is mediocre on both size and
+      speed, lzo is almost always worse than lz4, never use bzip2 or lzma.
+
+4. Customize cpio_list.txt with your required files. Remember that commands
+   must go in ./make (for library detection), and device files except
+   /dev/console and non-empty directories can be omitted.
+
+5. Add your public keys to authorized_keys. Note that dropbear only supports
+   RSA and ECDSA keys.
+
+6. make
+
+7. sudo make install
+
+8. Configure your boot loader/boot manager to use initramfs.img.