Debug Konfigurasi #

Debugging konfigurasi Nginx bisa menjadi proses yang membingungkan jika kita tidak mengetahui dari mana harus memulai. Nginx sering kali tidak memberikan pesan galat (error) yang langsung mengarah pada kesalahan logika di dalam berkas konfigurasi. Sebagai contoh, server kita bisa saja berjalan lancar tanpa galat sintaksis, tetapi permintaan (request) klien secara misterius jatuh ke server block yang salah, atau location block yang tidak sesuai harapan, atau header proxy yang kita buat ternyata tidak diteruskan ke backend.

Kendala-kendala logika semacam ini membutuhkan teknik pelacakan (tracing) dan pembongkaran (debugging) konfigurasi secara terstruktur. Di artikel ini, kita akan membahas cara membedah logika pemilihan blok di Nginx, memetakan rute menggunakan perintah diagnostik, melakukan inspeksi variabel runtime secara langsung, serta menerapkan isolasi masalah dengan metode sistematis.

Aturan Prioritas Pemilihan Location Block #

Salah satu sumber kebingungan terbesar dalam debugging konfigurasi Nginx adalah memahami location block mana yang memenangkan pencocokan rute ketika ada beberapa location block yang saling tumpang tindih.

Nginx tidak mencocokkan location block berdasarkan urutan penulisan dari atas ke bawah di dalam berkas konfigurasi, melainkan mengikuti urutan prioritas operator pencocokan berikut:

  1. Exact Match (=): Mencocokkan URI secara tepat karakter demi karakter. Jika ada kecocokan, pencarian langsung dihentikan dan location ini digunakan.
  2. Preferential Prefix (^~): Mencocokkan awalan URI terpanjang. Jika kecocokan terpanjang ditemukan di bawah operator ini, Nginx akan langsung menggunakan rute ini dan mengabaikan pemeriksaan ekspresi reguler (regular expression / regex).
  3. Regex Match (~ atau ~*): Mencocokkan ekspresi reguler secara peka huruf besar-kecil (~) atau tidak peka (~*). Nginx akan memindai dari atas ke bawah dan memenangkan rute regex pertama yang cocok.
  4. Standard Prefix (tanpa operator): Mencocokkan awalan URI terpanjang. Rute ini hanya akan digunakan jika tidak ada ekspresi reguler yang cocok.

Berikut adalah diagram alur keputusan pemilihan location block di Nginx:

flowchart TD
    Req["Request URI Tiba"] --> MatchExact{"1. Cek Exact Match '='?"}
    MatchExact -->|"Ya (Cocok)"| Exact["Gunakan Location '='<br/>(Hentikan Pencarian)"]
    MatchExact -->|"Tidak"| Preferential{"2. Cek Preferential Prefix '^~'?"}
    
    Preferential -->|"Ya (Cocok Terpanjang)"| PreferentialAction["Gunakan Location '^~'<br/>(Hentikan Pencarian, Abaikan Regex)"]
    Preferential -->|"Tidak"| RegexCheck{"3. Cek Regex Match '~' atau '~*'?"}
    
    RegexCheck -->|"Ada yang Cocok"| RegexAction["Gunakan Regex Pertama yang Cocok<br/>(Hentikan Pencarian)"]
    RegexCheck -->|"Tidak Ada yang Cocok"| StandardPrefix{"4. Cek Standard Prefix?"}
    
    StandardPrefix -->|"Ada yang Cocok"| StandardAction["Gunakan Prefix Terpanjang yang Cocok"]
    StandardPrefix -->|"Tidak Ada"| DefaultRoute["5. Fallback ke Default Location '/'"]

    classDef default fill:#f9f9f9,stroke:#d1d5db,stroke-width:1px,color:#111827;
    classDef matchStyle fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a;
    classDef stopStyle fill:#f0fdf4,stroke:#15803d,stroke-width:2px,color:#166534;
    class MatchExact,Preferential,RegexCheck,StandardPrefix matchStyle;
    class Exact,PreferentialAction,RegexAction,StandardAction,DefaultRoute stopStyle;

Langkah Pertama: Validasi Sintaksis dengan nginx -t #

Langkah pertama dalam setiap skenario debugging adalah melakukan validasi sintaksis berkas konfigurasi. Kita tidak boleh melakukan reload konfigurasi pada server produksi sebelum memastikan tidak ada kesalahan penulisan (typo) atau tanda baca yang hilang.

# Uji konfigurasi default (/etc/nginx/nginx.conf)
sudo nginx -t

# Output sukses yang diharapkan:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

Jika terjadi kesalahan, nginx -t akan langsung menampilkan baris berkas dan jenis galatnya:

nginx: [emerg] unexpected ";" in /etc/nginx/conf.d/app.conf:15
nginx: configuration file /etc/nginx/nginx.conf test failed

Menguji Berkas Konfigurasi Alternatif #

Saat kita sedang melakukan eksperimen konfigurasi baru dan tidak ingin mengganggu berkas konfigurasi utama server berjalan, kita bisa menduplikasi konfigurasi ke folder cadangan lalu memvalidasinya secara spesifik:

sudo nginx -t -c /var/www/test-env/nginx.conf

Dump Konfigurasi Aktif dengan nginx -T #

Pada server produksi dengan puluhan berkas konfigurasi virtual host yang saling terhubung menggunakan direktif include, melacak direktif mana yang aktif atau tertimpa (override) bisa menjadi sangat melelahkan.

Kita bisa menggunakan perintah nginx -T (huruf T kapital) untuk memerintahkan Nginx menggabungkan seluruh berkas include ke dalam satu keluaran dump teks utuh di terminal.

# Tampilkan seluruh konfigurasi aktif di terminal
sudo nginx -T

Karena outputnya bisa sangat panjang, kita dapat memadukannya dengan utilitas pencarian grep untuk memverifikasi apakah direktif tertentu telah dimuat secara benar:

# Cari di mana letak deklarasi server_name tertentu
sudo nginx -T | grep -A 10 "server_name app.unisbadri.com"

# Periksa apakah SSL parameter telah ter-include di semua tempat
sudo nginx -T | grep -E "ssl_protocols|ssl_ciphers"

# Hitung jumlah server block aktif yang terbaca oleh Nginx
sudo nginx -T | grep -c "server_name"

Debug dengan return: Melacak Pemetaan Location #

Ketika kita kebingungan mengapa suatu request diproses secara salah oleh Nginx (misalnya file statik JS mengembalikan error 404 padahal file ada di disk), kita dapat menggunakan taktik menyisipkan direktif return sementara dengan respons teks polos untuk mendeteksi location block mana yang memenangkan pencocokan rute.

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

    location / {
        return 200 "Rute Terpilih: Location Root ()\n";
    }

    location /api/ {
        return 200 "Rute Terpilih: Location API PREFIX\n";
    }

    location ^~ /api/v2/ {
        return 200 "Rute Terpilih: Location API V2 PREFERENTIAL\n";
    }

    location ~* \.php$ {
        return 200 "Rute Terpilih: Location PHP REGEX\n";
    }
}

Setelah memuat ulang konfigurasi tersebut di server testing, kita mengirimkan request menggunakan curl untuk melihat teks responsnya:

# Kasus 1: Request ke path root
curl http://test.unisbadri.com/
# Output: Rute Terpilih: Location Root ()

# Kasus 2: Request ke /api/users
curl http://test.unisbadri.com/api/users
# Output: Rute Terpilih: Location API PREFIX

# Kasus 3: Request ke /api/v2/auth (preferential memenangkan rute dari regex)
curl http://test.unisbadri.com/api/v2/auth.php
# Output: Rute Terpilih: Location API V2 PREFERENTIAL

Taktik sederhana ini memotong waktu debugging secara drastis karena kita tidak perlu menebak-nebak aturan reguler ekspresi mana yang salah tulis.

Debug dengan add_header: Inspeksi Variabel Runtime #

Nginx memiliki puluhan variabel internal (seperti $uri, $request_uri, $args, $upstream_addr, $upstream_response_time, dsb.) yang nilainya berubah secara dinamis di setiap request.

Untuk mengetahui isi nilai variabel tersebut secara langsung saat request diproses, kita bisa menambahkan kustom header respons menggunakan direktif add_header dengan flag always:

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

    location / {
        proxy_pass http://nodejs_backend;

        # Tambahkan header debug pada respons HTTP
        add_header X-Debug-URI "$uri" always;
        add_header X-Debug-Request-URI "$request_uri" always;
        add_header X-Debug-Args "$args" always;
        add_header X-Debug-Upstream-Addr "$upstream_addr" always;
        add_header X-Debug-Upstream-Response "$upstream_response_time" always;
        add_header X-Debug-Client-IP "$remote_addr" always;
    }
}

Kirimkan request menggunakan flag -I pada curl untuk menginspeksi header respons yang kembali dari server:

curl -I "http://debug.unisbadri.com/api/users?status=active"

# HTTP/1.1 200 OK
# Server: nginx
# X-Debug-URI: /api/users
# X-Debug-Request-URI: /api/users?status=active
# X-Debug-Args: status=active
# X-Debug-Upstream-Addr: 127.0.0.1:3000
# X-Debug-Upstream-Response: 0.045
# X-Debug-Client-IP: 203.0.113.50

[!WARNING] Jangan pernah membiarkan konfigurasi header debug kustom ini aktif di lingkungan produksi secara permanen. Hal ini dapat mengekspos informasi arsitektur jaringan internal, alamat IP backend, dan struktur port kita ke pihak luar yang dapat disalahgunakan untuk penyerangan.

debug_connection: Pelacakan Mendalam Per-IP #

Menyalakan level log debug secara global di server produksi adalah tindakan berbahaya karena volume penulisan log debug yang sangat masif akan memakan ruang disk gigabytes dalam hitungan menit, sekaligus membebani performa CPU I/O server.

Nginx menyediakan solusi cerdas bernama direktif debug_connection di dalam konteks events. Direktif ini memungkinkan kita menyalakan pencatatan log debug tingkat tinggi secara eksklusif hanya untuk alamat IP atau subnet tertentu saja (misalnya IP laptop kantor pengembang kita).

# Di main context (paling atas nginx.conf, di luar http{})
error_log /var/log/nginx/error.log warn; # Default level global tetap aman

events {
    worker_connections 1024;

    # Aktifkan pencatatan debug log hanya untuk alamat IP tester kita
    debug_connection 203.0.113.42;
    
    # Kita juga bisa memasukkan segmen subnet VPN internal
    debug_connection 10.8.0.0/24;
}

Ketika laptop dengan IP 203.0.113.42 mengirimkan request ke server kita, Nginx akan menuliskan log pemrosesan internal secara sangat detail di /var/log/nginx/error.log (seperti proses parsing header, pencocokan regex, fase rewrite, handshake SSL, hingga transfer bita), sedangkan request dari IP pengguna lain di internet tetap dicatat menggunakan level log standar warn.

Debugging Aturan Rewrite dengan rewrite_log #

Ketika kita menggunakan direktif rewrite untuk mengubah URL secara dinamis (misalnya mengarahkan URL ramah pengguna ke berkas internal), melacak apakah regex pencocokan rewrite berjalan dengan benar atau mengalami infinite loop (putaran tanpa akhir) sangatlah sulit dilakukan hanya dengan melihat browser.

Nginx menyediakan modul bawaan yang dapat merekam setiap proses evaluasi aturan rewrite ke dalam berkas error log menggunakan direktif rewrite_log.

  1. Aktifkan rewrite_log di tingkat server block:

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

    # Aktifkan pencatatan evaluasi rewrite rule
    rewrite_log on;

    # Kita wajib setel error_log ke level 'notice' agar log rewrite tercatat
    error_log /var/log/nginx/app-error.log notice;

    rewrite ^/users/([0-9]+)/?$ /profile.php?id=$1 last;
    rewrite ^/posts/([a-zA-Z0-9\-]+)/?$ /article.php?slug=$1 last;
}

  2. Analisis Output Log Rewrite: Saat request /users/42 masuk, Nginx akan menuliskan tahapan pencocokan regex ke dalam log:

    2026/06/16 14:30:00 [notice] 12345#12345: *127 "^/users/([0-9]+)/?$" matches "/users/42", rewriting to "/profile.php?id=42", client: 203.0.113.50, server: app.unisbadri.com, request: "GET /users/42 HTTP/1.1", host: "app.unisbadri.com"

    Jika terjadi kesalahan regex sehingga request tidak ter-rewrite, log akan menampilkan:

    2026/06/16 14:30:05 [notice] 12345#12345: *128 "^/users/([0-9]+)/?$" does not match "/users/abc", client: 203.0.113.50, server: app.unisbadri.com, request: "GET /users/abc HTTP/1.1", host: "app.unisbadri.com"

    Jika kita salah menulis flag last atau break sehingga memicu loop tak berujung (Nginx membatasi maksimum 10 kali putaran internal redirect), Nginx akan mengembalikan error 500 dan menulis log berikut:

    2026/06/16 14:30:10 [error] 12345#12345: *129 rewrite or internal redirection cycle while processing "/profile.php", ...

    Dengan mengaktifkan rewrite_log on dan menaikkan level log ke notice, kita dapat membongkar masalah redirect internal secara presisi.

Mendiagnosis Pemilihan Server Block (Virtual Host Mismatch) #

Skenario membingungkan lainnya adalah ketika kita memiliki beberapa berkas server block dengan server_name yang berbeda, tetapi request ke domain b.com selalu dijawab oleh konfigurasi milik a.com.

Untuk memecahkan masalah pemilihan server block (virtual host resolution), kita dapat menerapkan langkah diagnosis berikut:

  1. Periksa Direktif default_server: Nginx menggunakan server block yang memiliki parameter default_server pada direktif listen jika domain request tidak cocok dengan server_name mana pun. Jika tidak ada server block yang dideklarasikan sebagai default_server, Nginx secara otomatis akan menunjuk server block pertama yang dimuat di memori sebagai default server.

  2. Periksa Urutan Loading Berkas: Jika kita menggunakan direktif include /etc/nginx/conf.d/*.conf;, sistem operasi memuat berkas berdasarkan urutan alfabetis nama berkasnya. Berkas a.com.conf akan dimuat sebelum b.com.conf. Jika b.com salah diketik di konfigurasinya (misalnya kurang satu huruf), request ke b.com akan dijawab oleh default server (yaitu a.com.conf karena dimuat paling pertama).

  3. Uji Resolusi dengan Curl: Kita dapat mengirimkan request dengan memaksa HTTP Host header kustom untuk mensimulasikan pencocokan server name:

    # Test request ke IP server dengan memaksa Host domain B
curl -H "Host: b.com" http://IP_SERVER_KITA/

    Gabungkan ini dengan taktik return 200 "server b aktif" di dalam server block untuk memverifikasi secara langsung.

Saat kita menghadapi konfigurasi virtual host yang sangat kompleks (misal ratusan baris kode dengan puluhan rewrite rules, location block, header manipulation, dan cache bypass) yang memicu anomali perilaku server, mendebug dengan cara menebak baris mana yang salah sering kali berujung kegagalan.

Kita dapat menerapkan strategi Binary Search konfigurasi untuk melokalisasi masalah:

  1. Duplikasi file: Duplikasikan file konfigurasi virtual host bermasalah ke file cadangan.
  2. Komentari Setengah Blok: Nonaktifkan (beri tanda # di awal baris) sekitar setengah dari jumlah blok konfigurasi dinamis (misalnya nonaktifkan seluruh modul caching dan kompresi).
  3. Validasi dan Muat Ulang: Jalankan nginx -t lalu reload server.
  4. Uji Perilaku: Kirim request uji coba.
    • Jika masalah hilang: Berarti direktif yang bermasalah berada di dalam setengah blok konfigurasi yang baru saja kita komentari.
    • Jika masalah tetap ada: Berarti direktif yang bermasalah berada di dalam konfigurasi setengah blok yang masih aktif.
  5. Persempit Area: Ulangi pembagian setengah blok aktif tersebut hingga kita berhasil mengisolasi tepat satu direktif tunggal yang menjadi biang kerok masalah.

Strategi eliminasi sistematis ini menjamin temuan akar masalah secara logis tanpa terpengaruh oleh asumsi subjektif kita.

Verifikasi Keberhasilan Graceful Reload #

Setelah kita melakukan perubahan konfigurasi dan menjalakan sudo systemctl reload nginx, bagaimana kita bisa yakin bahwa Nginx benar-benar telah memuat ulang konfigurasi baru tersebut secara sukses tanpa kegagalan tersembunyi?

Kita bisa memverifikasinya melalui langkah-langkah berikut:

  • Langkah 1: Periksa log jurnal systemd untuk melihat status sinyal reload Nginx:
    sudo journalctl -u nginx --since "10 minutes ago"

# Log reload sukses yang diharapkan:
# systemd[1]: Reloading nginx - high performance web server...
# nginx[12345]: nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx[12345]: nginx: configuration file /etc/nginx/nginx.conf test is successful
# systemd[1]: Reloaded nginx - high performance web server.
  • Langkah 2: Periksa nomor Process ID (PID) master process Nginx. Pada proses graceful reload, PID master process tidak akan berubah, hanya PID worker process saja yang digantikan secara bertahap:
    # Catat PID master Nginx
cat /run/nginx.pid

# Periksa waktu pembuatan worker process baru
ps -eo pid,ppid,lstart,cmd | grep nginx
    Jika waktu pembuatan (start time) worker process baru selaras dengan detik saat kita menjalankan perintah reload, berarti transisi graceful reload telah berjalan dengan sukses di server kita.

Ringkasan Teknik Debugging #

  • nginx -T: Dump seluruh isi berkas konfigurasi aktif terintegrasi untuk melacak jika ada direktif duplikat yang tidak sengaja tertimpa.
  • Gunakan return sementara: Deteksi rute location block yang memenangkan pencocokan URI dengan membalikkan respons teks polos.
  • add_header X-Debug-*: Tampilkan nilai variabel runtime internal seperti $upstream_addr untuk melacak distribusi beban request backend.
  • debug_connection: Batasi pengaktifan verbose debug logging hanya untuk IP laptop kita demi menjaga performa server produksi.
  • Terapkan Binary Search: Temukan baris konfigurasi bermasalah pada berkas konfigurasi raksasa dengan cara menonaktifkan setengah bagian secara berkala.

← Sebelumnya: Error Umum   Berikutnya: Tools Diagnostik →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact