README rewritten from scratch so a newcomer can follow it (closes #154, closes #155)

The old README opened with project history and one list of a hundred
settings. The new one leads with what smallwebwaf is, what it protects
against, how to build and deploy it, how it sits in front of the app,
what happens to a request, the settings most deployments touch, how to
check it works and how to develop it. The reference material, every
setting, bans, rule files, the Core Rule Set, the admin endpoints, the
request log, alerts, metrics, state files, lookups, reputation sources,
the image and gitea, moves to files under docs/, each linked from the
README. Every statement was checked against the code on next.

Model: fable-5-1

docs/lookup.md

@@ -0,0 +1,79 @@
+# GeoJS and the lookup database
+
+`smallwebwaf` looks up each client's AS number and country, through GeoJS by
+default or in a database file on your own host. The settings are under "Looking
+up the AS number and country" in [`settings.md`](settings.md); the reasons for
+the defaults are under "Lookup of AS number and country" in
+[`SPEC.md`](../SPEC.md).
+
+## GeoJS
+
+By default `smallwebwaf` asks GeoJS, a free web service that needs no account,
+about every new visitor's address. It asks whether or not a setting uses the
+answer, since the log line, the history, the ban notes and the metrics carry the
+AS number and country. These addresses are never sent:
+
+- one in `SWWAF_ALLOW_NETS` or `SWWAF_DENY_NETS`;
+- one under a ban;
+- a private, loopback or link-local address, which no source can place.
+
+For an IPv6 visitor, GeoJS is asked about the first address of its group.
+Addresses are asked about together, up to 200 in one request
+(`https://get.geojs.io/v1/ip/geo.json?ip=a,b,c`), one request at a time. Each
+answer's `country_code`, `asn` and `organization_name` are read. An answer
+without a `country_code`, or with the `asn` `64512`, counts as unknown. Each
+answer is kept for seven days, in memory and in `lookups.json`, separately from
+the table of clients. Up to 100,000 answers are kept; past that, the answer used
+longest ago goes first.
+
+A request waits for its client's first answer only when a setting needs the
+answer before the request goes on. It waits up to `SWWAF_LOOKUP_TIMEOUT`. The
+settings that make it wait:
+
+- a country list;
+- `SWWAF_ADD_LOOKUP_HEADERS`;
+- any setting under "Lower limits by AS number and country" in
+  [`settings.md`](settings.md).
+
+Otherwise the request goes on at once, logged without the answer. The answer
+reaches the client's history and ban notes when it comes. A client whose answer
+has not come in time counts as from an unknown country until it comes, and its
+later requests do not wait. While GeoJS fails, new visitors count as from an
+unknown country, which `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` refuses. GeoJS is
+then left alone for a second, and twice as long after each further failure, up
+to five minutes, and one `source_failure` alert is sent per cooldown.
+
+## The database file
+
+To keep your visitors' addresses on your own host, set
+`SWWAF_LOOKUP_SOURCE=off`, or set it to `file`. `file` looks every client up in
+the free IPinfo Lite database (`ipinfo_lite.mmdb`) at `SWWAF_LOOKUP_DB_PATH`,
+reading its `asn`, `as_name` and `country_code` fields. You download the
+database with an IPinfo account and mount it into the container; `smallwebwaf`
+never fetches it and holds no account or token for it. It answers at once, with
+nothing sent off the host. A client whose address it does not hold counts as
+from an unknown country.
+
+`smallwebwaf` reads the whole file at start. It reads the file again once it has
+gone 2 seconds without a change after you replace it. A replacement it cannot
+read is logged and alerted, and the file read before stays in use. Mount the
+directory that holds the file, not the file itself. Many editors and download
+tools save a file by replacing it, and a container keeps seeing the old file
+when only the file is mounted.
+
+IPinfo updates the database daily, and releases it under the Creative Commons
+Attribution-ShareAlike 4.0 licence. It asks for a link to IPinfo on the site
+that uses it, such as "IP address data is powered by IPinfo".
+
+## A client without a country
+
+A client the lookup cannot place has an unknown country and AS number. That is
+one of:
+
+- a client on a private address;
+- one GeoJS or the database does not know;
+- one whose GeoJS answer has not come in time.
+
+`SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` refuses such a client, and the lower
+limits give it `SWWAF_UNKNOWN_LIMIT_PERCENT`. Nothing else treats it
+differently.