diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 88 |
1 files changed, 34 insertions, 54 deletions
@@ -21,17 +21,17 @@ choice (the author uses Ansible). The basic system allows you to log in as root with SSH using the key you provide to **v-i**. The installer removes all partitions on all drives on the system, and sets up LUKS and LVM2 on all the drives you specify. It sets up the time -zone and console keyboard layout you specify. It installs the -`locales-all` package so your locale is available. It sets up the -system to use the `deb.debian.org` Debian CDN mirror network. Anything -else you'll have to install and configure yourself. +zone and console keyboard layout you specify. The installed system is +fairly basic, but functional. Anything else you'll have to install and +configure yourself. **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.) +tricky. What was meant to be a weekend hack turned into a multi-year +project, on and off.) **v-i** uses **vmdb2** to install onto bare metal hardware. [**vmdb2**][] is a program to create a disk image virtual machines @@ -59,37 +59,8 @@ hostname: exolobe5 drive: /dev/nvme0n1 ``` -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 - 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. - ([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`---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 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 - 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 by the standard playbook - - the `user_ca_pubkey` variable contains public key for an SSH CA - whose user certificates are to be trusted +See [spec.md][] for a full description of the target specification +file. 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 @@ -108,6 +79,8 @@ tedious.) [`build-installer.sh`]: build-installer.sh [`v-i`]: v-i [`std.yml`]: std.yml +[spec.md]: spec.md +[tutorial]: tutorial.md [author]: https://liw.fi/ [Debian installer]: https://www.debian.org/devel/debian-installer/ [preseed files]: https://wiki.debian.org/DebianInstaller/Preseed @@ -174,10 +147,11 @@ standard system looks like this: * 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 + - network setup on `eth0` using `systemd-networkd` + - optionally wifi using `systemd-networkd` and `iwd` - SSH host key and host certificate installed if defined - - log in to `root` over SSH using a key or user certificate + - `root` password is locked, no login on console + - log in as `root` allowed 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 @@ -190,17 +164,19 @@ still being installed in a chroot. 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 +* delete any trace of LVM2 from all drives, erase all SSDs (securely, + if possble), 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 cleartext EFI and boot partitions, needed to boot with UEFI + and LUKS * create a physical volume for LVM2, and a logical volume for the root file system - add any additional drives as physical volumes to the volume group - - optionally use LUKS for full disk encryption for each physical - volume + - optionally use LUKS2 for full disk encryption for each physical + volume (LUKS2 for `argon2id` support) * install the Debian base system - run `debootstrap`, install a boot loader, and create fstab and `crypttab` files @@ -211,7 +187,8 @@ Thus, **v-i** does the following: - install an SSH server - add a chosen SSH public key to the root user's authorized keys file -* run any additional playbooks + - other configuration +* run any additional playbooks provided by the user **v-i** uses the **vmdb2** caching feature, where the results of `debootstrap` and some other steps get stored in a compressed tar @@ -241,12 +218,14 @@ Also, to build an image to boot off for running the installer: * `installer.yml`---the Ansible playbook for creating the installer image -See the tutorial about ways to add your SSH public key to the image so +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 -the installer. +the installer. If you have a working installer image, you can update +those two files by copying new versions into place: this is much +faster than building a whole new installer image. @@ -257,14 +236,15 @@ yet, but expects the following to be asked. ### What version of Debian does v-i install? -**v-i** installs Debian 11 (bullseye). +**v-i** installs the Debian stable release, by default. That's version +12 (bookworm) at the time of writing this. You can install other +versions by setting the `debian_release` field in the target +specification file. Any version from Debian 11 onward should work. ### What about other releases of Debian? The Debian 11 (bullseye) release is the earliest release the author -has gotten to work with **v-i**, and is the only release the author is -installing on bare metal systems. Later versions of Debian may work, -we will see. +has gotten to work with **v-i**. ### Is only UEFI supported? @@ -365,7 +345,7 @@ wifi_password: notopen The installed system is plain Debian, and you can configure it to support wifi as you would any other Debian system. The `v-i` installer -does not copy over the wifi credentials to the installed system. +**does** copy over the wifi credentials to the installed system. ### I'd like to use v-i, but I need changes |