mod_remoteip - Apache HTTP Server Version 2.4









Modules | Directives | FAQ | Glossary | Sitemap
Apache HTTP Server Version 2.4



Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_remoteip

Available Languages:  en  |
 fr 

Description:Replaces the original client IP address for the connection
with the useragent IP address list presented by a proxies or a load balancer
via the request headers.

Status:Base
Module Identifier:remoteip_module
Source File:mod_remoteip.c
Summary

    This module is used to treat the useragent which initiated the
    request as the originating useragent as identified by httpd for the
    purposes of authorization and logging, even where that useragent is
    behind a load balancer, front end server, or proxy server.

    The module overrides the client IP address for the connection
    with the useragent IP address reported in the request header configured
    with the RemoteIPHeader directive.

    Additionally, this module implements the server side of
    HAProxy's
    PROXY Protocol when
    using the RemoteIPProxyProtocol
    directive.

    Once replaced as instructed, this overridden useragent IP address is
    then used for the mod_authz_host
    Require ip
    feature, is reported by mod_status, and is recorded by
    mod_log_config %a and core
    %a format strings. The underlying client IP of the connection
    is available in the %{c}a format string.

    It is critical to only enable this behavior from
    intermediate hosts (proxies, etc) which are trusted by this server, since
    it is trivial for the remote useragent to impersonate another
    useragent.

Topics

 Remote IP Processing
Directives

 RemoteIPHeader
 RemoteIPInternalProxy
 RemoteIPInternalProxyList
 RemoteIPProxiesHeader
 RemoteIPProxyProtocol
 RemoteIPProxyProtocolExceptions
 RemoteIPTrustedProxy
 RemoteIPTrustedProxyList

Bugfix checklisthttpd changelogKnown issuesReport a bugSee also

mod_authz_host
mod_status
mod_log_config
Proxy Protocol Spec
Comments


Remote IP Processing

    Apache by default identifies the useragent with the connection's
    client_ip value, and the connection remote_host and remote_logname are
    derived from this value. These fields play a role in authentication,
    authorization and logging and other purposes by other loadable
    modules.

    mod_remoteip overrides the client IP of the connection with the
    advertised useragent IP as provided by a proxy or load balancer, for
    the duration of the request. A load balancer might establish a long
    lived keepalive connection with the server, and each request will
    have the correct useragent IP, even though the underlying client IP
    address of the load balancer remains unchanged.

    When multiple, comma delimited useragent IP addresses are listed in the
    header value, they are processed in Right-to-Left order.  Processing
    halts when a given useragent IP address is not trusted to present the
    preceding IP address.  The header field is updated to this remaining
    list of unconfirmed IP addresses, or if all IP addresses were trusted,
    this header is removed from the request altogether.

    In overriding the client IP, the module stores the list of intermediate
    hosts in a remoteip-proxy-ip-list note, which mod_log_config
    can record using the %{remoteip-proxy-ip-list}n format token.
    If the administrator needs to store this as an additional header, this
    same value can also be recording as a header using the directive
    RemoteIPProxiesHeader.

    IPv4-over-IPv6 Mapped Addresses
    As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded
    in their IPv4 representation.

    Internal (Private) Addresses
    All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8
    blocks (and IPv6 addresses outside of the public 2000::/3 block) are only
    evaluated by mod_remoteip when RemoteIPInternalProxy
    internal (intranet) proxies are registered.



RemoteIPHeader Directive

Description:Declare the header field which should be parsed for useragent IP addresses
Syntax:RemoteIPHeader header-field
Default:none
Context:server config, virtual host
Status:Base
Module:mod_remoteip

    The RemoteIPHeader directive triggers
    mod_remoteip to treat the value of the specified
    header-field header as the useragent IP address, or list
    of intermediate useragent IP addresses, subject to further configuration
    of the RemoteIPInternalProxy and
    RemoteIPTrustedProxy directives.  Unless these
    other directives are used, mod_remoteip will trust all
    hosts presenting a RemoteIPHeader IP value.

    Internal (Load Balancer) ExampleRemoteIPHeader X-Client-IP


    Proxy ExampleRemoteIPHeader X-Forwarded-For




RemoteIPInternalProxy Directive

Description:Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax:RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ...
Context:server config, virtual host
Status:Base
Module:mod_remoteip

    The RemoteIPInternalProxy directive adds one
    or more addresses (or address blocks) to trust as presenting a valid
    RemoteIPHeader value of the useragent IP.  Unlike the
    RemoteIPTrustedProxy directive, any IP address
    presented in this header, including private intranet addresses, are
    trusted when passed from these proxies.

    Internal (Load Balancer) ExampleRemoteIPHeader X-Client-IP
RemoteIPInternalProxy 10.0.2.0/24
RemoteIPInternalProxy gateway.localdomain




RemoteIPInternalProxyList Directive

Description:Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax:RemoteIPInternalProxyList filename
Context:server config, virtual host
Status:Base
Module:mod_remoteip

    The RemoteIPInternalProxyList directive specifies
    a file parsed at startup, and builds a list of addresses (or address blocks)
    to trust as presenting a valid RemoteIPHeader value of the useragent IP.

    The '#' hash character designates a comment line, otherwise
    each whitespace or newline separated entry is processed identically to
    the RemoteIPInternalProxy directive.

    Internal (Load Balancer) ExampleRemoteIPHeader X-Client-IP
RemoteIPInternalProxyList conf/trusted-proxies.lst


    conf/trusted-proxies.lst contents# Our internally trusted proxies;
10.0.2.0/24         #Everyone in the testing group
gateway.localdomain #The front end balancer



RemoteIPProxiesHeader Directive

Description:Declare the header field which will record all intermediate IP addresses
Syntax:RemoteIPProxiesHeader HeaderFieldName
Context:server config, virtual host
Status:Base
Module:mod_remoteip

    The RemoteIPProxiesHeader directive specifies
    a header into which mod_remoteip will collect a list of
    all of the intermediate client IP addresses trusted to resolve the useragent
    IP of the request. Note that intermediate
    RemoteIPTrustedProxy addresses are recorded in
    this header, while any intermediate
    RemoteIPInternalProxy addresses are discarded.

    ExampleRemoteIPHeader X-Forwarded-For
RemoteIPProxiesHeader X-Forwarded-By




RemoteIPProxyProtocol Directive

Description:Enable or disable PROXY protocol handling
Syntax:RemoteIPProxyProtocol On|Off
Context:server config, virtual host
Status:Base
Module:mod_remoteip
Compatibility:RemoteIPProxyProtocol is only available in httpd 2.4.31 and newer

    The RemoteIPProxyProtocol directive enables or 
    disables the reading and handling of the PROXY protocol connection header.
    If enabled with the On flag, the upstream client must
    send the header every time it opens a connection or the connection will
    be aborted unless it is in the list of disabled hosts provided by the
    RemoteIPProxyProtocolExceptions
    directive.

    While this directive may be specified in any virtual host, it is
    important to understand that because the PROXY protocol is connection
    based and protocol agnostic, the enabling and disabling is actually based
    on IP address and port. This means that if you have multiple name-based
    virtual hosts for the same host and port, and you enable it for any one of
    them, then it is enabled for all of them (with that host and port). It also
    means that if you attempt to enable the PROXY protocol in one and disable
    in the other, that won't work; in such a case, the last one wins and a
    notice will be logged indicating which setting was being overridden.

    Listen 80
<VirtualHost *:80>
    ServerName www.example.com
    RemoteIPProxyProtocol On

    #Requests to this virtual host must have a PROXY protocol
    # header provided. If it is missing, the connection will
    # be aborted
</VirtualHost>

Listen 8080
<VirtualHost *:8080>
    ServerName www.example.com
    RemoteIPProxyProtocol On
    RemoteIPProxyProtocolExceptions 127.0.0.1 10.0.0.0/8

    #Requests to this virtual host must have a PROXY protocol
    # header provided. If it is missing, the connection will
    # be aborted except when coming from localhost or the
    # 10.x.x.x RFC1918 range
</VirtualHost>




RemoteIPProxyProtocolExceptions Directive

Description:Disable processing of PROXY header for certain hosts or networks
Syntax:RemoteIPProxyProtocolExceptions host|range [host|range] [host|range]
Context:server config, virtual host
Status:Base
Module:mod_remoteip
Compatibility:RemoteIPProxyProtocolExceptions is only available in httpd 2.4.31 and newer

    The RemoteIPProxyProtocol directive enables or
    disables the reading and handling of the PROXY protocol connection header.
    Sometimes it is desirable to require clients to provide the PROXY header, but
    permit other clients to connect without it. This directive allows a server 
    administrator to configure a single host or CIDR range of hosts that may do
    so. This is generally useful for monitoring and administrative traffic to a 
    virtual host direct to the server behind the upstream load balancer.



RemoteIPTrustedProxy Directive

Description:Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax:RemoteIPTrustedProxy proxy-ip|proxy-ip/subnet|hostname ...
Context:server config, virtual host
Status:Base
Module:mod_remoteip

    The RemoteIPTrustedProxy directive adds one
    or more addresses (or address blocks) to trust as presenting a valid
    RemoteIPHeader value of the useragent IP.  Unlike the
    RemoteIPInternalProxy directive, any intranet
    or private IP address reported by such proxies, including the 10/8, 172.16/12,
    192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public
    2000::/3 block) are not trusted as the useragent IP, and are left in the
    RemoteIPHeader header's value.

    Trusted (Load Balancer) ExampleRemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxy 10.0.2.16/28
RemoteIPTrustedProxy proxy.example.com




RemoteIPTrustedProxyList Directive

Description:Declare client intranet IP addresses trusted to present the RemoteIPHeader value
Syntax:RemoteIPTrustedProxyList filename
Context:server config, virtual host
Status:Base
Module:mod_remoteip

    The RemoteIPTrustedProxyList directive specifies
    a file parsed at startup, and builds a list of addresses (or address blocks)
    to trust as presenting a valid RemoteIPHeader value of the useragent IP.

    The '#' hash character designates a comment line, otherwise
    each whitespace or newline separated entry is processed identically to
    the RemoteIPTrustedProxy directive.

    Trusted (Load Balancer) ExampleRemoteIPHeader X-Forwarded-For
RemoteIPTrustedProxyList conf/trusted-proxies.lst


    conf/trusted-proxies.lst contents
       # Identified external proxies;
       192.0.2.16/28         #wap phone group of proxies
       proxy.isp.example.com #some well known ISP
    




Available Languages:  en  |
 fr 

Copyright 2026 The Apache Software Foundation.Licensed under the Apache License, Version 2.0.
Modules | Directives | FAQ | Glossary | Sitemap