.env.example

# =============================================================================
# IPGeolocation.io middleware for Next.js
# Environment variables
#
# Copy the values you need into .env.local for local development, and into
# Project Settings > Environment Variables on Vercel for deployments.
#
# Get an API key at https://app.ipgeolocation.io/signup
# =============================================================================

# -----------------------------------------------------------------------------
# Required
# -----------------------------------------------------------------------------

# Your IPGeolocation.io API key. Without it the middleware does nothing.
IPGEOLOCATION_API_KEY=

# -----------------------------------------------------------------------------
# Country controls
# -----------------------------------------------------------------------------

# Allow list. Only these countries can reach the app, everyone else is blocked.
# Leave empty to allow every country.
# Format: comma separated ISO 3166-1 alpha-2 codes, case insensitive.
# Example: US,CA,GB,AU
IPGEO_ALLOWED_COUNTRIES=

# Block list. These countries are always blocked.
# Example: CN,RU,KP
IPGEO_BLOCKED_COUNTRIES=

# When an allow list is set and the country cannot be determined, the request is
# blocked. Set this to true to let unknown countries through instead.
IPGEO_ALLOW_UNKNOWN_COUNTRY=false

# Country to path redirects, as a JSON object.
# Example: {"US":"/us","GB":"/uk","DE":"/de"}
IPGEO_COUNTRY_REDIRECTS={}

# Keep the requested path and query string when redirecting, so that
# /pricing?ref=ad becomes /uk/pricing?ref=ad.
IPGEO_REDIRECT_PRESERVE_PATH=true

# Leave visitors alone when they are already on one of the mapped paths, so a
# German visitor who opens /uk on purpose stays there.
IPGEO_REDIRECT_RESPECT_EXISTING=true

# HTTP status for country redirects. One of 301, 302, 307 or 308.
IPGEO_REDIRECT_STATUS=307

# Name of a cookie that switches country redirects off for that visitor. Set the
# cookie from a "stay on this site" link. Leave empty to disable the feature.
IPGEO_REDIRECT_SKIP_COOKIE=

# -----------------------------------------------------------------------------
# Security controls
#
# Every variable in this block needs the security module, which is available on
# paid plans. A lookup with security costs 3 credits instead of 1. When all of
# them are false and no threat score threshold is set, the middleware does not
# request the security module at all and each lookup costs 1 credit.
# -----------------------------------------------------------------------------

# Block VPN exit nodes.
IPGEO_BLOCK_VPN=false

# Block datacenter and anonymous proxies.
IPGEO_BLOCK_PROXY=false

# Block residential proxy networks.
IPGEO_BLOCK_RESIDENTIAL_PROXY=false

# Block Tor exit nodes.
IPGEO_BLOCK_TOR=false

# Block relay networks such as iCloud Private Relay.
# Be careful: this affects a large number of ordinary Apple users.
IPGEO_BLOCK_RELAY=false

# Block cloud and hosting ranges such as AWS, GCP and Azure.
IPGEO_BLOCK_CLOUD_PROVIDER=false

# Block IPs with bot activity.
IPGEO_BLOCK_BOT=false

# Keep bots the API marks as known good, such as search engine crawlers, even
# when IPGEO_BLOCK_BOT is on. Turning this off can remove your site from search
# results, so leave it on unless you know you need the opposite.
IPGEO_ALLOW_KNOWN_GOOD_BOTS=true

# Block IPs flagged as spam sources.
IPGEO_BLOCK_SPAM=false

# Block IPs with a known attack history.
IPGEO_BLOCK_KNOWN_ATTACKER=false

# Block any IP the API marks as anonymous, which covers VPN, proxy, Tor and
# relay in one flag.
IPGEO_BLOCK_ANONYMOUS=false

# Block at or above this threat score, from 0 to 100. Leave empty to disable.
# A useful starting point is 75.
IPGEO_THREAT_SCORE_BLOCK_THRESHOLD=

# Block the request when a security rule is active but the API returned no
# security data, which happens on a free plan. The default is to let the request
# through and log the problem.
IPGEO_REQUIRE_SECURITY=false

# -----------------------------------------------------------------------------
# Blocking behaviour
# -----------------------------------------------------------------------------

# How to handle a blocked request.
#   redirect  send the visitor to IPGEO_BLOCK_PATH (default)
#   rewrite   render IPGEO_BLOCK_PATH at the original URL
#   deny      answer immediately with IPGEO_BLOCK_STATUS and IPGEO_BLOCK_MESSAGE
IPGEO_BLOCK_MODE=redirect

# The page used by redirect and rewrite mode.
IPGEO_BLOCK_PATH=/blocked

# Status and body used by deny mode.
IPGEO_BLOCK_STATUS=403
IPGEO_BLOCK_MESSAGE=Access to this site is restricted.

# Add ?reason=... to the block URL. The reason is always sent as the
# x-ipgeo-block-reason response header.
IPGEO_BLOCK_INCLUDE_REASON=true

# Block traffic when a lookup fails, instead of letting it through.
# false keeps the site available during an API incident, which is the default.
IPGEO_FAIL_CLOSED=false

# -----------------------------------------------------------------------------
# Bypasses
# -----------------------------------------------------------------------------

# Turn the middleware off without removing it from the project.
IPGEO_ENABLED=true

# Paths that skip every check. Useful for health checks and inbound webhooks.
# Example: /health,/api/webhooks
IPGEO_BYPASS_PATHS=

# IP addresses that skip every check, comma separated.
# Example: 203.0.113.10,198.51.100.4
IPGEO_BYPASS_IPS=

# A shared secret. A request carrying x-ipgeo-bypass-token with this value skips
# every check, which lets an uptime monitor through. Leave empty to disable.
IPGEO_BYPASS_TOKEN=

# -----------------------------------------------------------------------------
# Headers
# -----------------------------------------------------------------------------

# Prefix for the geo headers the middleware adds to the request.
# Inbound headers that use this prefix are always removed first, so a visitor
# cannot forge them.
IPGEO_HEADER_PREFIX=x-ipgeo

# Also copy the geo headers onto the response. Off by default, because the
# values describe the visitor and should not be cached by a shared cache.
IPGEO_SET_RESPONSE_HEADERS=false

# -----------------------------------------------------------------------------
# Network behaviour
# -----------------------------------------------------------------------------

# API timeout per attempt, in milliseconds.
IPGEO_TIMEOUT_MS=3000

# Retries for a timeout, a network error or a 5xx response. 0 to 3.
IPGEO_RETRIES=1

# In memory cache lifetime in milliseconds. 0 disables caching.
IPGEO_CACHE_TTL_MS=60000

# Largest number of cached IPs per edge isolate. 0 disables caching.
IPGEO_CACHE_MAX_ENTRIES=1000

# Pause lookups after this many consecutive failures. 0 disables the breaker.
IPGEO_CIRCUIT_FAILURE_THRESHOLD=5

# How long the pause lasts, in milliseconds.
IPGEO_CIRCUIT_COOLDOWN_MS=30000

# Restrict the API response to these fields to shrink the payload.
# Leave empty for the full response.
# Example: location,asn,time_zone,security
IPGEO_FIELDS=

# -----------------------------------------------------------------------------
# Client IP resolution
# -----------------------------------------------------------------------------

# Read the leftmost entry of x-forwarded-for instead of the rightmost.
# Leave this off on Vercel.
IPGEO_TRUST_FIRST_XFF=false

# Number of proxies you operate in front of the app. The client IP is read that
# many positions to the left of the rightmost entry.
IPGEO_TRUSTED_PROXY_COUNT=0

# -----------------------------------------------------------------------------
# Logging
# -----------------------------------------------------------------------------

# One of silent, error, warn, info or debug. Use debug while setting things up,
# then go back to warn.
IPGEO_LOG_LEVEL=warn