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"
+~~~