# 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-Ethernet adapter is fine for the second port
* 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:

* 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.
* Copy the Puomi specification file and playbook to USB drive.
* Boot your router PC from the USB drive.
* Install Puomi on the PC.
* Boot the PC.

These steps will be covered in more detail below.

## Get installer image

* Download the latest release image and helper scripts, using any
  download tool you like.
  - <https://files.liw.fi/v-i/>

* Decompress the image.

  - `unxz v-i.img.xz`

* 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
    sudo bash write-and-config.sh your.yaml /dev/sdx v-i.img
    ~~~

* 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
    ~~~

  The `user_pub` variable will be put into the `root` user's
  `authorized_keys` file. This will allow you to maintain the
  installed Puomi router from another machine using Ansible.

* Copy the spec file and the Puomi initial playbook to the installer
  drive, to `root` user home directory.

    ~~~sh
    sudo mount /dev/sdx2 /mnt
    sudo cp x220.yaml puomi-playbook.yml /mnt/root/
    sudo umount /mnt
    ~~~

* Make sure everything is written to the drive, then remove it.

    ~~~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 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 known to Linux as `eth0`
  - you may have to boot into the installer and experiment to find out
    which one it is

* 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.

* 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.

    ~~~sh
    v-i --verbose x220.yaml
    ~~~

  This may take several minutes.

* 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. 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 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
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/