# README for Puomi

Puomi will be software for a simple Internet router and access point
for home and small office use. A device running Puomi connects one or
more machines via Ethernet and wifi to the Internet, while providing a
firewall against outside intrusions.

Puomi will be based on the Debian GNU/Linux operating system. It needs
to be run on a small PC or other suitable hardware. Puomi will have no
interactive user interface, and will be managed entirely via Ansible.

## To build and test

Create a VM, accessible with the name `puomi-dev`, then run this to
provision and verify it works:

~~~sh
(cd env && ./setup.sh)
./check
~~~

You need [Subplot](https://subplot.liw.fi/) installed for `./check`.

If you use [vmadm](https://vmadm.liw.fi/ to create the outer VM:

~~~sh
(cd env && vmadm delete env.yaml && vmadm new env.yaml && ./setup.sh) && ./check
~~~

This will all take a while. On my laptop, it takes order of 10 to 15
minutes. Changes making this faster would be welcome.

## Walk through

Some of the more important files in the source tree:

* `env/` --- directory with Ansible, vmadm, and other files to set up
  a virtual testing environment.
  * `env/env.yaml` --- vmadm specification file for creating the outer
    VM
  * `env/playbook.yml` --- Ansible playbook for provisioning the outer
    VM
  * `env/setup.sh` --- shell script to provision the outer VM and
    creating and provisioning the inner VMs
  * `env/ssh` --- SSH keys and configuration for accessing the outer
    VM, used by the acceptance test suite
* `check` --- script that runs the acceptance tests
* `puomi.md` --- Markdown file that describes Puomi, the test
  environment, and how the environment is verified as working
* `puomi.yaml` and `puomi.py` --- implementations of the scenario
  steps used in the acceptance test in `puomi.md`
* `test.log` --- log file from test program; created by `check`;
  looking at the log may help debug any issues

## Hardware

We will be aiming Puomi at hardware like the following:

- <https://www.qotom.net/product/35.html>  
  A small headless PC with multiple Ethernet ports.

- <https://www.crowdsupply.com/traverse-technologies/ten64>  
  A headless Arm64 box with many networking options.


## Related links

- <https://routersecurity.org/consumerrouters.php>  
  Criticisms of consumer routers.

- <https://www.fkie.fraunhofer.de/content/dam/fkie/de/documents/HomeRouter/HomeRouterSecurity_2020_Bericht.pdf>  
  Home Router Security Report 2020, by Frauhofer FKIE