add contrib

contrib/README.md

@@ -0,0 +1,54 @@
+# Various other parts of a captive portal setup
+
+Network (HA) setup with IPv4 NAT:
+- two nodes
+- shared uplink L2, some transfer network (can be private or public)
+  * virtual addresses on active node for IPv4 and IPv6 to route traffic to
+- shared downlink L2
+  * virtual addresses on active node for IPv4 and IPv6 as gateway for clients
+    * using `fe80::1` as gateway, but also add a public IPv6 virtual address
+  * connected: private IPv4 prefix (e.g. CGNAT), not routed
+  * connected: public IPv6 prefix (routed to virtual uplink address of nodes)
+- public IPv4 prefix routed virtual uplink address of nodes to use for NAT
+  * IPv4-traffic from clients will be (S)NATted from this prefix; size depends
+    on number of parallel connections you want to support.
+- webserver on nodes:
+  * port 8080: receives transparent http redirects from the firewall; should return a temporary redirect to your portal page.
+  * port 80: redirect to https
+  * port 443: reverse-proxy to 127.0.0.1:8000 (the webui backend), but serve `/static` directly from directory (see main README)
+
+To access the portal page on the clients you'll need a DNS-name; it should point to the virtual addresses.  In some ways downlink address is preferred, but you also might want to avoid private addresses - i.e. use the uplink IPv4 address and the downlink IPv6 address.
+
+Also the management traffic for the virtual address should use the uplink interface if possible (`keepalived` supports this).
+
+## ISC dhcpd
+
+See `dhcpd.conf.erb` and `dhcpd6.conf.erb`.
+
+Note: don't use too large IPv4 pools or dhcpd will take a long time to sync and build up the leases files.
+
+## Firewall / NAT
+
+See `nftables.conf.erb` for forwarding rules; if you want traffic shaping as well see `shape_non_whitelisted.sh`.
+Local policies (ssh access and normal "host protection") are not included in the example.
+
+You also might want to set a high `net.netfilter.nf_conntrack_max` with sysctl (e.g. `16777216`).
+
+## Conntrackd
+
+Active/failover configuration TBD.
+
+I strongly recommend not to enable any tracking helpers; they often make significant holes into your stateful firewall (i.e. make clients reachable from the outside in ways they didn't actually want).
+
+## Keepalived (for virtual addresses)
+
+See `keepalived.conf.erb`.
+
+## Apache2
+
+See `apache2.conf` (only contains "interesting" parts, probably won't start that way).
+Any other webserver configured in a similar way should do just as well.
+
+## systemd units
+
+See the `systemd` directory for examples of systemd units.