Modul Bawaan #

Nginx hadir dengan banyak modul yang sudah dikompilasi ke dalam binary standar. Sebagian besar sudah aktif otomatis, beberapa perlu dikompilasi secara eksplisit. Mengetahui modul apa saja yang tersedia bisa menghemat banyak waktu — sebelum mencari solusi di luar, periksa dulu apakah Nginx sudah punya yang kamu butuhkan.

Cek Modul yang Terpasang #

# Lihat semua modul yang dikompilasi ke dalam Nginx
nginx -V 2>&1 | tr ' ' '\n' | grep module

# Atau tampilkan lengkap dengan semua flag kompilasi
nginx -V 2>&1

# Cari modul tertentu
nginx -V 2>&1 | grep -o 'with-[^ ]*'

ngx_http_stub_status: Monitoring Dasar #

Menyediakan endpoint dengan statistik koneksi Nginx secara real-time:

server {
    listen 8080;

    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        allow 10.0.0.0/8;
        deny all;
        access_log off;
    }
}

curl http://localhost:8080/nginx_status
# Active connections: 291
# server accepts handled requests
#  16630948 16630948 31070465
# Reading: 6 Writing: 179 Waiting: 106

Output ini dibaca sebagai:

Active connections: total koneksi aktif saat ini
accepts: total koneksi yang diterima sejak Nginx start
handled: total koneksi yang ditangani (sama dengan accepts jika tidak ada drop)
requests: total request yang diproses
Reading: koneksi yang sedang membaca header request
Writing: koneksi yang sedang mengirim response
Waiting: koneksi keepalive yang idle, menunggu request berikutnya

ngx_http_realip: IP Asli di Balik Proxy #

Sudah dibahas di section keamanan, tapi penting disebut sebagai modul:

# Perlu dikompilasi dengan --with-http_realip_module
# Di Ubuntu/Debian, biasanya sudah tersedia di paket nginx-extras

http {
    set_real_ip_from 10.0.0.0/8;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;
}

Cek apakah tersedia: nginx -V 2>&1 | grep realip

ngx_http_sub: Ganti Teks dalam Response #

Modul yang berguna untuk memodifikasi response HTML dari backend tanpa mengubah kode aplikasi:

# Perlu: --with-http_sub_module
server {
    location / {
        proxy_pass http://backend;

        # Ganti teks dalam response body
        sub_filter 'http://old-domain.com' 'https://new-domain.com';

        # Ganti semua kemunculan, bukan hanya yang pertama
        sub_filter_once off;

        # Terapkan pada semua tipe konten (default hanya text/html)
        sub_filter_types text/html application/json;
    }
}

Use case nyata: migrasi domain, meng-inject tracking script ke semua halaman, atau mengganti URL backend yang bocor ke response.

ngx_http_map: Pemetaan Variabel #

map adalah salah satu modul paling fleksibel di Nginx — membuat variabel baru berdasarkan nilai variabel lain:

http {
    # Mapping sederhana: device type berdasarkan User-Agent
    map $http_user_agent $device_type {
        default         "desktop";
        ~*Mobile        "mobile";
        ~*Tablet        "tablet";
    }

    # Mapping: aktifkan maintenance mode untuk path tertentu
    map $uri $maintenance {
        default             0;
        ~^/api/             1;
        ~^/admin/           1;
    }

    # Mapping multi-level: kombinasi dua variabel
    map "$request_method:$uri" $rate_limit_key {
        default             $binary_remote_addr;
        "POST:/auth/login"  "${binary_remote_addr}_login";
        "POST:/api/upload"  "${binary_remote_addr}_upload";
    }

    server {
        location / {
            # Gunakan variabel dari map
            if ($maintenance = 1) {
                return 503;
            }

            proxy_pass http://backend;
        }
    }
}

map dievaluasi secara lazy — hanya dieksekusi saat variabel yang dibuat benar-benar digunakan dalam request. Tidak ada overhead untuk request yang tidak memerlukan variabel tersebut.

ngx_http_geo: Variabel Berdasarkan IP #

geo membuat variabel berdasarkan IP address klien:

http {
    geo $is_bot {
        default         0;
        192.0.2.0/24    1;   # Range IP yang diketahui bot
        198.51.100.5    1;
    }

    geo $client_country {
        default         "unknown";
        # Butuh GeoIP database untuk ini
        # Biasanya dikombinasikan dengan ngx_http_geoip_module
    }

    server {
        location / {
            if ($is_bot) {
                return 403;
            }
            proxy_pass http://backend;
        }
    }
}

Untuk geo berdasarkan negara, gunakan ngx_http_geoip_module (MaxMind GeoIP database) atau ngx_http_geoip2_module (GeoIP2 format yang lebih baru).

ngx_http_split_clients: A/B Testing #

Modul untuk mendistribusikan request ke backend berbeda berdasarkan hash — berguna untuk A/B testing atau canary deployment berbasis persentase yang lebih deterministik dari weight:

http {
    # Bagi trafik: 20% ke backend baru, 80% ke backend lama
    # Hash berdasarkan IP sehingga user yang sama selalu ke backend yang sama
    split_clients "${remote_addr}" $variant {
        20%     "new";
        *       "old";
    }

    # Atau berdasarkan cookie untuk konsistensi lebih baik
    split_clients "${cookie_user_id}" $ab_test {
        50%     "variant_a";
        *       "variant_b";
    }

    upstream backend_old { server 10.0.0.1:3000; }
    upstream backend_new { server 10.0.0.2:3000; }

    server {
        location / {
            proxy_pass http://backend_$variant;
        }
    }
}

ngx_http_auth_request: Delegasi Autentikasi #

Modul yang sangat berguna untuk mengintegrasikan Nginx dengan authentication service eksternal:

# Perlu: --with-http_auth_request_module
server {
    location /protected/ {
        # Nginx akan kirim sub-request ke /auth sebelum memproses request utama
        auth_request /auth;

        # Jika /auth mengembalikan:
        # 2xx → lanjutkan, sajikan konten
        # 401 → kembalikan 401 ke klien
        # 403 → kembalikan 403 ke klien

        # Teruskan header dari response /auth ke request ke backend
        auth_request_set $auth_user $upstream_http_x_auth_user;
        proxy_set_header X-Auth-User $auth_user;

        proxy_pass http://backend;
    }

    # Endpoint auth yang melakukan validasi token/session
    location = /auth {
        internal;   # Hanya bisa dipanggil sebagai sub-request, tidak dari luar
        proxy_pass http://auth_service/validate;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI $request_uri;
    }
}

Pattern ini digunakan oleh banyak sistem SSO dan OAuth proxy — Nginx mendelegasikan keputusan autentikasi ke service terpisah tanpa perlu memodifikasi kode aplikasi backend.

Ringkasan #

stub_status memberikan statistik koneksi real-time — pasang di port terpisah yang hanya bisa diakses internal.
map adalah alat paling fleksibel untuk membuat variabel kustom — dievaluasi lazy, tidak ada overhead jika tidak dipakai.
sub_filter bisa memodifikasi response dari backend tanpa mengubah kode aplikasi — berguna untuk migrasi domain atau injeksi konten.
auth_request mendelegasikan autentikasi ke service eksternal — pola yang digunakan OAuth2 Proxy dan banyak sistem SSO.
Selalu cek nginx -V sebelum menggunakan modul — beberapa butuh dikompilasi eksplisit dan tidak tersedia di semua instalasi.

← Sebelumnya: Open File Cache Berikutnya: Lua dan OpenResty →