Methods for Retrieving the Client Source IP

January 18, 2024


In certain situations, our services require using the client IP for specific business or security reasons. However, the usual scenario involves the traffic passing through multiple networks, load balancers, or proxy services before reaching the actual service. At each layer of this process, the original client IP may be lost, leaving our service with only the IP of the preceding network. This outcome is not ideal for us.

Due to the intricate nature of our technology stack, obtaining the client IP involves employing various methods, sometimes in combination.

Managing Client IP via NAT

In certain IDC infrastructures established or leased by users, our services may reside in a separate LAN network behind a gateway. When clients attempt to connect to our services from an external network, the traffic is routed through the gateway.

A similar scenario may arise when utilizing cloud services. The VPC network provided by public cloud platforms functions as an independent LAN network, isolated from other VPCs and the internet. As a result, a gateway is required to facilitate external internet access and connect to external services.

This gateway, which could be a router or firewall device, typically offers DNAT (Destination NAT) address translation services for internal services. This involves the gateway holding one or more public IP addresses and forwarding traffic from specific ports on the public IP to specific ports on an internal IP. The gateway manages traffic forwarding and port mapping. However, due to the modification of the source address in the original IP packet header by the gateway, our services within the internal network can only identify the gateway's IP address, not the actual client address.

Historically, DNAT capabilities provided by network devices or software were relatively basic. They operated mainly at layer 3 and lacked awareness and manipulation capabilities for deeper-layer payloads. Their primary purpose was service exposure, and they couldn't pass the client IP downstream. Additionally, due to the performance limitations of these devices or software, there were constraints on the number of active connections and the maximum number of new connections they could handle. Scaling without hardware upgrades was often challenging, making them less adaptable to the dynamic environment of today.

To address these limitations, we turn to load balancing, which possesses more advanced traffic manipulation capabilities.

Client IP in Load Balancing

In general, load balancing is primarily categorized into two types based on their working layer: layer 4 and layer 7, corresponding to TCP data streams and application traffic (represented by HTTP), respectively.

Differing from IP gateways, load balancing refrains from modifying the IP packet header. At the IP packet level, it solely engages in transparent forwarding. Consequently, in contrast to the previously discussed DNAT, load balancing ensures the correct passage of the source IP contained in the IP packet to the components behind the load balancer.

For layer 4 load balancing, after accomplishing fundamental traffic forwarding, subsequent services can accurately retrieve the client IP without necessitating any special processing. In exceptional scenarios, it can leverage Proxy Protocol. This involves appending a new section before the original traffic payload, encompassing the client IP. Other reverse proxy servers or the service itself behind the load balancer can then interpret Proxy Protocol data to obtain the client IP.

For layer 7 load balancing, it possesses more profound traffic processing capabilities. It can directly convey the source IP at the HTTP protocol level. A prevalent approach is the utilization of the X-Forwarded-For HTTP header. The load balancing component extracts the source IP from the IP packet of the traffic, subsequently parsing and rewriting the HTTP request. It inserts a new XFF field in its request header, incorporating the client IP value.

HTTPS presents a particular challenge due to its encrypted payload, rendering the load balancing component unable to directly manipulate its HTTP headers. In such situations, the following approaches can be considered:

  • Without specific requirements, treating HTTPS traffic as standard TLS traffic and forwarding it directly at layer 4 is an option. In this scenario, the client IP can still be transmitted to the service behind the load balancer through the IP packet header.

  • When layer 7 functionality is necessary, hosting the TLS certificate on the load balancing component enables TLS termination. This process involves removing TLS encryption at the load balancing layer, utilizing plain HTTP on the LAN behind the load balancer, or establishing a new HTTPS connection to the service instead of direct forwarding. This allows the load balancing component to once again handle the original HTTP traffic and continue passing the IP using the XFF method.

Through nuanced traffic handling, load balancing offers various methods to convey the client IP to the backend service. Representative implementations of load balancing components include cloud-based ELB services, hardware-based F5 BIG-IP, Linux Virtual Server (LVS) based on the Linux kernel, and user-software-based NGINX.


Transmission of Client IP in CDN Services

Occasionally, we leverage CDN services provided by public cloud platforms to enhance the speed of user access to our services. Their functioning is akin to a layer 7 reverse proxy server, but in a broader context, CDNs can be considered part of the load-balancing domain.

CDN services typically provide TLS termination capabilities and can incorporate the client IP in HTTP requests sent to the service. For instance, AWS CloudFront CDN service supports passing the client IP using the XFF method, resembling the approach used in layer 7 load balancing.

Utilization of API Gateway

While load balancing components typically offer basic control capabilities for traffic, the APIs provided by cloud-based or hardware load balancers can be challenging to align with our specific business needs. In such scenarios, we turn to more adaptable components to apply tailored strategies to our services. This is where an API gateway, like Apache APISIX or API7 Enterprise, comes into play.

APISIX and API7 Enterprise support the Proxy Protocol, enabling the retrieval of the client IP from the load balancer.

Moreover, they feature a plugin named "real-ip," akin to NGINX's ngx_http_realip_module. This plugin fetches the client's IP from a source and uses it for downstream transmission and logging. The real-ip plugin on APISIX and API7 Enterprise enhances the functionality found on NGINX. It allows for dynamic activation or deactivation of the real source IP feature and expands the sources of client IP beyond the constraints of ngx_http_realip_module, which is limited to HTTP headers and Proxy Protocol. It can leverage any NGINX or APISIX extended variable, such as query parameters or POST form fields.



By leveraging a combination of technologies at different layers, we can effectively pass the client IP through each component of the service, serving both business and security needs.

To learn more about API management solutions, contact

Client IPAPISIX Basics