From 29a4c46263e833aa196f2a01c3df67100caace59 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sun, 6 Mar 2022 18:33:24 +0200 Subject: docs: add a tutorial Sponsored-by: author --- tutorial.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 tutorial.md diff --git a/tutorial.md b/tutorial.md new file mode 100644 index 0000000..e9bbee2 --- /dev/null +++ b/tutorial.md @@ -0,0 +1,115 @@ +# Install Debian on a bare metal system with v-i + +You need: + +- a USB drive, at least 4 GB +- a PC that supports UEFI +- backups: _all drives_ in the PC will be wiped from data + +The steps: + +1. Download the installer image from + . You can use `curl` or `wget` + or your web browser. Use **one of** the following commands: + + ~~~sh + curl https://files.liw.fi/v-i/v-i.img.xz > v-i.img.xz + wget -c https://files.liw.fi/v-i/v-i.img.xz + ~~~ + +2. Unpack the image. + + ~~~sh + unxz v-i.img.xz + ~~~ + +3. Insert USB drive and write the image to the stick. I prefer GNOME + Disks for this, but dd will work. Look up the device of the USB + stick: run `sudo dmsg -T` and look for relevant kernel message, or + use GNOME Disks, or something else. Replace the actual device for + `sdx` below, then run the following command: + + ~~~sh + dd if=v-i.img bs=1M oflag=direct status=progress of=/dev/sdx + ~~~ + +4. You will need to be able to log into the installer, once it's + running. You can do this by logging in as `root` without a password + on the virtual console, or you can use SSH. Note that SSH logins as + root _must_ use key authentication: passwords _do not work_. + + For SSH login you need to install your SSH public key into the + `authorized_keys` file. If you want that, use **one of** the + following two: + + - run a script to install it on the USB drive you've just written + the image to: + + ~~~sh + sudo bash set-authorized-keys /dev/sdx path/to/your/key.pub + ~~~ + + - create a second stick with a file system with the label + `v-i-config` and a file called `authorized_keys`, and have that + in a USB port when you boot from the v-i USB drive + +5. Make sure everything has been written to the USB drive. Again, I + prefer GNOME Disks for this, but from the command line: + + ~~~sh + sync + eject /dev/sdx + ~~~ + +6. Move the USB drive to the target machine and boot off the drive. + How this happens varies from machine to machine. On my Thinkpad, I + press F12 at the POST screen and then choose the right drive from + the boot menu. + +7. Wait for the system to boot. Log in as root, either from the + virtual console (no password), or via SSH. + +8. Create a target specification file `foo-target.yaml`. The name can + be anything, but it must be valid YAML. In the example below, there + are two NVMe drives. An extra logical volume is created. An extra + Ansible playbook is run against the target system. The given SSH + public key is installed into the `authorized_keys` file for the + `root` user on the target system. All drives will be encrypted + using LUKS, with the password "hunter2". + + ~~~yaml + luks: hunter2 + drive: /dev/nvme0n1 + extra_drives: + - /dev/nvme1n1 + hostname: foo + extra_playbooks: + - foo-playbook.yml + ansible_vars: + user_pub: | + ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPQe6lsTapAxiwhhEeE/ixuK+5N8esCsMWoekQqjtxjP liw personal systems + extra_lvs: + - name: vms + size: 1T + fstype: ext4 + mounted: /mnt/vms + ~~~ + +9. Install. Add the `--verbose` option to `./v-i` if you want to know + what's happening. The first time you run this on a given v-i USB + drive, it takes a while: it runs `vmdebootstrap` and that is just + slow. However, the output is cached, so further runs are faster. + + ~~~sh + rm -f install.log + ./v-i foo-target.yaml + ~~~ + +10. Reboot into the installed system. + +11. Finish configuring the system in whatever way you like to do that. + You can log into it via SSH as root. I use Ansible. + + Remember to change the LUKS password for each drive. + +12. Optional: Let me know how it went. -- cgit v1.2.1