IP2Proxy Caddy Middleware enriches incoming requests with proxy and network intelligence through HTTP headers. It looks up the visitor's IP address using either a local IP2Proxy BIN database or the IP2Location.io API, then makes the results available to downstream applications such as PHP.
- Two lookup modes: local BIN database or remote IP2Location.io API.
- 15 request headers covering proxy detection, network ownership, location and risk indicators.
- Configurable header prefix (default:
X-IP2Proxy). - Caddyfile integration for applications served through Caddy.
- IPv4 and IPv6 lookups, subject to data availability in the selected database or API plan.
Client request → Caddy (ip2proxy middleware) → IP lookup
├─ Local IP2Proxy BIN
└─ IP2Location.io API
→ Add X-IP2Proxy-* request headers → Application (e.g. PHP)
The middleware enriches requests, not HTTP responses. Your downstream application reads the injected request headers. If a lookup returns an error, the middleware continues to the next handler without applying new lookup headers.
- Go and xcaddy to build Caddy with this third-party module. The current
go.moddeclares Go 1.25.1. - Local mode: An IP2Proxy
.BINdatabase. Download a free LITE database from IP2Location LITE, or use a compatible licensed BIN file. - Remote mode: An IP2Location.io API key with access to the fields you need.
Build Caddy with the middleware:
xcaddy build --with github.com/ip2location/ip2proxy-caddyThe resulting caddy executable includes the ip2proxy directive. Use this custom binary rather than a standard Caddy binary that does not contain the module.
Choose one of the following Caddyfile configurations. Both examples use PHP-FPM; adjust the domain, document root and PHP-FPM socket for your environment.
Extract a compatible BIN file on the Caddy host and set its absolute path:
{
order ip2proxy before php_fastcgi
}
example.com {
root * /var/www/html
ip2proxy {
mode local
bin_path /path/to/IP2PROXY.BIN
header_prefix X-IP2Proxy
}
php_fastcgi unix//run/php/php8.4-fpm.sock
file_server
}Local mode performs the lookup against the BIN database without calling the remote API for each request. The database file must be readable by the Caddy process.
Set the API key in the Caddy process environment, then configure:
{
order ip2proxy before php_fastcgi
}
example.com {
root * /var/www/html
ip2proxy {
mode remote
api_key {$IP2LOCATION_API_KEY}
header_prefix X-IP2Proxy
}
php_fastcgi unix//run/php/php8.4-fpm.sock
file_server
}Remote mode makes IP2Location.io API lookups. Field availability and query limits depend on your subscription. Avoid committing API keys directly to your Caddyfile.
| Option | Description | Default |
|---|---|---|
mode |
local for BIN lookup or remote for API lookup |
local |
bin_path |
Path to the IP2Proxy BIN file; required in local mode | None |
api_key |
IP2Location.io API key; required in remote mode | None |
header_prefix |
Prefix for generated request headers | X-IP2Proxy |
Start Caddy with the configuration file:
./caddy run --config /path/to/Caddyfile --adapter caddyfileTo check Caddyfile syntax before running:
./caddy validate --config /path/to/Caddyfile --adapter caddyfileSave this example as index.php in the configured website directory and open it in your browser. It displays any IP2Proxy headers received by PHP:
<?php
$fields = [
'IS_PROXY',
'PROXY_TYPE',
'COUNTRY_CODE',
'COUNTRY_NAME',
'REGION',
'CITY',
'ISP',
'DOMAIN',
'USAGE_TYPE',
'ASN',
'AS',
'LAST_SEEN',
'THREAT',
'PROVIDER',
'FRAUD_SCORE',
];
header('Content-Type: text/plain; charset=utf-8');
foreach ($fields as $field) {
$key = 'HTTP_X_IP2PROXY_' . $field;
if (isset($_SERVER[$key])) {
echo $key . ': ' . $_SERVER[$key] . "\n";
}
}The example assumes the default X-IP2Proxy prefix. If you change header_prefix, update the PHP variable names accordingly. Values will depend on the IP address, BIN database fields or API subscription.
The middleware defines the following 15 request headers in both lookup modes. Each uses the default X-IP2Proxy prefix.
| Header | What it represents |
|---|---|
X-IP2Proxy-Is-Proxy |
General proxy indicator (True or False) |
X-IP2Proxy-Proxy-Type |
Proxy or network classification |
X-IP2Proxy-Country-Code |
Two-letter country code |
X-IP2Proxy-Country-Name |
Country name |
X-IP2Proxy-Region |
Region or state |
X-IP2Proxy-City |
City |
X-IP2Proxy-ISP |
Internet service provider |
X-IP2Proxy-Domain |
Associated domain |
X-IP2Proxy-Usage-Type |
Network usage classification |
X-IP2Proxy-ASN |
Autonomous System Number |
X-IP2Proxy-AS |
Autonomous system name |
X-IP2Proxy-Last-Seen |
Last-seen indicator for proxy-related activity |
X-IP2Proxy-Threat |
Threat classification |
X-IP2Proxy-Provider |
Proxy provider information |
X-IP2Proxy-Fraud-Score |
IP fraud risk score |
Note: The code sets these headers on successful lookups, but meaningful field values depend on the selected BIN product or API subscription. The local Is-Proxy decision uses the library's classification logic, so do not treat it as interchangeable with every proxy type or as definitive proof of malicious activity.
An Autonomous System Number (ASN) identifies a network operated under a common routing policy. The middleware exposes X-IP2Proxy-ASN and X-IP2Proxy-AS, helping applications understand which network is associated with a visitor's IP address.
ASN data can support network troubleshooting, traffic grouping, hosting-provider identification and security investigations. For offline IP intelligence resources, visit IP2Location LITE.
| Issue | Suggested check |
|---|---|
unrecognized directive: ip2proxy |
Use the Caddy binary built with xcaddy --with github.com/ip2location/ip2proxy-caddy. |
bin_path is required when mode is local |
Set bin_path to a readable BIN file. |
| BIN file cannot be opened | Verify the path, filesystem permissions and database format. |
api_key is required when mode is remote |
Make sure IP2LOCATION_API_KEY is available to the Caddy process. |
| Headers do not appear in PHP | Verify middleware ordering, the request path, PHP-FPM configuration and whether the lookup succeeds. |
| Some header values are missing or not useful | Verify that your BIN database or API subscription contains the corresponding fields. |
| Client IP appears incorrect | Check the proxy forwarding headers received by Caddy. |
- Trust the client IP carefully. The current implementation checks
CF-Connecting-IP,X-Real-IP,X-Forwarded-For, andForwardedbefore the connection IP. Restrict and sanitize forwarding headers at your trusted proxy; otherwise clients may spoof them. - Protect credentials. Keep the API key in your deployment environment or secret manager, not in committed Caddyfiles.
- Use signals as context. Proxy classifications, fraud scores and geolocation are risk indicators, not definitive evidence of fraud or a user's precise physical location.
- Handle failed lookups explicitly. A failed lookup does not block the request in the current implementation. Do not assume missing or previously supplied headers establish a clean result.
| Product | Purpose |
|---|---|
| IP2Location.io | Hosted IP geolocation, ASN, and network intelligence APIs. |
| IP2Location LITE | Free downloadable IP geolocation and ASN databases for offline use. |
| IP2Location Database | Commercial offline IP geolocation databases. |
| IP2Proxy | IP proxy, VPN, TOR and anonymizer intelligence. |
| IP2WHOIS | Domain WHOIS lookup services. |