From 5f5d6293ebc3d28d6337ecb184a98d7c7592a4dc Mon Sep 17 00:00:00 2001
From: Fabian Hauser <fabian@fh2.ch>
Date: Tue, 21 Apr 2020 22:12:37 +0200
Subject: [PATCH] Add role documentation

---
 README.adoc               | 21 +++++++++++++++++++++
 role/README.adoc          | 13 +++++++++++++
 role/backup/README.adoc   |  3 +++
 role/base/README.adoc     | 10 ++++++++++
 role/dropbear/README.adoc |  6 ++++++
 role/router/README.adoc   | 10 ++++++++++
 role/wwan/README.adoc     | 11 +++++++++++
 7 files changed, 74 insertions(+)
 create mode 100644 README.adoc
 create mode 100644 role/README.adoc
 create mode 100644 role/backup/README.adoc
 create mode 100644 role/base/README.adoc
 create mode 100644 role/dropbear/README.adoc
 create mode 100644 role/router/README.adoc
 create mode 100644 role/wwan/README.adoc

diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..8110a4a
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,21 @@
+[[qois-infrastructure]]
+qo.is Infrastructure
+--------------------
+
+This repository contains the infrastructure configuration.
+
+Structure
+~~~~~~~~~
+
+`hardware`:: Hardware specific configuration files, e.g. for wireless
+cards.
+`host`:: Main nixos `configuration.nix` for every host. The
+`configuration.nix` is symlinked to the specific host file.
+`role`:: Host roles, which are included from a host's configuration.
+`docs`:: Documentation of the concrete qo.is infrastructure
+
+Development
+~~~~~~~~~~~
+
+* The nix files shoud be formatted using nixfmt:
+** `nixfmt -c $(git ls-files *.nix)`
diff --git a/role/README.adoc b/role/README.adoc
new file mode 100644
index 0000000..e7aba31
--- /dev/null
+++ b/role/README.adoc
@@ -0,0 +1,13 @@
+= Roles
+
+:toc:
+
+include::backup/README.adoc[]
+
+include::base/README.adoc[]
+
+include::dropbear/README.adoc[]
+
+include::router/README.adoc[]
+
+include::wwan/README.adoc[]
diff --git a/role/backup/README.adoc b/role/backup/README.adoc
new file mode 100644
index 0000000..20cbe79
--- /dev/null
+++ b/role/backup/README.adoc
@@ -0,0 +1,3 @@
+== Backup Role
+
+Creates backup to an external mount with borg backup according to a specified schedule.
diff --git a/role/base/README.adoc b/role/base/README.adoc
new file mode 100644
index 0000000..c5df8c7
--- /dev/null
+++ b/role/base/README.adoc
@@ -0,0 +1,10 @@
+== Base Role
+
+The base role handles basic system configuration, which includes:
+
+* User management
+* Nix configuration
+* System default settings
+* Global packages (like `git` and `curl`) and sane configuration
+defaults for them
+* Basic networking configuration (like firewall and ssh)
diff --git a/role/dropbear/README.adoc b/role/dropbear/README.adoc
new file mode 100644
index 0000000..e6667ff
--- /dev/null
+++ b/role/dropbear/README.adoc
@@ -0,0 +1,6 @@
+== Dropbear Role
+
+Configuration of dropbear to allow HDD decryption from a remote host.
+
+Note: This role requires manually creating of persistant SSH-Keys with
+`dropbearkey -t <type> -f <output-keyfile>`
diff --git a/role/router/README.adoc b/role/router/README.adoc
new file mode 100644
index 0000000..ff193d2
--- /dev/null
+++ b/role/router/README.adoc
@@ -0,0 +1,10 @@
+== Router Role
+
+This role is applied on hosts which serve the rule of a SOHO router.
+
+Features:
+
+* NAT and basic Firewalling
+* Recursive DNS with `unbound` (DNSSEC validated)
+* Local DHCP and DNS with `dnsmasq`
+* Wireless with `hostapd`
diff --git a/role/wwan/README.adoc b/role/wwan/README.adoc
new file mode 100644
index 0000000..1d8c9ce
--- /dev/null
+++ b/role/wwan/README.adoc
@@ -0,0 +1,11 @@
+== WWAN Module
+
+This module configures WWAN adapters that support MBIM
+
+=== Current limitations
+
+* IPv4 tested only
+* Currently, it is not simple to get network failures or address updates
+via a hook or so.
+** A systemd timer to update the configuration is executed every 2
+minutes to prevent longer downtimes.