From d37a6deeceeb49bdfb26b69ccc351b7e3e40697a Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Mon, 13 Jun 2022 08:22:14 +0300 Subject: docs: improve README to be clearer about the installed system Sponsored-by: author --- README.md | 98 +++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 57 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index b9fd6db..86ba2a0 100644 --- a/README.md +++ b/README.md @@ -8,20 +8,26 @@ emptied. Any existing partitions will be lost. Forget any data you used to have, and operating systems you used to have installed. If you don't know what you're doing, leave.** -**v-i** installs Debian onto a PC. It's entirely non-interactive, -dangerous, unhelpful, and may only work for the author's PCs. The -[author][] wrote it so that repeated installations would be less of a -chore, for them, than using the official Debian installer. (Actually, -the author thought it'd be a quick, easy hack, and was too stubborn to -give up, when it turned out to be a bit tricky.) - +**v-i** installs enough of Debian installed so that the system can be +configured with a configuration management system once it's up an +running. **v-i** isn't meant to install a full desktop stack or +service suite: it's meant to provide a base on which such can be +installed. However, **v-i** can probably do that, but the [author][] +thinks such setup and configuration is better done post-install. + +**v-i** installs a very basic Debian onto a PC. It's entirely +non-interactive and unhelpful. The author wrote it so that repeated +installations would be less of a chore than using the official Debian +installer. (Actually, the author thought it'd be a quick, easy hack, +and was too stubborn to give up, when it turned out to be a bit +tricky.) + + **v-i** uses **vmdb2** to install onto bare metal hardware. [**vmdb2**][] is a program to create a disk image virtual machines with Debian, by the same author. It "installs Debian" to a file representing a hard drive. It's basically [debootstrap][], except the -target is a disk image instead of a directory. vmdb2 has been quite -useful for generating virtual machine images. It's also used to create -[Debian images for Raspberry Pis][]. **v-i** uses **vmdb2** to install -onto bare metal hardware. +target is a disk image instead of a directory. It's used to create +[Debian images for Raspberry Pis][]. To use **v-i** to install Debian on a PC: @@ -32,28 +38,17 @@ To use **v-i** to install Debian on a PC: - the author logs into the installer system via SSH * Create a v-i target specification file. See below for an example. * Run the command: `v-i --verbose exolobe5.yaml` -* See `installer.log` for what happened during the installation. +* See `installer.log` for what happened during the installation, if + anything failed. Example target specification file: ```yaml -drive: /dev/nvme0n1 -extra_drives: - - /dev/nvme1n1 hostname: exolobe5 -extra_playbooks: - - exolobe5-ansible.yml -ansible_vars: - user_pub: | - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPQe6lsTapAxiwhhEeE/ixuK+5N8esCsMWoekQqjtxjP liw personal systems -extra_lvs: - - name: vms - size: 1T - fstype: ext4 - mounted: /mnt/vms +drive: /dev/nvme0n1 ``` -Explanation: +A number of fields are allowed in the specification file: * `hostname`---the hostname of the installed system. This is so that when the installed system boots, and gets a network address using @@ -64,15 +59,15 @@ Explanation: * `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, and will be used entirely as physical +* `extra_drives`---a list of any additional physical volumes for LVM2. + These 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 - hardware token's challenge/response feature or TPM for LUKS, that's - better done on a running system. + password that is in cleartext. _You are expected to change it_ + after the system is installed and booted. If you'd rather use, say, + a hardware token's challenge/response feature or TPM for LUKS, + that's better done on a running system. * `extra_playbooks`---additional Ansible playbooks to use on the installed system. **v-i** comes with a "standard playbook" (in [`std.yml`][]) that it uses unconditionally, to set up a "standard @@ -116,20 +111,20 @@ 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 slightly -for their use case: +However, the **v-i** author felt it was lacking for their needs: * 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 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. + changes to the installer 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. Well, easy for its author. + understand and change. Well, easy for its author. The price for this + is less flexibility and less ease of use. * d-i is primarily meant to be used interactively, but it does support [preseed files][] for automating an installation. Preseeding means @@ -156,7 +151,22 @@ package in the system being installed. **v-i** defines a fairly minimal _standard install_, whose goal is to get the target system into a state where it boots from its own, internal storage, and where the rest of the system configuration can -be finished using your configuration management system of choice. +be finished using your configuration management system of choice. The +standard system looks like this: + +* UEFI boot, with an EFI partition (500 MiB) +* a cleartext `/boot` partition (500 MiB) +* LVM2 for the rest of the target drive, and all extra drives + - one VG + - no RAID at this time +* optional LUKS for all physical volumes, using the same passphrase +* a `root` LV (20 GiB) +* the rest of the VG not allocated +* a basic Debian installation + - `root` password is locked + - network setup on `eth0` using systemd-networkd + - SSH host key and host certificate installed if defined + - log in to `root` over SSH using a key or user certificate While **vmdb2** can, and does, run Ansible to configure the system being installed, in practice some things work better if most @@ -326,7 +336,13 @@ This might require paying them. The author is, unfortunately, probably not willing to spend their free time to make changes that don't benefit them directly, for free. Sorry. They _are_ willing to review and merge changes that would make -the software better. +the software better. (Also, the author is willing to be paid for such +work, for corporate customers. Unfortunately, invoicing private people +is too complicated.) + +### Why write v-i, when X, Y, and Z already exist? + +The author likes writing software, and dislikes evaluating software. # Legalese -- cgit v1.2.1