diff options
author | Lars Wirzenius <liw@liw.fi> | 2022-09-04 15:00:38 +0000 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2022-09-04 15:00:38 +0000 |
commit | 44c9cc66063f2c3db26488908565edace008ed6c (patch) | |
tree | dd673fc4f7947d58beb601a7257eeb2f183303ae | |
parent | 0de09dc6433c17f809acb1b14f8c98345ca584da (diff) | |
parent | 82e9618cae94c87a7f1ccd36fa5ae99499ac7052 (diff) | |
download | puomi-44c9cc66063f2c3db26488908565edace008ed6c.tar.gz |
Merge branch 'installation-doc' into 'main'
docs: add initial installation document
See merge request larswirzenius/puomi!12
-rw-r--r-- | install.md | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/install.md b/install.md new file mode 100644 index 0000000..47b0ca7 --- /dev/null +++ b/install.md @@ -0,0 +1,127 @@ +# Installing Puomi + +Puomi is Internet router software for home and small office use. It +consists of [Debian][] with a custom configuration to enable use of a +PC as a router. + +To use Puomi you need: + +* A PC with at least two Ethernet ports and UEFI. Below, we call it + "the router PC". +* 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. + +To install, short version: + +* Download a [v-i][] installer image. + - v-i is a custom installer for Debian +* Write the image to a USB drive. +* Configure the 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. + +These steps will be covered in more detail below. + +## Get installer image + +* Download the 0.2 release image and helper scripts. + - <https://files.liw.fi/v-i/0.2/v-i.img.xz> + - <https://files.liw.fi/v-i/0.2/write-and-config.sh> + - <https://files.liw.fi/v-i/0.2/configure-installer> +* 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 +~~~ + +* 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 +~~~ + +* Make sure everything is written to the drive, then remove it. + +~~~sh +eject /dev/sdx +~~~ + +* You may want to label the drive so you remember which one is the + installer. + +## Install on your 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". +* 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. + +~~~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 back into the installer, and do the install. Run the following + in the installer: + +~~~sh +./v-i --verbose x220.yaml +~~~ + +* Reboot. + +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. + +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 + +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 +your kind of thing. You can also use any other configuration +management tooling you prefer. + +[Debian]: https://www.debian.org/ +[v-i]: https://v-i.liw.fi/ |