caddy_maxmind_geolocation

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 26, 2026 License: ISC Imports: 17 Imported by: 0

README

caddy-maxmind-geolocation

Caddy v2 module to filter requests based on source IP geographic location. This was a feature provided by the V1 ipfilter middleware.

Installation

You can download a Caddy build with this plugin inside directly from the official Caddy page.

If you prefer, you can build Caddy by yourself by installing xcaddy and running:

xcaddy build --with github.com/DoMaLo/caddy-maxmind-geolocation

Please note that you will probably need Git installed to correctly build Caddy with this module. This is pretty unconvenient on Windows, but installing the package from https://git-scm.com/downloads/win should suffice.

Requirements

To be able to use this module you will need to have a Maxmind GeoLite2 database, that can be downloaded for free by creating an account. More information about this are available on the official website.

You will specifically need the GeoLite2-Country.mmdb file, or the GeoLite2-City.mmdb if you're matching on subdivisions and metro codes.

Alternatively, you can use a database from a GitHub repository (e.g. P3TERX/GeoLite.mmdb) that publishes GeoLite2 files as release assets. The module will download the file on startup and periodically check for updates.

Usage

You can use this module as a matcher to blacklist or whitelist a set of countries, subdivisions or metro codes.

You'll find the detailed explanation of all the fields on the Caddy website's plugin page.

Here are some samples:

Caddyfile
  1. Allow access to the website only from Italy and France:
test.example.org {
  @mygeofilter {
    maxmind_geolocation {
      db_path "/usr/share/GeoIP/GeoLite2-Country.mmdb"
      allow_countries IT FR
    }
  }

   file_server @mygeofilter {
     root /var/www/html
   }
}
  1. Deny access to the website from Russia or from IPs with an unknown country:
test.example.org {
  @mygeofilter {
    maxmind_geolocation {
      db_path "/usr/share/GeoIP/GeoLite2-Country.mmdb"
      deny_countries RU UNK
    }
  }

   file_server @mygeofilter {
     root /var/www/html
   }
}
  1. Allow access from US and CA, but exclude the NY subdivision (note that you'll need the City database here):
test.example.org {
  @mygeofilter {
    maxmind_geolocation {
      db_path "/usr/share/GeoIP/GeoLite2-City.mmdb"
      allow_countries US CA
      deny_subdivisions NY
    }
  }

   file_server @mygeofilter {
     root /var/www/html
   }
}
  1. Allow access from US, but only to TX subdivision excluding the metro code 623 and the not-recognized metro codes:
test.example.org {
  @mygeofilter {
    maxmind_geolocation {
      db_path "/usr/share/GeoIP/GeoLite2-City.mmdb"
      allow_countries US
      allow_subdivisions TX
      deny_metro_codes 623 UNK
    }
  }

   file_server @mygeofilter {
     root /var/www/html
   }
}
  1. Deny access from AS64496 (note that you'll need the ASN database here):
test.example.org {
  @mygeofilter {
    maxmind_geolocation {
      db_path "/usr/share/GeoIP/GeoLite2-ASN.mmdb"
      deny_asn 64496
    }
  }

   file_server @mygeofilter {
     root /var/www/html
   }
}
  1. Use database from GitHub (e.g. P3TERX/GeoLite.mmdb) with automatic updates:
test.example.org {
  @mygeofilter {
    maxmind_geolocation {
      github_repo "P3TERX/GeoLite.mmdb"
      github_asset "GeoLite2-Country.mmdb"
      cache_path "/var/lib/caddy/GeoLite2-Country.mmdb"
      update_interval 24h
      allow_countries IT FR
    }
  }

   file_server @mygeofilter {
     root /var/www/html
   }
}

Optional: set GITHUB_TOKEN env for higher API rate limit. update_interval defaults to 24h.

API/JSON
  1. Allow access to the website only from Italy and France:
{
  "apps": {
    "http": {
      "servers": {
        "myserver": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "test.example.org"
                  ],
		  "maxmind_geolocation": {
                    "db_path": "/usr/share/GeoIP/GeoLite2-Country.mmdb",
                    "allow_countries": [ "IT", "FR" ]
                  }
                }
              ],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "/var/www/html"
                }
              ]
            }
          ]
        }
      }
    }
  }
}
  1. Deny access to the website from Russia or from IPs with an unknown country:
{
  "apps": {
    "http": {
      "servers": {
        "myserver": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "test.example.org"
                  ],
		  "maxmind_geolocation": {
                    "db_path": "/usr/share/GeoIP/GeoLite2-Country.mmdb",
                    "deny_countries": [ "RU", "UNK" ]
                  }
                }
              ],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "/var/www/html"
                }
              ]
            }
          ]
        }
      }
    }
  }
}
  1. Allow access from US and CA, but exclude the NY subdivision (note that you'll need the City database here):
{
  "apps": {
    "http": {
      "servers": {
        "myserver": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "test.example.org"
                  ],
		  "maxmind_geolocation": {
                    "db_path": "/usr/share/GeoIP/GeoLite2-City.mmdb",
                    "allow_countries": [ "US", "CA" ],
                    "deny_subdivisions": [ "NY" ]
                  }
                }
              ],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "/var/www/html"
                }
              ]
            }
          ]
        }
      }
    }
  }
}
  1. Allow access from US, but only to TX subdivision excluding the metro code 623 and the not-recognized metro codes:
{
  "apps": {
    "http": {
      "servers": {
        "myserver": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "test.example.org"
                  ],
		  "maxmind_geolocation": {
                    "db_path": "/usr/share/GeoIP/GeoLite2-City.mmdb",
                    "allow_countries": [ "US" ],
                    "allow_subdivisions": [ "TX" ],
                    "deny_metro_codes": [ "623", "UNK" ]
                  }
                }
              ],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "/var/www/html"
                }
              ]
            }
          ]
        }
      }
    }
  }
}
  1. Deny access from AS64496 (note that you'll need the ASN database here):
{
  "apps": {
    "http": {
      "servers": {
        "myserver": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "test.example.org"
                  ],
          "maxmind_geolocation": {
                    "db_path": "/usr/share/GeoIP/GeoLite2-ASN.mmdb",
                    "deny_asn": [ "64496" ]
                  }
                }
              ],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "/var/www/html"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Documentation

Overview

Caddy v2 module to filter requests based on source IP geographic location. This was a feature provided by the V1 ipfilter middleware. Complete documentation and usage examples are available at https://github.com/DoMaLo/caddy-maxmind-geolocation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Country 

type Country struct {
	GeonameId         int    `maxminddb:"geoname_id"`
	IsInEuropeanUnion bool   `maxminddb:"is_in_european_union"`
	ISOCode           string `maxminddb:"iso_code"`
	Names             Names  `maxminddb:"names"`
}

type Location 

type Location struct {
	MetroCode int `maxminddb:"metro_code"`
}

type MaxmindGeolocation 

type MaxmindGeolocation struct {

	// The path of the MaxMind GeoLite2-Country.mmdb file. Not used when GitHub source is set.
	DbPath string `json:"db_path"`

	// GitHub source: repo in form owner/repo (e.g. P3TERX/GeoLite.mmdb).
	GitHubRepo string `json:"github_repo,omitempty"`
	// GitHub asset name from latest release (e.g. GeoLite2-Country.mmdb).
	GitHubAsset string `json:"github_asset,omitempty"`
	// Local path where the downloaded DB is stored. Required when using GitHub.
	CachePath string `json:"cache_path,omitempty"`
	// Optional token for GitHub API (higher rate limit, private repos).
	GitHubToken string `json:"github_token,omitempty"`
	// How often to check for updates (e.g. 24h). Default 24h.
	UpdateInterval caddy.Duration `json:"update_interval,omitempty"`

	// A list of countries that the filter will allow.
	// If you specify this, you should not specify DenyCountries.
	// If both are specified, DenyCountries will take precedence.
	// All countries that are not in this list will be denied.
	// You can specify the special value "UNK" to match unrecognized countries.
	AllowCountries []string `json:"allow_countries"`

	// A list of countries that the filter will deny.
	// If you specify this, you should not specify AllowCountries.
	// If both are specified, DenyCountries will take precedence.
	// All countries that are not in this list will be allowed.
	// You can specify the special value "UNK" to match unrecognized countries.
	DenyCountries []string `json:"deny_countries"`

	// A list of subdivisions that the filter will allow.
	// If you specify this, you should not specify DenySubdivisions.
	// If both are specified, DenySubdivisions will take precedence.
	// All subdivisions that are not in this list will be denied.
	// You can specify the special value "UNK" to match unrecognized subdivisions.
	AllowSubdivisions []string `json:"allow_subdivisions"`

	// A list of subdivisions that the filter will deny.
	// If you specify this, you should not specify AllowSubdivisions.
	// If both are specified, DenySubdivisions will take precedence.
	// All subdivisions that are not in this list will be allowed.
	// You can specify the special value "UNK" to match unrecognized subdivisions.
	DenySubdivisions []string `json:"deny_subdivisions"`

	// A list of metro codes that the filter will allow.
	// If you specify this, you should not specify DenyMetroCodes.
	// If both are specified, DenyMetroCodes will take precedence.
	// All metro codes that are not in this list will be denied.
	// You can specify the special value "UNK" to match unrecognized metro codes.
	AllowMetroCodes []string `json:"allow_metro_codes"`

	// A list of METRO CODES that the filter will deny.
	// If you specify this, you should not specify AllowMetroCodes.
	// If both are specified, DenyMetroCodes will take precedence.
	// All metro codes that are not in this list will be allowed.
	// You can specify the special value "UNK" to match unrecognized metro codes.
	DenyMetroCodes []string `json:"deny_metro_codes"`

	// A list of ASNs that the filter will allow.
	// If you specify this, you should not specify DenyASN.
	// If both are specified, DenyASN will take precedence.
	// All ASNs that are not in this list will be denied.
	// You can specify the special value "UNK" to match unrecognized ASNs.
	AllowASN []string `json:"allow_asn"`

	// A list of ASNs that the filter will deny.
	// If you specify this, you should not specify AllowASN.
	// If both are specified, DenyASN will take precedence.
	// All ASNs that are not in this list will be allowed.
	// You can specify the special value "UNK" to match unrecognized ASNs.
	DenyASN []string `json:"deny_asn"`
	// contains filtered or unexported fields
}

Allows to filter requests based on source IP country.

func (*MaxmindGeolocation) CaddyModule 

func (*MaxmindGeolocation) CaddyModule() caddy.ModuleInfo

func (*MaxmindGeolocation) Cleanup 

func (m *MaxmindGeolocation) Cleanup() error

func (*MaxmindGeolocation) Match 

func (m *MaxmindGeolocation) Match(r *http.Request) bool

func (*MaxmindGeolocation) Provision 

func (m *MaxmindGeolocation) Provision(ctx caddy.Context) error

func (*MaxmindGeolocation) UnmarshalCaddyfile 

func (m *MaxmindGeolocation) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

The matcher configuration will have a single block with the following parameters:

- `db_path`: path to the GeoLite2-Country.mmdb file (required if not using GitHub)

- `github_repo`: optional, GitHub repo owner/name (e.g. P3TERX/GeoLite.mmdb)

- `github_asset`: optional, asset filename in latest release (e.g. GeoLite2-Country.mmdb)

- `cache_path`: optional, local path to store downloaded DB when using GitHub

- `github_token`: optional, GitHub token for API (env: GITHUB_TOKEN)

- `update_interval`: optional, how often to check for updates (e.g. 24h), default 24h

- `allow_countries`: a space-separated list of allowed countries

- `deny_countries`: a space-separated list of denied countries.

- `allow_subdivisions`: a space-separated list of allowed subdivisions

- `deny_subdivisions`: a space-separated list of denied subdivisions.

- `allow_metro_codes`: a space-separated list of allowed metro codes

- `deny_metro_codes`: a space-separated list of denied metro codes.

- `allow_asn`: a space-separated list of allowed ASNs

- `deny_asn`: a space-separated list of denied ASNs.

You will want specify just one of `allow_***` or `deny_ééé`. If you specify both of them, denied items will take precedence over allowed ones.

Examples are available at https://github.com/DoMaLo/caddy-maxmind-geolocation/

func (*MaxmindGeolocation) Validate 

func (m *MaxmindGeolocation) Validate() error

type Names 

type Names struct {
	De   string `maxminddb:"de"`
	En   string `maxminddb:"en"`
	Es   string `maxminddb:"es"`
	Fr   string `maxminddb:"fr"`
	PtBr string `maxminddb:"pt-BR"`
	Ru   string `maxminddb:"ru"`
	ZhCn string `maxminddb:"zh-CN"`
}

type Record 

type Record struct {
	Country                Country      `maxminddb:"country"`
	Location               Location     `maxminddb:"location"`
	Subdivisions           Subdivisions `maxminddb:"subdivisions"`
	AutonomousSystemNumber int          `maxminddb:"autonomous_system_number"`
}

type Subdivision 

type Subdivision struct {
	ISOCode string `maxminddb:"iso_code"`
}

type Subdivisions 

type Subdivisions []Subdivision

func (Subdivisions) CommaSeparatedISOCodes 

func (s Subdivisions) CommaSeparatedISOCodes() string

func (Subdivisions) GetISOCodes 

func (s Subdivisions) GetISOCodes() []string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.