docs: add spec file spec

Sponsored-by: author

1 files changed, 177 insertions, 0 deletions

diff --git a/spec.md b/spec.md
new file mode 100644
index 0000000..8fe7ed9
--- /dev/null
+++ b/spec.md
@@ -0,0 +1,177 @@
+# v-i spec file spec
+
+The input file to `v-i`, called the "spec file", is a specification of
+the installation target. This is the specification of that file.
+
+Overview:
+
+* it's a YAML file in the form of a key/value map
+* it specifies things the installer needs to know
+* unknown keys are errors
+
+The keys that the installer understands are:
+
+* `hostname`---the name of the installed system, what `hostname` will output
+* `drive`---the boot drive
+* `extra_drives`---additional drives to format and add to the volume group
+* `extra_lvs`---additional logical volumes to create
+* `extra_playbooks`---additional Ansible playbooks to run
+* `ansible_vars`---variables for Ansible
+* `ansible_vars_files`---files with variables for Ansible
+* `luks`---cleartext password for full disk encryption
+* `debian_release`---which release of Debian to install
+* `root_fstype`---file system type of the root file system
+
+The `hostname` and `drive` fields are required, everything else is
+optional. No field may exist more than once.
+
+The fields are described in more detail in sections below.
+
+* `hostname`
+
+    The name of the installed system. This gets put into `/etc/hostname`
+    which the system will read when it boots.
+
+    A plain text string. The installer doesn't verify it, but if the
+    contents isn't suitable, the target system name will be wrong.
+
+    **Example:**
+    
+    ~~~yaml
+    hostname: exolobe1
+    ~~~
+
+* `drive`
+
+    The full path name of the block device for the boot drive of the
+    installed system, as seen by the installer. The boot loader will
+    be installed on this drive, `/boot` will be a partition, and the
+    rest of the drive will be a physical volume for the volume group
+    the installer creates. The drive will effectively be wiped:
+    partitions removed, physical volumes removed, all blocks on SSDs
+    discarded, etc, but not overwritten.
+
+    **Example:** first SATA drive
+    
+    ~~~yaml
+    drive: /dev/sda
+    ~~~
+
+    **Example:** first NVMe drive
+    
+    ~~~yaml
+    drive: /dev/nvme0n1
+    ~~~
+
+* `extra_drives`
+
+    A list of full path names of block devices of additional drives to
+    use as physical volumes in the volume group the installer creates.
+    The drives will be wiped the same way as the boot drive.
+    
+    The installer **will remove** all volume groups and physical
+    volumes even on drives not mentioned in `drive` or `extra_drives`.
+    It will discard all blocks only in the named drives, however.
+
+    **Example:**
+    
+    ~~~yaml
+    extra_drives:
+    - /dev/sdb
+    - /dev/sd
+    ~~~
+
+* `extra_lvs`
+
+    Additional logical volumes for the installer to create. The value
+    for this key is a list of key/value mappings describing the Luvs to
+    create, where the inner keys are:
+    
+    * `name`---name of of the LV
+    * `size`---size of the LV, in a format accepted by `lvcreate --size`
+    * `fstype`---type of the file system for the LV, defaults to `ext4`
+    * `mounted`---where the LV should be mounted
+
+    **Example:**
+    
+    ~~~yaml
+    extra_lvs:
+      - name: home
+        size: 202G
+        fstype: btrfs
+        mounted: /home
+    ~~~
+
+* `extra_playbooks`
+
+    A list of additional Ansible playbooks to run on the installed system. The
+    installer first runs its own standard playbook, and the additional
+    playbooks can make changes after that. The playbooks need to be
+    present in the installer.
+
+    **Example:**
+    
+    ~~~yaml
+    extra_playbooks:
+    - foo.yml
+    ~~~
+
+* `ansible_vars`
+
+    Variable definitions for Ansible playbooks. Note that these will
+    be set  for all playbooks the installer runs.
+
+    **Example:** `exolobe1`
+    
+    ~~~yaml
+    ansible_vars:
+      user_pub: |
+       ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPQe6lsTapAxiwhhEeE/ixuK+5N8esCsMWoekQqjtxjP
+    ~~~
+
+* `ansible_vars_files`
+
+    Like `ansible_vars`, but list of files with variable definitions
+    to give to Ansible.
+
+    **Example:**
+    
+    ~~~yaml
+    ansible_vars_files:
+      - hostid.yml
+    ~~~
+
+* `luks`
+
+    The cleartext password for full disk encryption (LUKS). You
+    probably want to change this after installing, but for very high
+    risk situations, be aware the reading SSD flash chips can let an
+    attacker access the old LUKS header after the change.
+
+    **Example:**
+    
+    ~~~yaml
+    luks: asdf
+    ~~~
+
+* `debian_release`
+
+    Code name of Debian release to install. Defaults to `bullseye`.
+
+    **Example:**
+    
+    ~~~yaml
+    debian_release: bookworm
+    ~~~
+
+* `root_fstype`
+
+    Type of the root file system. Defaults to `ext4`. (This is a
+    little-tested feature of `v-i`. Please report if it works for
+    you.)
+
+    **Example:**
+    
+    ~~~yaml
+    root_fstype: xfs
+    ~~~