From 28fe4a6f6361ec3e7378984479b246466d2d970b Mon Sep 17 00:00:00 2001 From: "petar.nikolic" <153569195+pekisa15@users.noreply.github.com> Date: Tue, 16 Sep 2025 01:23:44 +0200 Subject: [PATCH] Added nginx documentation --- source/_posts/nginx.md | 587 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 587 insertions(+) create mode 100644 source/_posts/nginx.md diff --git a/source/_posts/nginx.md b/source/_posts/nginx.md new file mode 100644 index 0000000..f4d1713 --- /dev/null +++ b/source/_posts/nginx.md @@ -0,0 +1,587 @@ +--- +title: Nginx +date: 2025-09-15 21:17:50 +background: bg-slate-600 +tags: +categories: + - Linux Command +intro: nginx quick reference cheat sheet +plugins: + - copyCode +--- +## Getting Started {.cols-3} + +### Install & Service + +- **Ubuntu/Debian** + ```shell script + $ sudo apt update && sudo apt install -y nginx + ``` +- **RHEL/CentOS** + ```shell script + $ sudo yum install -y epel-release nginx && sudo systemctl enable --now nginx + ``` +- **Service** + ```shell script + $ sudo systemctl status nginx + $ sudo systemctl reload nginx + $ sudo systemctl restart nginx + $ sudo nginx -t # test config + $ nginx -V # built modules + ``` + +### Key Paths + +- `/etc/nginx/nginx.conf` _(main config)_ +- `/etc/nginx/conf.d/*.conf` _(drop‑ins)_ +- `/etc/nginx/sites-available/` + `sites-enabled/` _(Debian style)_ +- `/var/www/html` _(default docroot)_ +- `logs`: `/var/log/nginx/access.log`, `/var/log/nginx/error.log` + +### Minimal HTTP Server + +```nginx +# /etc/nginx/conf.d/example.conf +server { + listen 80; + server_name example.com; + root /var/www/example/public; + + location / { + try_files $uri $uri/ =404; + } +} +``` + +## Config Structure {.cols-3} + +### Core Blocks + +- `main` (global) +- `events` (worker connections) +- `http` → `server` → `location` +- `stream` (TCP/UDP) +- `upstream` (load balancers) + +```nginx +user www-data; +worker_processes auto; + +events { worker_connections 1024; } + +http { + include mime.types; + default_type application/octet-stream; + sendfile on; + keepalive_timeout 65; + + # servers / includes go here... +} +``` + +### Context & Order + +- **`location` match order**: + 1. Exact `=` + 2. `^~` (no regex if matched) + 3. Regex `~` / `~*` (first match) + 4. Prefix (longest path) +- `try_files` evaluates in order then falls back. + +```nginx +location = /healthz { return 204; } +location ^~ /static/ { expires 7d; } +location ~* \.(png|jpg|css|js)$ { expires 7d; } +location / { try_files $uri $uri/ /index.html; } +``` + +### Common Includes + +```nginx +http { + include /etc/nginx/conf.d/*.conf; + include /etc/nginx/snippets/*.conf; # Ubuntu/Debian +} +``` + +## Virtual Hosts & Redirects {.cols-3} + +### Basic Server Block + +```nginx +server { + listen 80; + server_name example.com www.example.com; + root /var/www/example/public; + index index.html index.htm; +} +``` + +### Redirect HTTP→HTTPS + +```nginx +server { + listen 80; + server_name example.com www.example.com; + return 301 https://example.com$request_uri; +} +``` + +### Canonical Host + +```nginx +# Force non-www +server { + listen 80; + server_name www.example.com; + return 301 $scheme://example.com$request_uri; +} +``` + +## TLS/SSL {.cols-3} + +### Basic TLS Server + +```nginx +server { + listen 443 ssl http2; + server_name example.com; + + ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_prefer_server_ciphers off; + + root /var/www/example/public; +} +``` + +### HSTS & Security Headers + +```nginx +add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always; +add_header X-Content-Type-Options "nosniff" always; +add_header X-Frame-Options "SAMEORIGIN" always; +add_header Referrer-Policy "no-referrer-when-downgrade" always; +add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always; +``` + +### Let’s Encrypt (Certbot) + +```shell script +$ sudo apt install -y certbot python3-certbot-nginx +$ sudo certbot --nginx -d example.com -d www.example.com +$ sudo systemctl list-timers | grep certbot # auto-renew +``` + +## Reverse Proxy {.cols-3} + +### Basic Proxy + +```nginx +upstream app { + server 127.0.0.1:3000; + # server unix:/run/app.sock; # alternative +} + +server { + listen 80; + server_name api.example.com; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_pass http://app; + } +} +``` + +### WebSockets / HTTP Upgrade + +```nginx +location /socket.io/ { + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_pass http://app; +} +``` + +### Timeouts & Buffers + +```nginx +proxy_connect_timeout 5s; +proxy_send_timeout 60s; +proxy_read_timeout 60s; +proxy_buffering on; +proxy_buffers 16 16k; +proxy_busy_buffers_size 24k; +``` + +## Static, Compression, Caching {.cols-3} + +### Static Files + +```nginx +location /assets/ { + alias /var/www/example/assets/; + access_log off; + expires 7d; + add_header Cache-Control "public, max-age=604800, immutable"; +} +``` + +### Gzip + +```nginx +gzip on; +gzip_types text/plain text/css application/javascript application/json image/svg+xml; +gzip_min_length 1024; +gzip_comp_level 5; +``` + +### (Optional) Brotli (if compiled) + +```nginx +brotli on; +brotli_comp_level 5; +brotli_types text/plain text/css application/javascript application/json image/svg+xml; +``` + +## Caching & Microcaching {.cols-3} + +### Proxy Cache Zone + +```nginx +proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=micro:10m max_size=1g inactive=10m use_temp_path=off; +map $request_method $no_cache { default 0; POST 1; PUT 1; PATCH 1; DELETE 1; } +``` + +### Use the Cache + +```nginx +location /api/ { + proxy_cache micro; + proxy_cache_bypass $no_cache; + proxy_no_cache $no_cache; + proxy_cache_valid 200 301 302 10s; + proxy_cache_valid any 1s; + add_header X-Cache-Status $upstream_cache_status; + proxy_pass http://app; +} +``` + +### Conditional Bypass + +```nginx +# Skip cache when logged in (example cookie) +map $http_cookie $logged_in { + default 0; + ~*"(session|auth|logged_in)" 1; +} +proxy_cache_bypass $logged_in; +proxy_no_cache $logged_in; +``` + +## PHP‑FPM / FastCGI {.cols-3} + +### Basic PHP Handler + +```nginx +location ~ \.php$ { + include fastcgi_params; + fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; + fastcgi_param DOCUMENT_ROOT $realpath_root; + fastcgi_pass unix:/run/php/php8.2-fpm.sock; + fastcgi_buffers 16 16k; + fastcgi_read_timeout 60s; +} +``` + +### try_files Front Controller + +```nginx +location / { + try_files $uri $uri/ /index.php?$args; +} +``` + +### Security Tips + +```nginx +location ~* \.(?:ini|log|sh|sql|bak)$ { deny all; } +location ~ /\.(?!well-known) { deny all; } +``` + +## Rewrites & Routing {.cols-3} + +### try_files + +```nginx +location / { + try_files $uri $uri/ /index.html; +} +``` + +### Regex Rewrites + +```nginx +# Remove trailing slash (except root) +if ($request_uri ~* "^(.+)/+$") { return 301 $1; } + +# Legacy path to new path +rewrite ^/old/(.*)$ /new/$1 permanent; +``` + +### SPA / History API + +```nginx +location / { + try_files $uri /index.html; +} +``` + +## Rate Limiting & DoS Mitigation {.cols-3} + +### Request Rate + +```nginx +# 10 req/s with burst 20 per IP +limit_req_zone $binary_remote_addr zone=reqs:10m rate=10r/s; + +server { + location /api/ { + limit_req zone=reqs burst=20 nodelay; + } +} +``` + +### Concurrent Connections + +```nginx +limit_conn_zone $binary_remote_addr zone=conns:10m; +server { + location /download/ { + limit_conn conns 10; + } +} +``` + +### Body Size & Timeouts + +```nginx +client_max_body_size 25m; +client_body_timeout 30s; +keepalive_timeout 65s; +``` + +## Security Headers & Access {.cols-3} + +### Basic Hardening + +```nginx +server_tokens off; +add_header X-Content-Type-Options "nosniff" always; +add_header X-Frame-Options "SAMEORIGIN" always; +add_header Referrer-Policy "no-referrer-when-downgrade" always; +``` + +### Allow/Deny + +```nginx +location /admin/ { + allow 192.168.0.0/16; + deny all; +} +``` + +### CORS (Example) + +```nginx +location /api/ { + add_header Access-Control-Allow-Origin "https://app.example.com" always; + add_header Access-Control-Allow-Credentials "true" always; + if ($request_method = OPTIONS) { + add_header Access-Control-Allow-Methods "GET, POST, OPTIONS"; + add_header Access-Control-Allow-Headers "Authorization, Content-Type"; + return 204; + } + proxy_pass http://app; +} +``` + +## Logging & Debug {.cols-3} + +### Formats + +```nginx +log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for" ' + '$request_time $upstream_response_time'; + +access_log /var/log/nginx/access.log main; +error_log /var/log/nginx/error.log warn; +``` + +### Per‑Location Logging + +```nginx +location /healthz { access_log off; } +``` + +### Debugging + +```shell script +$ sudo nginx -t +$ sudo nginx -s reload +$ tail -f /var/log/nginx/error.log +``` + +## Upstreams & LB {.cols-3} + +### Strategies + +| Directive | Meaning | +| ------------- | ----------------------- | +| (default) | round‑robin | +| `least_conn` | least connections | +| `ip_hash` | sticky by client IP | +| `hash key` | hash by custom key | + +{.show-header} + +### Example Upstream + +```nginx +upstream api_backends { + least_conn; + server 10.0.0.11:8080 max_fails=3 fail_timeout=30s; + server 10.0.0.12:8080 max_fails=3 fail_timeout=30s; + # server backup.example:8080 backup; +} +``` + +### Health & Failover + +```nginx +proxy_next_upstream error timeout http_502 http_503 http_504; +proxy_next_upstream_tries 3; +``` + +## Useful Variables {.cols-3} + +### Request & Client + +| Variable | Description | +| --------------------- | ---------------------------- | +| `$host` | Host header / server name | +| `$server_name` | Chosen server_name | +| `$remote_addr` | Client IP | +| `$http_user_agent` | User‑Agent | +| `$request_method` | GET/POST/... | + +{.show-header .bold-first} + +### Paths & Files + +| Variable | Description | +| ----------------------- | ---------------------- | +| `$document_root` | Current root | +| `$realpath_root` | Symlink‑resolved root | +| `$request_uri` | Path + query | +| `$uri` | Normalized URI | +| `$args` | Raw query string | + +{.show-header .bold-first} + +### Upstream + +| Variable | Description | +| -------------------------- | ------------------ | +| `$upstream_addr` | Upstream server(s) | +| `$upstream_status` | Upstream status | +| `$upstream_response_time` | Time from upstream | + +{.show-header .bold-first} + +## Stream (TCP/UDP) {.cols-3} + +### TCP Proxy + +```nginx +stream { + upstream db { + server 10.0.0.10:5432; + server 10.0.0.11:5432; + } + server { + listen 5432; + proxy_pass db; + } +} +``` + +### UDP Proxy + +```nginx +stream { + server { + listen 53 udp; + proxy_responses 1; + proxy_timeout 2s; + proxy_pass 1.1.1.1:53; + } +} +``` + +### Access Control + +```nginx +stream { + server { + listen 6379; + allow 10.0.0.0/8; + deny all; + proxy_pass 127.0.0.1:6379; + } +} +``` + +## Snippets {.cols-3} + +### Security Snippet + +```nginx +# /etc/nginx/snippets/security.conf +server_tokens off; +add_header X-Content-Type-Options "nosniff" always; +add_header X-Frame-Options "SAMEORIGIN" always; +add_header Referrer-Policy "no-referrer-when-downgrade" always; +``` + +### PHP Snippet + +```nginx +# /etc/nginx/snippets/fastcgi-php.conf +location ~ \.php$ { + include fastcgi_params; + fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; + fastcgi_param DOCUMENT_ROOT $realpath_root; + fastcgi_pass unix:/run/php/php8.2-fpm.sock; +} +``` + +### Proxy Headers Snippet + +```nginx +# /etc/nginx/snippets/proxy-headers.conf +proxy_set_header Host $host; +proxy_set_header X-Real-IP $remote_addr; +proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +proxy_set_header X-Forwarded-Proto $scheme; +``` +