How to Mirror Traffic with Nginx Using ngx_http_mirror_module

Copying production traffic to a pre‑release or test environment enables functional verification, performance testing with real requests, non‑intrusive debugging, and safe refactoring validation.

1. Install Nginx

Create a YUM repository file /etc/yum.repos.d/nginx.repo with the following content:

[nginx-stable]
name=nginx stable repo
gbaseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

[nginx-mainline]
name=nginx mainline repo
baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

Install: yum install nginx Typical locations for nginx.conf are /etc/nginx, /usr/local/nginx/conf or /usr/local/etc/nginx. Start Nginx with nginx and manage it using:

nginx -s reload

nginx -s quit

ps -ax | grep nginx

2. ngx_http_mirror_module Overview

The ngx_http_mirror_module (available from Nginx 1.13.4) creates background sub‑requests that duplicate the original request; the responses are discarded. This provides traffic mirroring without affecting live traffic.

Basic Example

location / {
    mirror /mirror;
    proxy_pass http://backend;
}

location = /mirror {
    internal;
    proxy_pass http://test_backend$request_uri;
}

To exclude the request body from the mirror, add mirror_request_body off;. When the body is disabled, also set proxy_pass_request_body off; and clear the Content‑Length header.

3. Building Nginx with the Mirror Module

Official packages may omit the module, so compile Nginx from source with the required modules:

./configure \
    --sbin-path=/usr/local/nginx/nginx \
    --conf-path=/usr/local/nginx/nginx.conf \
    --pid-path=/usr/local/nginx/nginx.pid \
    --with-http_ssl_module \
    --without-http_limit_req_module \
    --without-http_mirror_module \
    --with-pcre=../pcre-8.43 \
    --with-zlib=../zlib-1.2.11 \
    --add-module=/path/to/ngx_devel_kit \
    --add-module=/path/to/lua-nginx-module
make && make install

4. Full Configuration Example

upstream api.abc.com { server 127.0.0.1:8080; }
upstream tapi.abc.com { server 127.0.0.1:8081; }

server {
    listen 80;
    location /api {
        proxy_pass http://api.cjs.com;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Traffic mirroring
        mirror /newapi;
        mirror /mirror2;
        mirror /mirror3;
        mirror_request_body on;
    }
    location /tapi {
        proxy_pass http://tapi.cjs.com$request_uri;
        proxy_pass_request_body on;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

5. Useful Commands

# Show Nginx processes with start time
ps -eo pid,user,lstart,etime,cmd | grep nginx
# Count established connections
netstat -an | grep ESTABLISHED | wc -l
# Count connections on port 80
netstat -an | grep ":80" | wc -l

6. References

Official Nginx documentation: http://nginx.org/en/docs/

ngx_http_mirror_module page: http://nginx.org/en/docs/http/ngx_http_mirror_module.html

lua‑nginx‑module on GitHub: https://github.com/openresty/lua-nginx-module