caddygeofence

README

caddy-geofence

A caddy module for IP geofencing your caddy web server using https://ipbase.com/

• caddy-geofence
  • Usage
    • Build with caddy
    • Docker
  • Caddyfile example
  • Development
    • Run
    • Build

Usage

1. For an IP that is not within the geofence, 403 will be returned on the matching route.
2. An API token from ipbase.com is required to run this module.

Caching

This module by default will use a configurable in-memory cache, should you need an external/persistent cache, the module supports redis. See the caddyfile exmaple below for how to enable.

Free tier includes 150 requests per month

Build with caddy

# build module with caddy
xcaddy build --with github.com/circa10a/caddy-geofence

Docker

docker run --net host -v /your/Caddyfile:/etc/caddy/Caddyfile -e IPBASE_API_TOKEN -p 80:80 -p 443:443 circa10a/caddy-geofence

Caddyfile example

{
	debug
	order geofence before respond
}

:80

route /* {
	geofence {
		# cache_ttl is the duration to store ip addresses and if they are within proximity or not to increase performance
		# Cache for 7 days, valid time units are "ms", "s", "m", "h"
		# Not specifying a TTL sets no expiration on cached items and will live until restart
		cache_ttl 168h

		# ipbase.com API token, this example reads from an environment variable
		ipbase_api_token {$IPBASE_API_TOKEN}

		# radius is the distance of the geofence in kilometers
		# If not supplied, will default to 0.0 kilometers
		# 1.0 => 1.0 kilometers
		radius 1.0

		# allow_private_ip_addresses is a boolean for whether or not to allow private ip ranges
		# such as 192.X, 172.X, 10.X, [::1] (localhost)
		# false by default
		# Some cellular networks doing NATing with 172.X addresses, in which case, you may not want to allow
		allow_private_ip_addresses true

		# allowlist is a list of IP addresses that will not be checked for proximity and will be allowed to access the server
		allowlist 206.189.205.251 206.189.205.252

		# status_code is the HTTP response code that is returned if IP address is not within proximity. Default is 403
		status_code 403

		# redis_enabled disables the in-memory cache and will connect to a remote redis instance
		# default is false
		redis_enabled true
		# the <host>:<port> of the remote redis instance
		# default is localhost:6379
		redis_addr redis:6379
		# redis_username is the username to connect to a secured redis instance
		# default is ""
		redis_username user
		# redis_password is the password to connect to a secured redis instance
		# default is ""
		redis_password password
		# redis_db is the id of the redis db to connect to to store cache ip addresses
		# default is 0
		redis_db 0
	}
}

log {
	output stdout
}

Development

Requires xcaddy to be installed

Run

export IPBASE_API_TOKEN=<token>
make run

Build

make build

Run redis enabled stack

export IPBASE_API_TOKEN=<token>
make redis

Documentation

Index

• type CaddyGeofence
  • func (CaddyGeofence) CaddyModule() caddy.ModuleInfo
  • func (cg *CaddyGeofence) Provision(ctx caddy.Context) error
  • func (cg CaddyGeofence) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (cg *CaddyGeofence) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (cg CaddyGeofence) Validate() error

Types

type CaddyGeofence

type CaddyGeofence struct {

	// ipbase_api_token is REQUIRED and is an API token ipbase.com.
	// Free tier includes 150 requests per month.
	IPBaseAPIToken string `json:"ipbase_api_token,omitempty"`
	// remote_ip is the IP address to geofence against.
	// Not specifying this field results in geofencing the public address of the machine caddy is running on.
	RemoteIP string `json:"remote_ip,omitempty"`
	// allowlist is a list of IP addresses that will not be checked for proximity and will be allowed to access the server.
	Allowlist []string `json:"allowlist,omitempty"`
	// status_code is the HTTP response code that is returned if IP address is not within proximity. Default is 403.
	StatusCode int `json:"status_code,omitempty"`
	// cache_ttl is string parameter for caching ip addresses with their allowed/not allowed state.
	// Not specifying a TTL sets no expiration on cached items and will live until restart.
	// Valid time units are "ms", "s", "m", "h".
	// In-memory cache is used if redis is not enabled.
	CacheTTL time.Duration `json:"cache_ttl,omitempty"`
	// radius is the distance of the geofence in kilometers.
	// If not supplied, will default to 0.0 kilometers.
	// 1.0 => 1.0 kilometers.
	Radius float64 `json:"radius"`
	// allow_private_ip_addresses is a boolean for whether or not to allow private ip ranges
	// such as 192.X, 172.X, 10.X, [::1] (localhost). Default is false.
	// Some cellular networks doing NATing with 172.X addresses, in which case, you may not want to allow.
	AllowPrivateIPAddresses bool `json:"allow_private_ip_addresses"`
	// redis_enabled uses redis for caching. Default is false.
	RedisEnabled bool `json:"redis_enabled,omitempty"`
	// redis_username is the username to connect to a redis instance. Default is "".
	RedisUsername string `json:"redis_username,omitempty"`
	// redis_password is the password to connect to a redis instance. Default is "".
	RedisPassword string `json:"redis_password,omitempty"`
	// redis_addr is the address to connect to a redis instance. Default is localhost:6379.
	RedisAddr string `json:"redis_addr,omitempty"`
	// redis_db is the db id. Default is 0.
	RedisDB int `json:"redis_db,omitempty"`
	// contains filtered or unexported fields
}

CaddyGeofence implements IP geofencing functionality. https://github.com/circa10a/caddy-geofence

func (CaddyGeofence) CaddyModule

func (CaddyGeofence) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CaddyGeofence) Provision

func (cg *CaddyGeofence) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (CaddyGeofence) ServeHTTP

func (cg CaddyGeofence) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*CaddyGeofence) UnmarshalCaddyfile

func (cg *CaddyGeofence) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (CaddyGeofence) Validate

func (cg CaddyGeofence) Validate() error

Validate validates that the module has a usable config.