Configuration¶

banip reads user-managed settings from ~/.banip/banip.yaml. version, countries, allowlist, and denylist are validated when banip loads the configuration. Country codes must appear in the country-code reference. The bots and database sections have defaults when they are omitted.

# Config schema version. Required.
version: 4
# Named country policies used to generate country allowlists.
countries:
  policies:
    restricted:
      mode: allowlist
      codes:
        - CA
        - US
    public:
      mode: blocklist
      codes:
        - CN
        - RU
# Addresses or networks that should never be blocked.
allowlist: []
# User-managed addresses or networks to add to the blocklist.
denylist: []
# Managed bot and crawler range settings.
bots:
  enabled: true
  providers:
    - google
    - bing
    - openai
    - anthropic
    - amazon
    - meta
# External database update settings.
database:
  maxmind_edition: GeoLite2-Country-CSV
  secrets_file: ~/.secrets

This is the starter configuration written by banip database init. Review both example policies and select the country codes appropriate for each consumer before building.

Country policies¶

countries.policies contains one or more named policies. Policy names start with a lowercase letter and may also contain lowercase letters, digits, underscores, and hyphens.

An allowlist policy permits only its configured country codes. A blocklist policy permits every country label in the current GeoLite2 data except its configured codes. An empty blocklist permits every GeoLite2 country label; an allowlist must contain at least one code. See Country codes for the complete GeoNames-derived reference.

Each build writes a positive country allowlist for every policy:

~/.banip/country_allowlist_restricted.txt
~/.banip/country_allowlist_public.txt

These products always contain permitted codes, regardless of the configured policy mode. This gives proxies and firewalls one consistent membership check. A build removes a named policy file when its policy no longer exists in banip.yaml.

The rendered IP blocklist includes qualifying threat addresses from the union of countries permitted by all policies. A shared blocklist can therefore protect services using different country policies. Threat addresses are included only when their GeoLite-derived label is permitted by at least one policy. GeoLite may provide a continent code when no country code is available.

Country geolocation is approximate. Use country policies as a supplemental control rather than as authentication or authorization.

Allowlists and denylists¶

allowlist contains addresses or CIDR networks that must never be blocked. It has final precedence over the ipsum feed, the denylist, and managed bot ranges. When an allowlisted address or network overlaps a blocked network, banip splits the blocked network to preserve the allowlisted space.

denylist contains user-managed addresses or CIDR networks to add to the rendered blocklist. These entries are not limited by country policies. A build reads but does not rewrite the denylist. Managed bot ranges are stored separately in botdata.json rather than in denylist.

Managed bots¶

bots.enabled controls whether builds include stored managed bot ranges and defaults to true. bots.providers selects from google, bing, openai, anthropic, amazon, and meta; all six are enabled by default. The amazon provider combines Amazonbot, Amzn-SearchBot, and Amzn-User ranges. See Managed bot ranges for refresh and inspection commands. Unknown and duplicate provider names are rejected.

Automatic configuration upgrade¶

When banip reads a version-1, version-2, or version-3 configuration, it automatically writes schema version 4. Existing targets become the codes in a restricted allowlist policy, preserving the previous country filter and threat-selection behavior. Version-1 list keys are also renamed to their current forms, and version-3 countries.default_policy is removed. The complete converted configuration is validated before banip atomically replaces the prior file, so a failed upgrade leaves the original unchanged.

Do not mix keys from different schema versions in one file. banip reports the ambiguity instead of choosing a precedence.

Database settings¶

database.maxmind_edition is passed to MaxMind's download endpoint. The downloaded archive must contain the standard GeoLite2 Country IPv4, IPv6, and English-language locations CSV filenames, so the default GeoLite2-Country-CSV should normally remain unchanged. database.secrets_file identifies an optional dotenv-style credential file and defaults to ~/.secrets. Set it to null to disable credential-file loading and use environment variables only.

The ipsum download URL can be overridden for mirrors or compatible feeds:

database:
  sources:
    ipsum:
      url: https://example.com/ipsum.txt

GeoLite downloads always use MaxMind's authenticated download endpoint and the configured database.maxmind_edition. Unknown configuration keys and invalid database setting types are rejected rather than silently replaced with defaults.