NGINX Config

NGINX 설정 파일을 작성할 때 자주 필요한 기본 형식, context 구조, 핵심 필드, 검증 절차를 정리한다.

• NGINX 설정은 directive; 단위와 block { … } 단위로 구성된다.
• 최소한 HTTP 서버를 쓰려면 보통 전역 영역, events, http, server, location 계층을 이해해야 한다.
• 저장 후에는 항상 nginx -t 로 문법과 include 경로를 먼저 검증한 뒤 reload 하는 편이 안전하다.

• 한 줄 directive는 세미콜론 ;
• block directive는 중괄호 { }
• 주석은 #
• include는 다른 설정 파일을 병합한다.

user nginx;
worker_processes auto;
 
events {
    worker_connections 1024;
}
 
http {
    include /etc/nginx/mime.types;
 
    server {
        listen 80;
        server_name example.com;
 
        location / {
            root /srv/www/example;
            index index.html;
        }
    }
}

• main: 파일 최상위 영역. 프로세스, 로그, include, worker 수 같은 전역 설정을 둔다.
• events: connection 처리 방식과 동시 연결 수를 제어한다.
• http: HTTP 공통 동작, MIME, logging, timeout, gzip, upstream, server block을 둔다.
• server: virtual host 단위다. listen, server_name, root, TLS, redirect, proxy 정책을 정의한다.
• location: URI path 매칭 단위다. 정적 파일 제공, reverse proxy, rewrite, fallback을 정의한다.

• user: worker process 실행 계정
• worker_processes: worker 수. 보통 auto
• error_log: 에러 로그 경로와 레벨
• pid: master PID 파일 경로
• include: 모듈 또는 분리 설정 파일 로드

• worker_connections: worker당 동시 연결 수
• multi_accept: 가능한 연결을 한 번에 더 많이 accept 할지 여부
• use: 이벤트 처리 모델 지정(epoll 등). 보통 자동 선택에 맡기는 편이 많다.

• include /etc/nginx/mime.types: MIME type 로드
• default_type: 확장자 매칭 실패 시 기본 Content-Type
• log_format: access log 포맷 정의
• access_log: access log 경로와 포맷
• sendfile: 커널 레벨 파일 전송 최적화
• keepalive_timeout: keep-alive 유지 시간
• client_max_body_size: 업로드 허용 크기 제한
• gzip: 압축 활성화 여부
• include /etc/nginx/conf.d/*.conf: site/server 분리 구성 시 흔한 패턴

• listen: 수신 포트와 소켓 옵션
• server_name: hostname 매칭 규칙
• root: 문서 루트
• index: 기본 인덱스 파일
• charset: 응답 문자셋 기본값
• error_page: 에러 응답별 대체 페이지
• return: 즉시 redirect 또는 상태 코드 반환
• ssl_certificate, ssl_certificate_key: TLS 인증서와 키 경로

• try_files: 정적 파일 존재 확인 후 fallback
• proxy_pass: upstream으로 reverse proxy
• proxy_set_header: upstream에 전달할 헤더 보정
• fastcgi_pass: PHP-FPM 같은 FastCGI upstream 전달
• alias: URI와 실제 경로를 직접 매핑
• rewrite: URI 재작성

user nginx;
worker_processes auto;
 
events {
    worker_connections 1024;
}
 
http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
 
    server {
        listen 80;
        listen [::]:80;
        server_name example.com www.example.com;
        root /srv/www/example;
        index index.html index.htm;
 
        location / {
            try_files $uri $uri/ =404;
        }
    }
}

server {
    listen 80;
    server_name app.example.com;
 
    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name example.com;
    http2 on;
 
    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;
 
    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

• events { worker_connections …; }
• http { … }
• server { listen; server_name; root; }
• location / { try_files …; } 또는 기본 파일 제공 규칙

• server { listen; server_name; }
• location / { proxy_pass …; }
• upstream 전달 헤더 proxy_set_header

• listen 443 ssl
• server_name
• ssl_certificate
• ssl_certificate_key

• client_max_body_size
• 필요 시 proxy_read_timeout, proxy_send_timeout

• /etc/nginx/nginx.conf 안에 직접 작성

• nginx.conf 에서 include /etc/nginx/conf.d/*.conf;
• site별 server block을 별도 파일로 분리

• Debian/Ubuntu 계열은 sites-available, sites-enabled 패턴을 자주 사용
• RHEL 계열은 conf.d/*.conf 패턴이 흔하다.

nginx -t
nginx -T
nginx -s reload

• -t: 문법과 include 대상 검증
• -T: 최종 병합된 전체 설정 확인
• -s reload: 무중단 재적용 시도

• directive is not allowed here: directive가 잘못된 context에 있다.
• unknown directive: 모듈 미설치, 오타, 버전 차이 가능성이 있다.
• cannot load certificate: 인증서 경로, 권한, 파일 내용 확인이 필요하다.
• 변경이 반영되지 않으면 nginx -T 로 실제 읽는 파일을 확인한다.
• service manager가 다른 config path를 주입하는지 점검한다.
• include된 하위 파일끼리 충돌하는지 확인한다.

• nginx
• nginx.conf
• https
• fallback
• sshd_config

• codex:: 2026-07-15 Added an nginx config overview page focused on configuration format, common fields, templates, and validation flow.