Modul Bawaan #

Nginx hadir dengan banyak modul bawaan yang sudah dikompilasi secara langsung ke dalam berkas binary standar (static compilation). Sebagian besar modul ini sudah aktif secara otomatis, sementara beberapa lainnya perlu diaktifkan melalui flag konfigurasi kompilasi yang eksplisit. Mengetahui modul bawaan apa saja yang tersedia adalah langkah krusial bagi administrator web server; hal ini membantu kita menghemat waktu rilis dan CPU server karena kita tidak perlu mencari modul pihak ketiga eksternal untuk fitur yang sebenarnya sudah disediakan secara resmi oleh Nginx.

Di artikel ini, kita akan membedah modul-modul bawaan Nginx yang paling sering digunakan pada lingkungan produksi tingkat lanjut. Kita juga akan menyusun skema verifikasi modul serta mengintegrasikan modul-modul tersebut ke dalam konfigurasi web server kita secara sinergis.

Memverifikasi Modul yang Terpasang di Server #

Sebelum kita menggunakan modul tertentu, kita harus memastikan bahwa binary Nginx kita telah mengompilasi modul tersebut. Kita bisa melakukan verifikasi ini menggunakan baris perintah (command line) dengan memanfaatkan parameter -V (huruf V besar) yang menampilkan seluruh informasi versi dan opsi konfigurasi kompilasi.

Berikut adalah beberapa perintah CLI untuk memeriksa keberadaan modul pada server kita:

# 1. Menampilkan seluruh baris konfigurasi kompilasi
nginx -V 2>&1

# 2. Memecah baris konfigurasi per modul agar lebih mudah dibaca
nginx -V 2>&1 | tr ' ' '\n' | grep module

# 3. Mencari modul tertentu secara spesifik (contoh: realip)
nginx -V 2>&1 | grep -o 'with-[^ ]*realip[^ ]*'

Jika perintah di atas memunculkan string --with-http_realip_module atau modul serupa di terminal kita, itu berarti modul tersebut siap untuk kita gunakan di dalam file nginx.conf.

ngx_http_stub_status: Monitoring Dasar Real-Time #

Modul ngx_http_stub_status menyediakan metrik statistik koneksi Nginx secara instan dan real-time. Informasi ini sangat penting untuk diintegrasikan dengan sistem monitoring eksternal (seperti Prometheus, Datadog, atau Zabbix) guna mengamati beban trafik masuk.

Konfigurasi Endpoint Status yang Aman #

Karena informasi status server bersifat sensitif, kita wajib mengamankan endpoint ini agar hanya bisa diakses oleh server internal kita atau sistem pemantauan terpercaya:

server {
    listen 8080;
    server_name localhost;

    location /nginx_status {
        stub_status;       # Mengaktifkan monitoring stub_status

        # Batasi akses hanya untuk localhost dan IP internal monitoring
        allow 127.0.0.1;
        allow 10.0.0.0/8;  # Contoh segmen network internal kita
        deny all;          # Tolak semua IP lainnya

        access_log off;    # Matikan log akses agar tidak mengotori disk
    }
}

Membaca dan Menganalisis Output Status #

Kita bisa menguji endpoint ini menggunakan utilitas curl:

curl http://localhost:8080/nginx_status

Output respons yang diterima akan terlihat seperti ini:

Active connections: 291 
server accepts handled requests
 16630948 16630948 31070465 
Reading: 6 Writing: 179 Waiting: 106

Cara membaca dan menganalisis metrik di atas adalah sebagai berikut:

Active connections: Jumlah total koneksi klien yang saat ini sedang terbuka dan aktif di Nginx (termasuk koneksi yang sedang sibuk mengirim data maupun koneksi idle).
accepts: Jumlah total koneksi yang telah diterima oleh Nginx semenjak proses server pertama kali dinyalakan.
handled: Jumlah total koneksi yang sukses ditangani. Nilai ini harus selalu sama dengan accepts kecuali jika server kita sempat kehabisan resource (drop connections) akibat batas sistem operasi terlampaui.
requests: Jumlah total permintaan HTTP yang telah dilayani. Rasio antara requests dan handled (di atas menunjukkan rata-rata $1.86$ request per koneksi) membuktikan efisiensi protokol Keepalive kita.
Reading: Jumlah koneksi aktif di mana Nginx sedang membaca header permintaan dari klien. Angka yang terlalu tinggi bisa mengindikasikan serangan tipe Slowloris atau klien dengan koneksi internet sangat lambat.
Writing: Jumlah koneksi aktif di mana Nginx sedang memproses permintaan, membaca data dari upstream, atau menulis data respons kembali ke klien.
Waiting: Jumlah koneksi keepalive yang sedang dalam status idle (waiting for requests). Nilai ini dipengaruhi secara langsung oleh durasi direktif keepalive_timeout.

ngx_http_realip: Mengembalikan IP Klien Asli #

Ketika Nginx kita berada di belakang sistem penyeimbang beban (Load Balancer), CDN seperti Cloudflare, atau reverse proxy eksternal lainnya, variabel $remote_addr bawaan Nginx secara default akan mencatat IP address dari server proxy tersebut, bukan IP address komputer klien asli.

Modul ngx_http_realip memecahkan masalah ini dengan mengganti nilai IP address klien di tingkat variabel internal Nginx berdasarkan header HTTP tepercaya yang disisipkan oleh proxy (seperti X-Forwarded-For atau CF-Connecting-IP).

Konfigurasi Integrasi dengan Cloudflare dan Proxy Internal #

Berikut adalah cara menyusun konfigurasi modul realip di dalam blok http:

http {
    # 1. Daftarkan seluruh IP range proxy/CDN tepercaya kita
    # Contoh range IP resmi milik Cloudflare
    set_real_ip_from 103.21.244.0/22;
    set_real_ip_from 103.22.200.0/22;
    set_real_ip_from 103.31.4.0/22;
    set_real_ip_from 104.16.0.0/13;
    set_real_ip_from 104.24.0.0/14;
    set_real_ip_from 172.64.0.0/13;
    # IP Load Balancer internal kita
    set_real_ip_from 10.10.1.5;

    # 2. Tentukan header HTTP pembawa IP asli
    real_ip_header CF-Connecting-IP; # Gunakan X-Forwarded-For jika proxy standar

    # 3. Aktifkan pencarian rekursif
    real_ip_recursive on;
}

Mengapa real_ip_recursive Sangat Penting? #

Jika real_ip_recursive disetel ke off (default), Nginx hanya akan percaya pada IP proxy terluar yang langsung terhubung dengannya. Namun, jika kita menyalakan real_ip_recursive on, Nginx akan menelusuri daftar IP di dalam header X-Forwarded-For dari kanan ke kiri, mengabaikan IP yang cocok dengan daftar set_real_ip_from, dan mengambil IP pertama yang bukan merupakan bagian dari proxy tepercaya sebagai IP klien asli. Ini mengamankan server kita dari manipulasi header (IP spoofing) oleh penyerang luar.

ngx_http_sub_module: Modifikasi Respons HTML on-the-fly #

Modul ngx_http_sub_module adalah filter respons yang mampu mencari dan mengganti potongan string tertentu di dalam body dokumen HTML yang dikirimkan oleh backend aplikasi kita sebelum data tersebut sampai ke browser klien.

Kasus Penggunaan: Injeksi Skrip Analitik dan Pembaruan URL Domain #

Misalkan kita ingin memigrasi domain dari server lama ke server baru tanpa harus mengubah ribuan baris kode hardcoded di database aplikasi backend:

server {
    listen 80;
    server_name www.domainbaru.com;

    location / {
        proxy_pass http://app_backend;

        # Ganti semua referensi domain lama ke domain baru secara dinamis
        sub_filter 'http://domainlama.com' 'https://www.domainbaru.com';

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

        # Izinkan modifikasi respons untuk JSON dan HTML
        sub_filter_types text/html text/css application/json;

        # Pertahankan header Last-Modified dari backend (jika dibutuhkan)
        sub_filter_last_modified on;
    }
}

Meminimalkan Beban CPU Akibat sub_filter #

Modul filter ini memproses data streaming respons di memori. Jika file yang dikirimkan sangat besar dan sub_filter_once dimatikan (off), beban CPU server kita akan mengalami kenaikan. Praktik terbaiknya adalah membatasi penerapan sub_filter_types hanya untuk file bertipe teks ringan dan memastikan buffer internal Nginx cukup longgar.

ngx_http_map_module: Pemetaan Variabel Dinamis secara Efisien #

Modul ngx_http_map_module membuat variabel baru di Nginx yang nilainya secara otomatis disesuaikan berdasarkan nilai variabel lain. Modul ini merupakan salah satu modul paling serbaguna untuk menyederhanakan logika percabangan di konfigurasi Nginx.

Contoh Pemetaan Jenis Perangkat dan Mode Pemeliharaan (Maintenance) #

Kita mendeklarasikan blok map di dalam konteks http (di luar blok server):

http {
    # 1. Deteksi tipe perangkat berdasarkan string User-Agent
    map $http_user_agent $device_type {
        default         "desktop";
        ~*mobile        "mobile";
        ~*tablet        "tablet";
        ~*android       "mobile";
    }

    # 2. Pengendalian mode pemeliharaan berbasis segmen URI
    map $uri $maintenance_mode {
        default             0;
        ~^/api/v[1-2]/      0; # API utama tetap buka
        ~^/admin/           1; # Blokir akses admin panel
        ~^/dashboard/       1; # Blokir dashboard pengguna
    }

    server {
        listen 80;
        server_name app.unisbadri.com;

        location / {
            # Terapkan hasil map pemeliharaan
            if ($maintenance_mode = 1) {
                return 503; # Kembalikan Service Unavailable
            }

            # Teruskan tipe perangkat ke backend aplikasi via header kustom
            proxy_set_header X-Device-Type $device_type;
            proxy_pass http://app_backend;
        }

        # Halaman kustom maintenance
        error_page 503 /maintenance.html;
        location = /maintenance.html {
            root /var/www/error_pages;
            internal;
        }
    }
}

Keuntungan Utama: Lazy Evaluation #

Hal paling istimewa dari modul map Nginx adalah proses evaluasinya dilakukan secara lazy (tertunda). Nginx tidak akan menghitung nilai variabel baru tersebut di awal transaksi. Perhitungan pola regex atau perbandingan teks hanya akan dilakukan oleh CPU jika variabel kustom tersebut benar-benar dipanggil di dalam konfigurasi request yang sedang diproses.

ngx_http_geo_module: Pengelompokan Berbasis IP Address #

Modul ngx_http_geo_module membuat variabel kustom berdasarkan alamat IP klien. Ini sangat berguna untuk menentukan logika keamanan khusus untuk jaringan kantor atau memisahkan lalu lintas bot.

Konfigurasi Klasifikasi IP Whitelist #

http {
    # Klasifikasikan IP klien ke dalam kategori status akses
    geo $ip_access_level {
        default         "public";
        127.0.0.1       "admin";
        192.168.1.0/24  "internal"; # Jaringan LAN kantor kita
        10.0.0.0/8      "internal"; # Jaringan VPC Cloud
        198.51.100.44   "trusted_partner";
    }

    server {
        listen 80;

        location /secure-endpoint/ {
            # Hanya admin dan IP internal yang diizinkan masuk
            if ($ip_access_level = "public") {
                return 403; # Terlarang untuk publik
            }

            proxy_pass http://backend;
        }
    }
}

ngx_http_split_clients: Distribusi Trafik Persentase (A/B Testing) #

Modul ngx_http_split_clients membagi request klien ke dalam beberapa kelompok variabel menggunakan algoritma hashing MurmurHash3. Metode ini menjamin pembagian trafik yang sangat deterministik berdasarkan kunci kustom (seperti alamat IP atau nilai cookie).

Mengatur Pengujian Fitur Baru (Canary Release) #

http {
    # Pisahkan trafik klien: 15% ke rilis beta v2, 85% ke rilis stabil v1
    # Kita menggunakan IP dan User-Agent sebagai hash key agar konsisten
    split_clients "${remote_addr}${http_user_agent}" $app_upstream {
        15.0%   "backend_beta";
        *       "backend_stable";
    }

    upstream backend_stable {
        server 10.0.2.1:8080;
    }

    upstream backend_beta {
        server 10.0.2.2:8080;
    }

    server {
        listen 80;
        server_name app.unisbadri.com;

        location / {
            proxy_pass http://$app_upstream;
            add_header X-Route-Group $app_upstream always;
        }
    }
}

ngx_http_auth_request_module: Delegasi Otorisasi #

Modul ngx_http_auth_request_module mendelegasikan proses autentikasi dan otorisasi klien kepada server otorisasi eksternal sebelum Nginx meneruskan request ke backend aplikasi utama. Jika sub-request otorisasi mengembalikan kode status HTTP 2xx, Nginx melanjutkan proses. Jika otorisasi mengembalikan HTTP 401 atau 403, Nginx langsung memotong koneksi dan mengirimkan kode kesalahan tersebut ke klien.

Berikut adalah diagram urutan alur kerja modul ini di tingkat jaringan:

sequenceDiagram
    autonumber
    actor Klien as Klien Browser
    participant Nginx as Nginx Web Server
    participant Auth as Auth Service (External)
    participant App as Backend Application

    Klien->>Nginx: GET /protected/resource
    Note over Nginx: Mendeteksi auth_request /auth
    Nginx->>Auth: GET /auth (Sub-request Internal)
    Note over Auth: Validasi Session / JWT Cookie
    alt Token Valid (HTTP 200 OK)
        Auth-->>Nginx: HTTP 200 OK + Header (X-User)
        Note over Nginx: Set variabel dari response header
        Nginx->>App: GET /protected/resource + X-Auth-User
        App-->>Nginx: HTTP 200 OK (Content)
        Nginx-->>Klien: HTTP 200 OK (Content)
    else Token Tidak Valid / Expired (HTTP 401/403)
        Auth-->>Nginx: HTTP 401 Unauthorized
        Nginx-->>Klien: HTTP 401 Unauthorized (Redirect ke Login)
    end

Konfigurasi Delegasi Autentikasi dengan OAuth2 Proxy #

server {
    listen 443 ssl;
    server_name portal.unisbadri.com;

    location /private/ {
        # Langkah 1: Kirim sub-request internal ke lokasi /auth
        auth_request /auth;

        # Langkah 2: Jika auth sukses, ambil user header dari auth service
        # dan kirimkan ke backend utama kita
        auth_request_set $user $upstream_http_x_auth_user;
        proxy_set_header X-Authenticated-User $user;

        proxy_pass http://private_backend;
    }

    # Endpoint penampung sub-request otorisasi
    location = /auth {
        internal; # Mencegah akses langsung dari internet luar

        proxy_pass http://auth_service.internal/validate-token;
        proxy_pass_request_body off;          # Hemat bandwidth: jangan kirim body request klien
        proxy_set_header Content-Length "";  # Setel kosong agar auth service tidak menunggu input
        proxy_set_header X-Original-URI $request_uri;
    }

    # Penanganan jika otorisasi gagal
    error_page 401 = @redirect_to_login;
    location @redirect_to_login {
        return 302 https://sso.unisbadri.com/login?rd=$scheme://$host$request_uri;
    }
}

ngx_http_secure_link_module: Mengamankan Tautan Unduhan #

Modul ngx_http_secure_link_module digunakan untuk melindungi berkas unduhan di server kita agar tidak bisa diunduh secara sembarangan oleh pihak yang tidak memiliki hak akses (hotlinking prevention), serta membatasi waktu kedaluwarsa tautan tersebut.

Modul ini memverifikasi kecocokan antara parameter tanda tangan digital (hash MD5) yang dikirim klien di URL dengan hash MD5 yang dihitung secara dinamis oleh server Nginx kita menggunakan kunci rahasia (shared secret) dan waktu kedaluwarsa.

Konfigurasi Secure Link di Nginx #

server {
    listen 80;
    server_name downloads.unisbadri.com;

    location /files/ {
        # Pola URL: /files/namafile?md5=hash-string&expires=unix-timestamp
        secure_link $arg_md5,$arg_expires;

        # Hitung hash MD5 pembanding dari variabel internal:
        # shared_secret + URI berkas + Unix timestamp kedaluwarsa
        secure_link_md5 "KunciRahasiaServerKita$uri$arg_expires";

        # Verifikasi kecocokan hash
        if ($secure_link = "") {
            # Hash tidak cocok sama sekali (Unauthorized)
            return 403;
        }

        if ($secure_link = "0") {
            # Hash cocok tapi waktu kedaluwarsa telah terlampaui
            return 410; # Gone
        }

        # Jika lolos verifikasi, sajikan file unduhan
        root /var/www/downloads;
    }
}

Pembuatan Tautan dari Aplikasi Backend #

Di aplikasi backend kita (misalnya Node.js atau Python), kita membuat tautan kedaluwarsa dengan algoritma berikut:

Hitung Unix timestamp kedaluwarsa (misalnya 3 jam dari sekarang = 1789000000).
Buat string input: "KunciRahasiaServerKita/files/document.pdf1789000000".
Hitung hash MD5 dari string input tersebut.
Ubah hash MD5 biner menjadi format Base64 URL-safe (ganti + dengan -, / dengan _, dan hapus =).
Bentuk tautan final: https://downloads.unisbadri.com/files/document.pdf?md5=HasilHash&expires=1789000000.

ngx_http_addition_module: Menggabungkan Konten Otomatis #

Modul ngx_http_addition_module menyisipkan output dari URI internal lain sebelum atau setelah isi body respons utama. Modul ini sangat berguna untuk menyisipkan header navigasi, iklan promosi, atau footer hak cipta pada halaman statis secara terpusat tanpa menyentuh kode file HTML individu.

Konfigurasi Penambahan Header/Footer #

server {
    listen 80;
    server_name blog.unisbadri.com;

    location /articles/ {
        root /var/www/blog;

        # 1. Sisipkan file header sebelum body file HTML disajikan
        add_before_body /includes/header.html;

        # 2. Sisipkan file footer setelah body file HTML selesai disajikan
        add_after_body /includes/footer.html;

        # Batasi hanya untuk tipe text/html
        addition_types text/html;
    }

    # Tandai lokasi includes sebagai internal agar tidak bisa diakses langsung klien
    location /includes/ {
        root /var/www/blog;
        internal;
    }
}

Analisis Perbandingan dan Dampak Overhead Modul #

Setiap modul memiliki dampak tersendiri terhadap performa CPU dan memori RAM server Nginx kita. Berikut adalah tabel ringkasan dampak dan karakteristik modul bawaan:

Modul Nginx	Tipe Operasi	Dampak CPU	Dampak RAM	Rekomendasi Penggunaan
`ngx_http_stub_status`	Membaca metrik internal	Sangat Rendah	Sangat Rendah	Selalu aktifkan di port internal terpisah untuk monitoring instans.
`ngx_http_realip`	Penulisan ulang IP address	Sangat Rendah	Sangat Rendah	Wajib diaktifkan jika Nginx berada di belakang CDN/Load Balancer.
`ngx_http_sub_module`	Pemindaian string respons	Sedang	Rendah	Batasi hanya untuk file teks berukuran kecil demi menghemat CPU.
`ngx_http_map_module`	Evaluasi variabel dinamis	Rendah (Lazy)	Rendah	Gunakan sesering mungkin untuk menggantikan percabangan `if` yang berat.
`ngx_http_geo_module`	Pencarian IP radial	Rendah	Rendah	Sangat efisien untuk whitelist/blacklist IP dalam jumlah massal.
`ngx_http_split_clients`	Hashing MurmurHash3	Rendah	Sangat Rendah	Ideal untuk implementasi A/B testing dan canary release aman.
`ngx_http_auth_request`	Sub-request jaringan	Sedang (Network)	Rendah	Pastikan backend auth merespons cepat untuk menghindari latensi tinggi.
`ngx_http_secure_link`	Perhitungan MD5	Rendah	Sangat Rendah	Gunakan untuk file statik berharga atau membatasi masa berlaku tautan unduhan.

Ringkasan dan Praktik Terbaik #

Hindari if Bertingkat, Gunakan map: Struktur percabangan if di dalam location block Nginx sering memicu perilaku tidak terduga (if is evil). Manfaatkan modul map untuk membuat keputusan variabel yang bersih dan aman.
Amankan stub_status: Jangan pernah membiarkan endpoint monitoring status terbuka untuk publik. Batasi menggunakan IP whitelist allow/deny atau gunakan port internal.
Aktifkan real_ip_recursive: Selalu nyalakan fitur rekursif pada modul realip jika infrastruktur kita menggunakan CDN berlapis guna memblokir celah manipulasi header IP dari penyerang luar.
Gunakan sub_filter Secara Selektif: Hindari memproses dokumen biner atau HTML berukuran mega-byte menggunakan sub_filter karena hal tersebut memicu peningkatan beban komputasi CPU worker.

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