Debug Konfigurasi #

Debugging konfigurasi Nginx bisa menjadi frustasi jika kamu tidak tahu di mana harus mulai. Nginx tidak selalu memberikan pesan error yang jelas saat perilakunya tidak sesuai harapan — request mungkin jatuh ke server block yang salah, location yang berbeda dari yang dikira, atau header yang tidak diteruskan.

Langkah Pertama: nginx -t #

Sebelum apapun, selalu validasi konfigurasi:

# Test konfigurasi — tampilkan syntax error
sudo nginx -t

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

# Output dengan error:
# nginx: [emerg] unexpected ";" in /etc/nginx/conf.d/example.com.conf:15
# nginx: configuration file /etc/nginx/nginx.conf test failed

nginx -t hanya mengecek sintaks, bukan logika. Konfigurasi yang syntax-valid bisa saja berperilaku berbeda dari yang diharapkan.

Melihat Konfigurasi yang Aktif #

Nginx bisa punya banyak file include. Untuk melihat konfigurasi yang benar-benar aktif setelah semua include digabungkan:

# Tampilkan seluruh konfigurasi yang aktif (termasuk semua include)
sudo nginx -T

# Filter untuk melihat bagian tertentu
sudo nginx -T | grep -A 10 "server_name example.com"

# Hitung berapa server block yang ada
sudo nginx -T | grep -c "server_name"

# Cek apakah directive tertentu ada
sudo nginx -T | grep "proxy_pass"

nginx -T (kapital) melakukan dump konfigurasi lengkap ke stdout. Sangat berguna untuk memverifikasi bahwa include sudah berjalan dan tidak ada konfigurasi yang tertimpa.

Debug dengan return: Mana Location yang Terkena #

Saat bingung mengapa request jatuh ke location yang tidak diharapkan, tambahkan return sementara:

server {
    server_name example.com;

    location / {
        return 200 "jatuh ke location /\n";
    }

    location /api/ {
        return 200 "jatuh ke location /api/\n";
    }

    location ~ \.php$ {
        return 200 "jatuh ke location php regex\n";
    }
}

# Test mana location yang digunakan
curl https://example.com/
# jatuh ke location /

curl https://example.com/api/users
# jatuh ke location /api/

curl https://example.com/index.php
# jatuh ke location php regex

Ini cara tercepat untuk memahami bagaimana Nginx memetakan URL ke location block.

Debug dengan add_header: Inspeksi Variabel #

Untuk melihat nilai variabel Nginx saat request diproses:

server {
    location /debug/ {
        add_header X-Debug-Uri $uri always;
        add_header X-Debug-Args $args always;
        add_header X-Debug-Remote-Addr $remote_addr always;
        add_header X-Debug-Upstream $upstream_addr always;
        add_header X-Debug-Host $host always;

        proxy_pass http://backend;
    }
}

curl -I https://example.com/debug/test?foo=bar
# HTTP/2 200
# x-debug-uri: /debug/test
# x-debug-args: foo=bar
# x-debug-remote-addr: 203.0.113.42
# x-debug-upstream: 10.0.0.1:3000
# x-debug-host: example.com

Jangan lupa hapus debug headers setelah selesai — informasi ini bisa mengekspos detail internal server ke pengguna.

debug_connection: Trace Detail Per-IP #

Untuk debug mendalam tanpa mengaktifkan debug logging global (yang sangat verbose):

# Di main context (luar http{})
error_log /var/log/nginx/error.log;

events {
    # Aktifkan debug logging hanya untuk IP ini
    debug_connection 203.0.113.42;     # IP spesifik
    debug_connection 10.0.0.0/24;      # Atau subnet
}

# Ikuti log saat melakukan request dari IP tersebut
sudo tail -f /var/log/nginx/error.log | grep "debug"

# Contoh output debug yang bisa dilihat:
# rewrite phase: ...
# http script: ...
# http finalize request: ...
# upstream: ...

Debug log menampilkan setiap langkah internal Nginx — fase rewrite, evaluasi location, koneksi ke upstream, dll. Sangat verbose tapi sangat informatif.

Memahami Mengapa Server Block Tertentu Dipilih #

Nginx memilih server block berdasarkan listen dan server_name. Jika tidak ada yang cocok, ia menggunakan default server:

# Kirim request dengan Host header tertentu
curl -H "Host: example.com" http://YOUR_SERVER_IP/

# Test server block mana yang merespons
curl -v https://example.com/ 2>&1 | grep "< HTTP"

# Cek apakah default_server sudah dikonfigurasi
sudo nginx -T | grep "default_server"

# Tangkap request yang tidak cocok dengan server_name manapun
# Berguna untuk debug "siapa yang menangani request ini?"
server {
    listen 80 default_server;
    server_name _;   # Tangkap semua

    return 444;   # 444 = Nginx tutup koneksi tanpa response
    # Atau:
    return 200 "default server\n";
}

Isolasi Masalah: Binary Search #

Saat konfigurasi kompleks tidak bekerja seperti yang diharapkan, gunakan pendekatan binary search — nonaktifkan setengah konfigurasi dan test:

# Konfigurasi asli yang bermasalah (disederhanakan):
server {
    location / {
        # 10 directive di sini, salah satu bermasalah
        proxy_set_header A "a";
        proxy_set_header B "b";
        proxy_set_header C "c";
        proxy_cache my_cache;
        proxy_cache_bypass $cookie_session;
        gzip on;
        add_header X-Custom "value";
        # ... dst
    }
}

# Langkah debug:
# 1. Comment setengah directive
# 2. Test apakah masalah masih ada
# 3. Jika tidak ada → masalah di setengah yang di-comment
# 4. Uncomment setengahnya, comment setengah lagi
# 5. Ulangi hingga menemukan directive bermasalah

Cek Apakah Reload Berhasil #

Setelah nginx -s reload atau systemctl reload nginx, verifikasi perubahan benar-benar aktif:

# Cek kapan Nginx terakhir kali di-reload
sudo systemctl status nginx | grep "Active:"

# Cek PID master process — PID berubah setelah full restart, tidak setelah reload
cat /run/nginx.pid

# Verifikasi konfigurasi baru aktif dengan mengakses endpoint yang baru ditambahkan
curl -I https://example.com/new-endpoint

# Atau cek log untuk konfirmasi reload
sudo journalctl -u nginx | grep "reload\|signal"

Ringkasan #

nginx -t untuk syntax check, nginx -T untuk dump konfigurasi aktif lengkap termasuk semua include.
Sisipkan return 200 "label\n" sementara untuk memverifikasi location block mana yang menangani request tertentu.
add_header X-Debug-* untuk memeriksa nilai variabel Nginx saat runtime — hapus setelah debugging selesai.
debug_connection IP di blok events mengaktifkan debug logging hanya untuk IP tertentu — tidak berdampak ke traffic lain.
Gunakan pendekatan binary search untuk konfigurasi kompleks — comment setengah, test, sempitkan hingga menemukan directive bermasalah.

← Sebelumnya: Error Umum Berikutnya: Tools Diagnostik →