sneak
d712bb1496
check / check (push) Waiting to run
docs/settings.md is now the one settings reference; the spec keeps the conventions, the off list and each group's requirements and reasons, and links to it for the per-setting entries. The endpoint list, the ban notes, the state file contents, the rule file format and the alert object likewise live in docs/ and are linked from the spec. The package list from the README's Design section joins "Architecture". The nine docs files are byte-identical to those on the README branch. Package comments that named "Alert webhook schema", "Request log" and "Metrics endpoint" for their field lists now name the docs files. Model: fable-5-1
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
# 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.
|