Dynamic Module #

Sebelum dynamic module diperkenalkan di Nginx 1.9.11, menambah modul baru berarti mengkompilasi ulang seluruh binary Nginx dari source. Dynamic module mengubah ini — modul dikompilasi sebagai file .so (shared object) terpisah dan dimuat saat runtime melalui directive load_module. Tidak perlu kompilasi ulang, tidak perlu downtime yang panjang.

Static vs Dynamic Module #

Static module (cara lama):
  Modul dikompilasi langsung ke binary nginx
  + Performa sedikit lebih baik (no dynamic linking overhead)
  + Tidak ada risiko kompatibilitas versi
  - Butuh kompilasi ulang nginx untuk tambah/hapus modul
  - Downtime saat update

Dynamic module (cara baru):
  Modul sebagai file .so terpisah
  + Tambah modul tanpa kompilasi ulang nginx
  + Update modul independen dari nginx binary
  - File .so harus dikompilasi dengan versi nginx yang sama
  - Sedikit overhead dynamic linking (biasanya tidak terasa)

Memuat Dynamic Module #

# Di bagian paling atas nginx.conf, sebelum blok apapun
# (di main context, bukan di http{} atau events{})

load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;
load_module modules/ngx_http_geoip2_module.so;
load_module modules/ngx_http_headers_more_filter_module.so;

events { ... }
http { ... }

Path yang diberikan ke load_module bisa relatif (dari direktori prefix Nginx, biasanya /etc/nginx/) atau absolut:

# Relatif — Nginx cari di /etc/nginx/modules/
load_module modules/ngx_http_brotli_filter_module.so;

# Absolut
load_module /usr/lib/nginx/modules/ngx_http_brotli_filter_module.so;

Direktori Module Standar #

# Ubuntu/Debian: module disimpan di
ls /usr/lib/nginx/modules/
# atau
ls /etc/nginx/modules-available/    # Module yang tersedia tapi belum diaktifkan
ls /etc/nginx/modules-enabled/      # Symlink ke yang diaktifkan

# CentOS/RHEL:
ls /usr/lib64/nginx/modules/

# Nginx dari source: biasanya di
ls /etc/nginx/modules/
# atau
ls /usr/local/nginx/modules/

Di Ubuntu/Debian, modul biasanya berupa file konfigurasi di modules-available/ yang diaktifkan dengan symlink ke modules-enabled/. Isinya hanya satu baris load_module ...:

# Cara yang direkomendasikan di Debian/Ubuntu
cat /etc/nginx/modules-available/50-mod-http-brotli-filter.conf
# load_module modules/ngx_http_brotli_filter_module.so;

# Aktifkan dengan symlink
sudo ln -s /etc/nginx/modules-available/50-mod-http-brotli-filter.conf \
           /etc/nginx/modules-enabled/50-mod-http-brotli-filter.conf

sudo nginx -t && sudo systemctl reload nginx

Kompatibilitas Versi: Masalah Utama Dynamic Module #

Ini adalah keterbatasan terpenting yang harus dipahami: file .so harus dikompilasi dengan versi Nginx yang sama persis dengan yang berjalan di server. Tidak bisa menggunakan modul yang dikompilasi untuk Nginx 1.24.0 di Nginx 1.25.0 meski hanya beda patch version.

# Cek versi Nginx yang berjalan
nginx -v
# nginx version: nginx/1.24.0

# Cek modul yang dimuat berjalan dengan benar
nginx -t
# Jika ada incompatibility:
# nginx: [emerg] module .../ngx_http_brotli_filter_module.so is not binary compatible

# Solusi: kompilasi ulang .so dengan source yang sama

Karena itu, saat upgrade Nginx, kamu juga perlu mengkompilasi ulang atau mengupdate semua dynamic module. Ini yang membuat menggunakan paket biner dari distribusi (apt/yum) lebih mudah — mereka mengelola kompatibilitas ini untuk kamu.

Membuat Dynamic Module Sederhana #

Untuk memahami bagaimana dynamic module bekerja, berikut contoh module yang hanya menambahkan header ke setiap response:

// ngx_http_hello_header_module.c
#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>

static ngx_int_t ngx_http_hello_header_handler(ngx_http_request_t *r);

static ngx_http_module_t ngx_http_hello_header_module_ctx = {
    NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL
};

ngx_module_t ngx_http_hello_header_module = {
    NGX_MODULE_V1,
    &ngx_http_hello_header_module_ctx,
    NULL,
    NGX_HTTP_MODULE,
    NULL, NULL, NULL, NULL, NULL, NULL, NULL,
    NGX_MODULE_V1_PADDING
};

Ini hanya untuk ilustrasi — membuat modul C dari awal cukup kompleks. Untuk logika kustom yang lebih sederhana, Lua via OpenResty jauh lebih praktis.

Workflow: Menambah Dynamic Module Baru #

# 1. Cari apakah ada paket biner
apt search nginx-module
# atau
apt search libnginx-mod

# 2. Jika ada, install langsung
sudo apt install libnginx-mod-http-brotli -y

# 3. Aktifkan (Ubuntu/Debian)
sudo ln -s /etc/nginx/modules-available/50-mod-http-brotli-filter.conf \
           /etc/nginx/modules-enabled/
sudo ln -s /etc/nginx/modules-available/50-mod-http-brotli-static.conf \
           /etc/nginx/modules-enabled/

# 4. Test konfigurasi
sudo nginx -t

# 5. Reload
sudo systemctl reload nginx

# 6. Verifikasi modul dimuat
nginx -V 2>&1 | grep -- '--add-dynamic-module'
# Atau cek dengan
nginx -T 2>&1 | head -5   # Lihat module yang dimuat di output konfigurasi

Ringkasan #

load_module harus berada di paling atas nginx.conf, sebelum blok events atau http.
Dynamic module harus dikompilasi dengan versi Nginx yang sama persis — beda minor version pun tidak kompatibel.
Di Ubuntu/Debian, gunakan sistem modules-available/modules-enabled/ dengan symlink — lebih rapi dan mudah dikelola.
Saat upgrade Nginx, selalu update semua dynamic module bersamaan untuk menghindari binary incompatibility.
Untuk logika kustom, Lua via OpenResty jauh lebih mudah dari menulis modul C — gunakan dynamic module C hanya untuk kebutuhan performa atau integrasi level rendah.

← Sebelumnya: Modul Pihak Ketiga Berikutnya: Node.js App →