SoFunction
Updated on 2025-04-27

The principle and configuration method of Nginx to obtain the real IP of the client

introduction

In modern production environments, Nginx is widely used as a reverse proxy server for service exposure and load balancing. Especially when facing public network access, CDN or cloud vendor load balancers are usually deployed on the Nginx front-end to improve access performance and security. How to accurately obtain and transmit the real IP of the client has become an important topic in development and operation and maintenance.

This article will analyze in detail the principles, configuration methods and usage scenarios of Nginx to obtain the real IP of the client, and help you correctly handle the client IP under different protocols and architectures.

Basic issues with reverse proxy and client IP acquisition

By default, Nginx does not automatically modify or add the request headerX-Forwarded-For, which means:

  • If the front-end load balancer or CDN is not passedX-Forwarded-For, the client IP obtained by Nginx is actually the IP of the load balancer.
  • If the front end has been passedX-Forwarded-For, Nginx will retain and forward the request header as is.

Therefore, in order to ensure that the backend service can correctly identify the client's real IP, the request header usually needs to be configured and adjusted according to the actual situation.

Common variables and their meanings

Understanding Nginx's built-in variables is crucial for proper configuration. The following are key variable resolutions:

$remote_addr

  • Represents the IP address of the previous layer agent or client that establishes a connection to the Nginx server.
  • In TCP Layer 4 load balancing scenario (enable the function of obtaining the client's real IP),$remote_addrUsually the real IP of the client.
  • In HTTP layer seven load balancing scenario,$remote_addrUsually the IP of the load balancer or CDN, because the client's real IP passesX-Forwarded-Fortransfer.

$http_x_forwarded_for

  • Get the request headerX-Forwarded-ForThe original value of the front-end load balancer or CDN adds a list of client IPs.
  • This value can contain one or more IP addresses, separated by commas, representing the client's real IP and the passing proxy IP from left to right.

$proxy_add_x_forwarded_for

  • Nginx comes with composite variables to append the client IP of the currently connected ($remote_addr) to existing onesX-Forwarded-Forin the list.
  • If there is no original in the requestX-Forwarded-For, the value of this variable is$remote_addr。
  • For example, if the front end has been passedX-Forwarded-For: 1.1.1.1,and$remote_addryes2.2.2.2, after setting it to:X-Forwarded-For: 1.1.1.1, 2.2.2.2。

Typical configuration methods and application scenarios

Passing client real IP in Nginx configuration

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

This configuration can be maintained while maintaining the originalX-Forwarded-ForBased on the value, the current connection IP is added, which is suitable for multi-level proxy chain scenarios, making it convenient for back-end services to track source links.

Directly cover the X-Forwarded-For header

proxy_set_header X-Forwarded-For $remote_addr;

This configuration will cover all previously passedX-Forwarded-ForInformation, directly use the current connection IP as the unique value.

Applicable scenarios:

  • You are sure that you are currently connected$remote_addrIt is the real IP of the client (such as when TCP Layer 4 load balancing is enabled for real IP penetration).
  • Or want to avoid resetting IP information when the link passes too long or contains useless proxy IP.

Keep the real IP delivered by the load balancer

The current load balancer has correctly injected the client's real IP intoX-Forwarded-For, generally, there is no need to modify the header in the Nginx anti-generation layer, and it can be forwarded directly:

proxy_set_header X-Forwarded-For $http_x_forwarded_for;

Or if it is not set by default, Nginx will automatically pass the received request header through.

The impact of different protocols and listening levels on IP

  • TCP layer 4 monitoring(Four-layer load balancing):

    • The load balancer forwards traffic directly through the network layer. If “get the real IP of the client” is enabled, then$remote_addrThat is, the real client IP,X-Forwarded-ForUsually not present.

  • HTTP layer seven listening(Seven-layer load balancing):

    • The load balancer proxys the request through the HTTP protocol to put the real IP of the client intoX-Forwarded-Forhead,$remote_addris the load balancer instance IP.

In summary, determining your architecture and protocol environment is the prerequisite for choosing a suitable real IP acquisition strategy.

Print the real IP in the Nginx access log

To more accurately record the client's real IP in the log, you can use when configuring access to the log:

log_format main '$remote_addr - $remote_user [$time_local] '
                '"$request" $status $body_bytes_sent '
                '"$http_referer" "$http_user_agent" '
                '"$http_x_forwarded_for"';

access_log /var/log/nginx/ main;

in,$http_x_forwarded_forIt can display real client IP links for easy troubleshooting and analysis.

Safety protection suggestions

becauseX-Forwarded-ForThe header is easily forged by the client, it is recommended:

  • Trust only IPs from trusted load balancing/proxy servers andX-Forwarded-For。
  • usereal_ipModule (ngx_http_realip_module)replace$remote_addrIt is a real client IP, configured as follows:
set_real_ip_from 192.168.0.0/16;  # Proxy server IP segmentreal_ip_header X-Forwarded-For;
real_ip_recursive on;

This configuration ensures that the backend application can get the correct$remote_addrand prevent forgery.

Summarize

  • Understanding the protocol hierarchy of the load balancer and the “Get the real IP of the client” feature is critical to properly configuring Nginx and backend applications.
  • $proxy_add_x_forwarded_forIt is a best practice for appending client IP and is suitable for multi-level proxy environments.
  • passreal_ipModule configuration to map real client IP to$remote_addr, convenient for application processing.
  • Print in the log$http_x_forwarded_forHelps track multi-hop proxy links.

Proper configuration and use of these variables can help you accurately obtain the real IP of the client in a complex load balancing and proxy environment, ensuring stable operation and security protection of your business.

The above is the detailed content of the principle and configuration method of Nginx to obtain the real IP of the client. For more information about Nginx to obtain the real IP of the client, please pay attention to my other related articles!