From ec840ea16bd56ed9ac60a6726450ca3c42ee4e3f Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 28 Oct 2023 10:53:42 +0300 Subject: docs: update `install.md` to match current v-i better Signed-off-by: Lars Wirzenius Sponsored-by: author --- install.md | 126 ++++++++++++++++++++++++++++------------------------- puomi-playbook.yml | 6 +-- 2 files changed, 70 insertions(+), 62 deletions(-) diff --git a/install.md b/install.md index 483efc6..f0dabaf 100644 --- a/install.md +++ b/install.md @@ -12,6 +12,7 @@ To use Puomi you need: * A USB drive to hold the installer image. * A second machine to provision the router. Below, we call it the "laptop", but it can be any machine. +* Some Ethernet cables. To install, short version: @@ -19,8 +20,8 @@ To install, short version: - v-i is a custom installer for Debian * Write the image to a USB drive. * Configure the USB drive. +* Copy the Puomi specification file and playbook to USB drive. * Boot your router PC from the USB drive. -* Copy the Puomi specification file and playbook to installer. * Install Puomi on the PC. * Boot the PC. @@ -28,101 +29,108 @@ These steps will be covered in more detail below. ## Get installer image -* Download the 0.2 release image and helper scripts, using any - download you like. - - - - - - +* Download the latest release image and helper scripts, using any + download tool you like. + - + * Decompress the image. + - `unxz v-i.img.xz` -* Create an installer configuration, like the one below. Below, we - call it `your.yaml`. The simplest is to set one configuration key to - the name of your SSH public key file. -~~~yaml -authorized_keys_file: mykey.pub -~~~ +* Create an empty installer configuration file. Below we call it + `your.yaml`, but you can call it anything. If you want, you can add + content, see [v-i documentation](https://doc.liw.fi/v-i/spec.html) + for details. + + ~~~sh + touch your.yaml + ~~~ * Insert the USB drive to a USB port, and find out the device name. (GNOME Disks is a good tool for this. Kernel messages will also tell you.) Below, we call it `/dev/sdx`. + * Write the installer to the USB drive and configure it. -~~~sh -./write-and-config your.yaml /dev/sdx -~~~ + ~~~sh + ./write-and-config your.yaml /dev/sdx + ~~~ + +* Create a "specification" file to describe the installation you want + to do. Below we call it `x220.yaml`. You can pick any host name. The + drive must be the drive from which the PC boots. You may want to + check what it is called when the installer runs: it may change when + the installer USB drive is plugged in. + + ~~~yaml + drive: /dev/sda + hostname: x220 + extra_playbooks: + - puomi-playbook.yml + ansible_vars: + user_pub: | + YOUR SSH PUBLIC KEY GOES HERE + ~~~ + +* Copy the spec file and the Puomi initial playbook to the installer + drive, to `root` user home directory. The drive should still be + mounted after the previous steps. Run `df` to see where it is + mounted. + + ~~~sh + cp x220.yaml puomi-playbook.yml /media/$USER/$SOMETHING/root/ + ~~~ * Make sure everything is written to the drive, then remove it. -~~~sh -eject /dev/sdx -~~~ + ~~~sh + udisksctl power-off -b /dev/sdx + ~~~ * You may want to label the physical drive so you remember which one is the installer. -## Install on your PC. +## Install on your router PC. * Connect the router PC's main Ethernet port to your home Internet connection. This can be directly to the external network, or to your existing router. - - the main port is the one know to Linux as "eth0" + + - the main port is the one known to Linux as `eth0` - you may have to boot into the installer and experiment to find out which one it is -* Connect your laptop to any other Ethernet port in the router PC. + * Insert the installer USB to the router PC and boot off it. This may involve telling your BIOS which drive to boot from. Every BIOS is different about this. -* Your laptop should get an address 10.1.1.something from the router - DHCP. Your laptop won't be able to access the Internet, but you can - log into the installer. Check that you can log, then log out again. - -~~~sh -ssh root@v-i -~~~ - -* Create a "specification" file to describe the installation you want - to do. Below we call it `x220.yaml`. You can pick any host name. The - drive must be the drive from which the PC boots. You may want to - check what it is called when the installer runs: it may change when - the installer USB drive is plugged in. - -~~~yaml -drive: /dev/sda -hostname: x220 -extra_playbooks: - - puomi-playbook.yml -ansible_vars: - user_pub: | - YOUR SSH PUBLIC KEY GOES HERE -~~~ - -* Copy the spec file and the Puomi initial playbook to the installer. -~~~sh -scp x220.yaml puomi-playbook.yml root@v-i: -~~~ +* Log in via the virtual console as `root` (no password required) and + run the installer. Note that logging in as root without a password + only works on the virtual console, not via SSH. -* Log back into the installer, and do the install. Run the following - in the installer: + ~~~sh + v-i --verbose x220.yaml + ~~~ -~~~sh -./v-i --verbose x220.yaml -~~~ + This may take several minutes. -* Reboot. +* Reboot the router PC. Depending on your BIOS, you may need to remove + the installer USB drive, but wait until the installer kernel has + unmounted it. To be entirely sure, power off, then remove the drive, + then power on again. The router PC should now boot into a Debian system that has been -configured as an Internet router. Your laptop, still connected to the -router, should be able to access the Internet normally. DNS should -work just fine. +configured as an Internet router. If you connect your laptop to the +router (any Ethernet port except `eth0`), it should be able to access +the Internet normally. The router provides hosts on the LAN addresses +via DHCP. The router implements NAT, which means that your laptop won't be accessible directly from the public side of the router PC: any connections must be initiated by the laptop. There is, however, no firewall, unless you set it up yourself. -## Configure the installer as you wish +## Configure the router as you wish You have root. You can configure the router as you wish. The `puomi` Ansible role in the Puomi source tree may be useful, if Ansible is diff --git a/puomi-playbook.yml b/puomi-playbook.yml index 0e9cbc3..73b6c30 100644 --- a/puomi-playbook.yml +++ b/puomi-playbook.yml @@ -74,8 +74,8 @@ vars: ansible_python_interpreter: /usr/bin/python3 - puomi_lan_ip: 10.3.1.1 - puomi_dhcp_start: 10.3.1.10 - puomi_dhcp_end: 10.3.1.250 + puomi_lan_ip: 10.1.1.1 + puomi_dhcp_start: 10.1.1.10 + puomi_dhcp_end: 10.1.1.250 puomi_dhcp_netmask: 255.255.255.0 puomi_dhcp_lease: 1h -- cgit v1.2.1