diff options
author | Lars Wirzenius <liw@liw.fi> | 2021-07-24 10:14:49 +0300 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2021-07-27 15:54:40 +0300 |
commit | 91a5fef528e998939860f5bff93f18d4723bbdfd (patch) | |
tree | bfa88ff7aba022bf09ce4cae333fa36e7ba5e9ae /puomi.md | |
parent | 56671321dbd662fa3f2babdfdbf59f3287f5533b (diff) | |
download | puomi-91a5fef528e998939860f5bff93f18d4723bbdfd.tar.gz |
feat: add scripts + infra for setting up nested VMs for routers
Run ./check to run the acceptance tests with Subplot. This should
work, for minimal amounts of work.
Sponsored-by: author
Diffstat (limited to 'puomi.md')
-rw-r--r-- | puomi.md | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/puomi.md b/puomi.md new file mode 100644 index 0000000..f710792 --- /dev/null +++ b/puomi.md @@ -0,0 +1,98 @@ +--- +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 `puomienv`. + +[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@puomienv hostname +then stdout is exactly "puomienv\n" +~~~ |