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