--- title: "Puomi---a simple router" author: The Puomi project template: python bindings: - puomi.yaml - lib/runcmd.yaml functions: - puomi.py - lib/runcmd.py ... # Introduction Puomi is, or will become, 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 is 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. # Overview This chapter is sketches the overall shape of Puomi. * Puomi runs on a PC with at least two Ethernet ports. * Puomi is connected via a specific Ethernet port (named "eth0") to a public Internet connection and to devices on the local network ("the LAN") via other Ethernet ports. * Puomi routes traffic between the local network and the Internet and between devices on the local network. * At this stage, there is no firewall. That will come later. # Testing The functionality of Puomi is verified in an environment consisting of nested virtual machines. The outer VM provides an isolated environment in which three inner VMs work. This isolation is primarily for networking purposes. The inner VMs are: * `puomi`---the router itself * `webby`---represents a web server on the public Internet * `lappy`---represents a host on the local network The outer VM uses [libvirt][] to manage the inner VMs, and the [vmadm][] tool to create VMs. vmadm is used for simplicity, since this is what it was written for. vmadm could be replaced with some shell or Python scripting, but life is too short. The vmadm tool is installed automatically into the outer VM. The outer VM can be created in whatever way is convenient: the acceptance test suite does not create it. [libvirt]: https://libvirt.org/ [vmadm]: https://vmadm.liw.fi/ ~~~pikchr Webby: box "webby" arrow <-> Internet: ellipse "Internet" arrow <-> "wan" aligned Puomi: box "puomi" arrow <-> "lan" aligned Laptop: box "laptop" ~~~ There are two libvirt virtual networks, `wan` and `lan`, configured in the outer VM. `webby` attached to `wan`, `lappy` is attached to `lan`, and `puomi` is attached to both. `webby` can't reach `lappy` directly, or vice versa, unless `puomi` routes the packets for them. The outer VM is further configured so that the inner VMs can't reach the network outside the outer VM. # Acceptance criteria This chapter documents and verifies the detailed acceptance criteria for the Puomi testing environment using [Subplot][] scenarios. It is meant to be used against a previously set up instance of the environment called `puomi-dev`. [Subplot]: https://subplot.liw.fi/ ## Smoke test This scenario verifies that the Puomi testing environment has all three virtual machines, and that it's possible to log into each of them from the test environment. ~~~scenario given a router testing environment when I run ssh -F .ssh/config -v puomi@puomi-dev hostname then stdout is exactly "puomi-dev\n" when I run ssh -F .ssh/config -v puomi hostname then stdout is exactly "puomi\n" when I run ssh -F .ssh/config -v webby hostname then stdout is exactly "webby\n" when I run ssh -F .ssh/config -v lappy hostname then stdout is exactly "lappy\n" ~~~