mirror of
https://github.com/Fechin/reference.git
synced 2026-11-20 21:23:11 +03:00
1 file changed
+587
@@ -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;
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user