From f21ac0c30a2097fdb09a990fdb219e079ecb0671 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sun, 6 Mar 2022 18:58:55 +0200 Subject: docs: tidy up README Sponsored-by: author --- README.md | 58 ++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 1d1294e..14a00fb 100644 --- a/README.md +++ b/README.md @@ -60,12 +60,14 @@ Explanation: DHCP, it can provide a name. The author's home network setup automatically adds that hostname to the internal DNS. This avoids a manual DNS configuration step, and the author is lazy. -* `drive`---the main drive to install to. This will have the EFI and - `/boot` partitions, and have GRUB installed. The rest of the drive - will be a physical volume for LVM2. + ([dnsmasq](https://dnsmasq.org/) is lovely.) +* `drive`---the main drive to install to. This is where the EFI and + `/boot` partitions are created, and where GRUB gets installed. The + rest of the drive will be a physical volume for LVM2. * `extra_drives`---any additional physical volumes for LVM2. These - will not be partitioned. -* `luks`---the password for full disk encryption for LVM2 physical + will not be partitioned, and will be used entirely as physical + volumes. +* `luks`---the password for full disk encryption for all LVM2 physical volumes. If not set, LUKS is not used. This is a single, fixed password that is in cleartext. You are expected to change it after the system is installed and boots. If you'd rather use, say, a @@ -76,14 +78,15 @@ Explanation: [`std.yml`][]) that it uses unconditionally, to set up a "standard system" that the author likes. You can provide additional playbooks, for additional configuration at installation time. +* `ansible_vars`---variables to set for Ansible playbooks. - the `user_pub` variable contains an SSH public key that gets installed into the `root` user `authorized_keys` file on the - installed system -* `ansible_vars`---variables to set for Ansible playbooks. + installed system by the standard playbook With all this configuration in a file, which you can keep in git, you can install a base system repeatedly to a specific computer, and do it -the same way every time. +the same way every time. If that's not something you do, then you may +want to use the official Debian installer instead. (Caveat: **v-i** does nothing to configure your BIOS/UEFI. It can't. You have to manually configure it the way you want it to be. For @@ -106,24 +109,25 @@ tedious.) The official [Debian installer][] is often referred to as _d-i_. It works quite well, for almost any hardware Debian can run on, and -supports a lot of languages, and if flexible enough to be acceptable +supports a lot of languages, and it's flexible enough to be acceptable for nearly every use case. Millions upon millions of people are satisfied users of it. It is a great achievement of Debian, and the people of the `debian-boot` team. -However, the **v-i** author felt it could be improved upon for them: +However, the **v-i** author felt it could be improved upon slightly +for their use case: * d-i is not entirely easy to understand and modify. It requires building special [udeb][] packages for any software that's to be part of the installer environment, which makes it harder to make - changes without collaboration from maintainers of those packages. - The architecture of d-i is also a little non-linear. d-i also needs - to support a very wide variety of hardware and use cases, which has + changes without co-operation from maintainers of those packages. The + architecture of d-i is also a little non-linear. d-i also needs to + support a very wide variety of hardware and use cases, which has made it large and complex. **v-i** is happy with normal deb packages, and is a thin Python wrapper script around **vmdb2**, making it reasonably easy to - understand and change. + understand and change. Well, easy for its author. * d-i is primarily meant to be used interactively, but it does support [preseed files][] for automating an installation. Preseeding means @@ -154,7 +158,8 @@ be finished using your configuration management system of choice. While **vmdb2** can, and does, run Ansible to configure the system being installed, in practice some things work better if most -configuration is done to a running system. The goal of **v-i** is to +configuration is done to a running system; if nothing else, some +Ansible modules don't work well in a chroot. The goal of **v-i** is to get a system into that state as quickly and easily as possible. For example, the Ansible module to set a hostname on a system with systemd requires systemd to be running. That's awkward while the system is @@ -164,6 +169,8 @@ Thus, **v-i** does the following: * delete any trace of LVM2 from all drives, wipe all SSDs, and generally reset the system to as close to a blank state as possible + - there is no question "are you sure?" to give the user a chance to + repent: as soon as you run **v-i**, you've lost all your data * create a partition table ("label") on the target drive * create EFI and boot partitions, needed to boot with UEFI and LUKS * create a physical volume for LVM2, and a logical volume for the root @@ -189,7 +196,8 @@ archive. On subsequent runs, if the cache file exists, it's unpacked, instead of running the commands. This speeds things up a bit: running **v-i** without the cache file takes the author about 5 minutes; with the cache file it takes about 1.5 minutes. This matters if there is a -need to do many installations. +need to do many installations. It also matters if you're developing +an installer and need to run it tens of times a day. ## Hacking @@ -210,11 +218,8 @@ Also, to build an image to boot off for running the installer: * `installer.yml`---the Ansible playbook for creating the installer image -You'll want to build your own installer image, if you want to log into -it over SSH, so that you can install your own SSH key. If you log in -via the Linux virtual console, you don't need that: there's no -password for root (but SSH login for root doesn't work with -passwords). +See the tutorial about ways to add your SSH public key to the image so +that you can log into the installer via SSH. You probably mostly only need to modify `v-i` and `std.yml`. The rest is to get you and your target machine into a state where you can run @@ -242,10 +247,15 @@ we will see. Yes. +### Why is BIOS (without UEFI) not supported? + +All of the author's PCs have UEFI, and the author doesn't care to do +the work to add support for BIOS. + ### What about multi-boot? **v-i** doesn't support installing more than one operating system on -one computer. +one computer. The author has no need for this. ### What about installing something else than Debian? @@ -263,10 +273,10 @@ least the following steps in **vmdb2** code, and then change the cache tar archive * `apt`---install packages - whatever package manager the system has probably works - - you can probably run the package manager from a chroot step + - you can probably run the package manager from a **vmdb2** `chroot` step * `grub`---install boot loader - this chooses the appropriate Debian package automatically - - might possibly be doable as a chroot step + - might possibly be doable as a `shell` step - this is likely the trickiest bit: booting is _intricate_ * `cryptsetup`---format a drive for full disk encryption - this just runs the `cryptsetup` program and tells the fstab step -- cgit v1.2.1