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:

  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

  drive: /dev/sda

  Example: first NVMe drive

  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:

  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:

  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:

  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

  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:

  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:

  luks: asdf

• debian_release

  Code name of Debian release to install. Defaults to bullseye.

  Example:

  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:

  root_fstype: xfs