From f7fd33c5bd63fa90a7e8be541d9a10a9369e714f Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Thu, 13 Jan 2022 14:53:13 +0200 Subject: docs: rewrite README Sponsored-by: author --- README.md | 73 +++++++++++++++------------------------------------------------ 1 file changed, 17 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index b734faa..1890c12 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,28 @@ -# README for Puomi +# Puomi, a Debian based home or small office Internet router -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 is a way to install Debian on a computer and configure it to be +an Internet router for home or small office use. A Puomi router +provides: -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. +* routing between an internal and external network +* IPv4 NAT +* DNS to the local network +* DHCP to the local network, with hosts added to local DNS -## To build and test +Puomi is a very basic Debian system, without any user interface. It is +installed onto a PC using the [v-i][] installer for Debian, and +post-installation configuration and administration is expected to be +done using SSH and Ansible. -Create a VM, accessible with the name `puomi-dev`, then run this to -provision and verify it works: +## Installation -~~~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 +This is not yet documented. ## Hardware -We will be aiming Puomi at hardware like the following: - -- - A small headless PC with multiple Ethernet ports. - -- - A headless Arm64 box with many networking options. - +Puomi currently targets a Lenovo Thinkpad X220 laptop with a USB +Ethernet adapter installed. We expect that any reasonably standard PC +will work. ## Related links -- cgit v1.2.1