summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2022-06-13 05:23:00 +0000
committerLars Wirzenius <liw@liw.fi>2022-06-13 05:23:00 +0000
commitc264f7ac39e6a10742130ed9889505f24b1be3f4 (patch)
treea61903fc8ff9c184f28bbd25ed2a004c0e148011
parentda4a5897c19da6609c32ea947b184b5619472ee7 (diff)
parentd37a6deeceeb49bdfb26b69ccc351b7e3e40697a (diff)
downloadv-i-c264f7ac39e6a10742130ed9889505f24b1be3f4.tar.gz
Merge branch 'docs' into 'main'
docs: improve README to be clearer about the installed system See merge request larswirzenius/v-i!24
-rw-r--r--README.md98
1 files 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