How to Mirror Production Traffic with Nginx’s ngx_http_mirror_module

The goal is to duplicate production traffic to a pre‑release or test environment for functional verification, performance testing, and troubleshooting without affecting real users. Nginx’s ngx_http_mirror_module (available since Nginx 1.13.4) creates background sub‑requests that mirror the original request while discarding the responses.

1. Install Nginx

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

[nginx-stable]
name=nginx stable repo
baseurl=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 Nginx: yum install nginx -y Typical configuration file locations are /etc/nginx/nginx.conf, /usr/local/nginx/conf/nginx.conf or /usr/local/etc/nginx/nginx.conf. Start Nginx with nginx. Common control commands:

# start
nginx
# fast shutdown
nginx -s stop
# graceful shutdown
nginx -s quit
# reload configuration
nginx -s reload
# reopen log files
nginx -s reopen
# list processes
ps -ax | grep nginx

Alternatively stop the master process with kill -s QUIT <master‑pid>.

2. Minimal Configuration

A minimal nginx.conf:

user  nginx;
worker_processes  1;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    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/access.log  main;
    sendfile        on;
    keepalive_timeout  65;
    include /etc/nginx/conf.d/*.conf;
}

3. Using ngx_http_mirror_module

Basic mirroring example:

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

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

To control request‑body mirroring, use mirror_request_body on|off and adjust the mirror location accordingly:

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

location = /mirror {
    internal;
    proxy_pass http://log_backend;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

4. Building Nginx with the Mirror Module

Pre‑built packages may omit the mirror module, so compile from source:

# Download source from http://nginx.org/en/download.html
./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 \
    --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

5. Practical Mirror Configuration

Example upstreams and server block that mirrors requests to multiple test backends and optionally copies the request body:

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 copy
        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;
    }
}

6. Monitoring Commands

ps -eo pid,user,lstart,etime,cmd | grep nginx

– view process runtime. netstat -an | grep ESTABLISHED | wc -l – count established connections. netstat -an | grep ":80" | wc -l – count connections on port 80.

7. References

Official Nginx documentation for core configuration, the mirror module, and related topics can be found at http://nginx.org/en/docs/, http://nginx.org/en/docs/http/ngx_http_mirror_module.html, and http://nginx.org/en/docs/beginners_guide.html. Third‑party resources such as LuaJIT ( http://luajit.org/) and the lua‑nginx‑module repository ( https://github.com/openresty/lua-nginx-module) are also referenced.