docs(meta): Explain project premise

README.md

@@ -4,21 +4,68 @@ Update a firewall rule that relies on dynamic DNS names
 
 # What
 
-* This script assumes exclusive ownership of the `firewalld` direct rules file `/etc/firewalld/direct.xml` or whereever configured 
+Script `update-firewall-source.py`, UFS for short, assists `firewalld` in writing `iptables`-compatible rules, the so-called _direct_ rules.
 
-* List of address can be empty, direct file will then be removed
+UFS focuses on environments where the following is true:
-* After every execution script will trigger systemd firewalld service restart
+
-* No subnet, will simply not be validated
+1. You're on a Red Hat Enterprise Linux or a derivative operating system
-* Include example systemd unit file and install instructions 
+2. You want to keep using its default firewall management tool `firewalld`
-* firewall-cmd --check-config
+3. You want to use Docker
-* default location for config file and default name for config file
+4. You want published Docker ports to not be accessible from everywhere
-* we should deduplicate list
+
-* is intended to help with just docker-user
+## Why
-* man page https://ipset.netfilter.org/iptables.man.html we do iptables
+
-* added in order
+By installing a moderately modern version of Docker Engine it will very kindly take control of some aspects of firewall rules. If you don't do anything with what Docker gives you the end result is that all ports you publish via Docker (and by extension `docker compose`) are quite literally published to the entire Internet. All sources addresses can access published ports on your machine which may not necessarily be desired.
-* related, established? needed?
+
-* section names as comments?
+On the one hand Docker expects you to add custom rules for container access to an `iptables` chain called `DOCKER-USER`. On the other hand Docker - more specifically its way to handle rules - does not care for how to limit access to host ports.
-* Comment max 256 chars
+
+UFS handles both container ports and host ports. It largely follows suggestions outlined by [John Michael Carr's August 2017 unrouted.io blog post "Docker meet firewall - finally an answer"](https://unrouted.io/2017/08/15/docker-firewall/).
+
+## How
+
+`update-firewall-source.py` uses a `config.ini` file that may in its simplest form look somewhat like this:
+
+```
+[My home]
+addr = some.dyndns.host.net
+ports = 22, 80, 443
+
+[deny-all]
+target = DROP
+addr =
+ports =
+proto =
+state =
+```
+
+Over in the ['examples' directory](examples) you will find systemd `.service` and `.timer` example files to regularly execute UFS.
+
+Its systemd journal output will look somewhat like this:
+
+```
+systemd[1]:     Starting firewalld direct rules generator...
+python[961809]: Generating rules from section '[My home]' ...
+python[961809]: Verifying address ['some.dyndns.host.net'] ...
+python[961809]: For 'some.dyndns.host.net' found records: ['1.2.3.4', '2606:4700:20::681a:804']
+python[961809]: Adding IPv4 address '1.2.3.4' ...
+python[961809]: For section '[My home]' option 'do_ipv6' equals false. Skipping IPv6 handling of
+python[961809]: 2606:4700:20::681a:804' ...
+python[961809]: Writing new firewalld direct config ...
+python[961809]: Restarting systemd firewalld.service unit ...
+python[961809]: Done
+systemd[1]:     update-firewall-source.service: Succeeded.
+systemd[1]:     Started firewalld direct rules generator.
+```
+
+## Tying it together
+
+A Docker Engine installation nowadays adds the `iptables` chain `DOCKER-USER` which is all well and good. Adding rules to it makes sure that Docker's published ports can only be accessed from where you want.
+
+If you want to cover both Docker containers and the host OS, however, that doesn't fly. UFS adds a chain named `FILTERS`. This chain is called from both `DOCKER-USER` (anything accessing a Docker published port goes this route) **_and_** from the `INPUT` chain (anything headed for the host operating system goes that way).
+
+You only maintain the `FILTERS` chain and don't have to worry about whether an application is unknowingly accessible via public Internet - no matter if that app is a container or a `dnf` package. Even better: UFS does management for you, you just give it a `config.ini` file.
+
+Find more in-depth info on how `ip(6)tables` evolves with UFS down in the ["iptables behind the scenes" section](#iptables-behind-the-scenes).
 
 # Prep
 
@@ -27,6 +74,8 @@ Aside from Python dependencies make sure that your OS has headers and static lib
 dnf -y install dbus-glib-devel dbus-devel
 ```
 
+This script assumes write access to `firewalld` direct rules file `/etc/firewalld/direct.xml` or whereever else you've configured this file to live. Typically that means you're going to want to run UFS as `root`.
+
 # Config structure
 
 Package configuration happens via a `config.ini` file that follows INI-style syntax. Copy [examples/config.ini.example](examples/config.ini.example) to `config.ini` to get started: