NAME
Mojolicious::Plugin::ClientIP::Pluggable - Customizable client IP detection plugin for Mojolicious
SYNOPSIS
use Mojolicious::Lite;
# CloudFlare-waware settings
plugin 'ClientIP::Pluggable',
analyze_headers => [qw/cf-pseudo-ipv4 cf-connecting-ip true-client-ip/],
restrict_family => 'ipv4',
fallbacks => [qw/rfc-7239 x-forwarded-for remote_address/];
get '/' => sub {
my $c = shift;
$c->render(text => $c->client_ip);
};
app->start;DESCRIPTION
Mojolicious::Plugin::ClientIP::Pluggable is a Mojolicious plugin to get an IP address, which allows to specify different HTTP-headers (and their priorities) for client IP address extraction. This is needed as different cloud providers set different headers to disclose real IP address.
If the address cannot be extracted from headers different fallback options are available: detect IP address from X-Forwarded-For header, detect IP address from forwarded header (rfc-7239), or use remote_address environment.
The plugin is inspired by Mojolicious::Plugin::ClientIP.
METHODS
client_ip
Find a client IP address from the specified headers, with optional fallbacks. The address is validated that it is publicly available (aka routable) IP address. Empty string is returned if no valid address can be found.
OPTIONS
analyzed_headers
Define order and names of cloud provider injected headers with client IP address. For cloudflare we found the following headers are suitable:
plugin 'ClientIP::Pluggable',
analyzed_headers => [qw/cf-pseudo-ipv4 cf-connecting-ip true-client-ip/].This option is mandatory.
More details at https://support.cloudflare.com/hc/en-us/articles/202494830-Pseudo-IPv4-Supporting-IPv6-addresses-in-legacy-IPv4-applications, https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-CloudFlare-handle-HTTP-Request-headers, https://support.cloudflare.com/hc/en-us/articles/206776727-What-is-True-Client-IP
restrict_family
plugin 'ClientIP::Pluggable', restrict_family => 'ipv4';
plugin 'ClientIP::Pluggable', restrict_family => 'ipv6';If defined only IPv4 or IPv6 addresses are considered valid among the possible addresses.
By default this option is not defined, allowing IPv4 and IPv6 addresses.
fallbacks
plugin 'ClientIP::Pluggable',
fallbacks => [qw/rfc-7239 x-forwarded-for remote_address/]);Try to get valid client IP-address from fallback sources, if we fail to do that from cloud-provider headers.
rfc-7239 uses forwarded header, x-forwarded-for use <x-forwarded-for> header (appeared before rfc-7239 and still widely used) or use remote_address environment ($c-tx->remote_address>).
Default value is [remote_address].
ENVIRONMENT
CLIENTIP_PLUGGABLE_ALLOW_LOOPBACK
Allows non-routable loopback address (127.0.0.1) to pass validation. Use it for test purposes.
Default value is 0, i.e. loopback addresses do not pass IP-address validation.
COPYRIGHT AND LICENSE
Copyright (C) 2017 binary.com