🚀 Taegi Taeknology

Nginx 필수 명령어

18 min read

Nginx는 고성능 웹 서버, 리버스 프록시, 로드 밸런서, HTTP 캐시 등으로 널리 사용되는 강력한 소프트웨어입니다. Nginx를 효과적으로 운영하고 관리하기 위해서는 주요 명령어들과 그 사용법을 숙지하는 것이 필수적입니다. 이 가이드에서는 Nginx 관리자가 자주 사용하는 유용한 명령어들과 각 명령어가 어떤 상황에서 유용한지 시나리오 중심으로 설명합니다.

1. 설정 파일 문법 검사: nginx -t

Nginx 설정을 변경한 후에는 반드시 문법 오류가 없는지 확인해야 합니다. 이 명령어를 사용하면 Nginx를 실제로 재시작하거나 설정을 다시 불러오기 전에 설정 파일의 유효성을 검사할 수 있습니다.

sudo nginx -t

또는 (설정 파일 경로를 명시적으로 지정할 경우):

sudo nginx -t -c /etc/nginx/nginx.conf

유용한 시나리오:

  • 설정 변경 후: server 블록 추가/수정, location 지시어 변경, SSL 인증서 경로 수정 등 Nginx 설정 파일(nginx.conf 또는 sites-available/ 내의 파일 등)을 수정한 후 적용하기 전에 항상 실행합니다.

  • 오류 발생 시: Nginx가 시작되지 않거나 reload에 실패할 때, 이 명령어를 통해 어떤 설정 파일의 어느 부분에서 문제가 발생했는지 구체적인 오류 메시지를 확인할 수 있습니다.

성공 시 출력 예시:

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

2. Nginx 서비스 시작: systemctl start nginx 또는 nginx

Nginx 서비스를 시작합니다. 시스템 부팅 시 자동으로 시작되도록 설정되어 있지 않거나, 중지된 상태에서 다시 실행할 때 사용합니다.

sudo systemctl start nginx

만약 systemd를 사용하지 않는 구형 시스템이거나 직접 바이너리를 실행하는 경우:

sudo nginx

유용한 시나리오:

  • 최초 설치 후: Nginx를 처음 설치하고 실행할 때.

  • 서버 재부팅 후: Nginx 서비스가 자동으로 시작되지 않도록 설정된 경우 서버 재부팅 후 수동으로 시작할 때.

  • 서비스 중단 후: 유지보수 등의 이유로 Nginx를 중지했다가 다시 서비스를 개시할 때.

3. Nginx 서비스 중지: systemctl stop nginx 또는 nginx -s stop

실행 중인 Nginx 서비스를 중지합니다.

sudo systemctl stop nginx

또는 (빠른 종료, 현재 연결 즉시 종료):

sudo nginx -s stop

유용한 시나리오:

  • 서버 유지보수: Nginx와 관련된 주요 시스템 변경 작업이나 긴급한 서버 점검 시 서비스를 일시 중단해야 할 때.

  • 포트 충돌 해결: 다른 서비스가 Nginx가 사용하는 포트(기본 80, 443)를 사용해야 할 경우 임시로 중지할 때.

4. Nginx 서비스 재시작: systemctl restart nginx

Nginx 서비스를 완전히 중지했다가 다시 시작합니다. 이 과정에서 아주 짧은 시간 동안 서비스 중단이 발생할 수 있습니다.

sudo systemctl restart nginx

유용한 시나리오:

  • reload 실패 시: nginx -s reload 명령으로 설정 변경 사항이 제대로 적용되지 않거나 오류가 발생할 때.

  • Nginx 모듈 변경 시: Nginx 모듈을 추가하거나 제거하는 등 Nginx 바이너리 자체에 변경이 있었을 때.

  • 심각한 문제 발생 시: Nginx가 불안정하게 동작하거나 원인 불명의 문제가 발생했을 때 초기화 개념으로 재시작을 시도할 수 있습니다.

5. Nginx 설정 다시 불러오기 (Graceful Reload): systemctl reload nginx 또는 nginx -s reload

이 명령어는 Nginx 관리에서 매우 중요하고 자주 사용됩니다. 실행 중인 Nginx 마스터 프로세스에게 설정 파일을 다시 읽어오도록 지시합니다. 기존 연결은 유지하면서 새로운 설정을 적용하므로, 서비스 중단 없이 변경 사항을 반영할 수 있습니다.

sudo systemctl reload nginx

또는:

sudo nginx -s reload

유용한 시나리오:

  • 설정 파일 변경 적용: 가상 호스트 추가/수정, 리다이렉션 규칙 변경, SSL 인증서 파일 교체, location 블록 수정 등 nginx.conf 또는 관련 설정 파일을 변경한 후 서비스 중단 없이 적용하고 싶을 때. (인증서 교체 후 유효 기간이 변경되지 않을 때 이 명령어를 실행해야 합니다.)

  • 로그 파일 로테이션: 로그 파일을 수동으로 로테이션한 후 Nginx가 새로운 로그 파일을 사용하도록 할 때 (Nginx는 USR1 시그널을 받으면 로그 파일을 다시 엽니다. reload는 이 시그널을 포함합니다).

주의: reload 전에 항상 nginx -t 명령으로 설정 파일의 문법을 검사하는 것이 좋습니다. 문법 오류가 있는 상태에서 reload를 시도하면 실패하고, 최악의 경우 Nginx가 중단될 수도 있습니다.

6. Nginx 서비스 상태 확인: systemctl status nginx

Nginx 서비스의 현재 실행 상태, PID(프로세스 ID), 최근 로그 등을 확인할 수 있습니다.

sudo systemctl status nginx

유용한 시나리오:

  • Nginx 실행 여부 확인: Nginx가 정상적으로 실행 중인지, 아니면 중단되었는지 확인할 때.

  • 오류 확인: Nginx 시작 실패 또는 reload 실패 시 관련 오류 메시지를 빠르게 확인할 때.

  • 서비스 활성화 여부 확인: 시스템 부팅 시 Nginx가 자동으로 시작되도록 설정되어 있는지 확인할 때.

7. Nginx 버전 확인: nginx -v 및 nginx -V

설치된 Nginx의 버전을 확인합니다.

  • 간단한 버전 정보만 표시:

    nginx -v

    출력 예시: nginx version: nginx/1.18.0 (Ubuntu)

  • 버전 정보와 함께 컴파일 시 적용된 설정 옵션까지 자세히 표시:

    nginx -V

    출력 예시 (일부):

    nginx version: nginx/1.18.0 (Ubuntu)
built by gcc 9.3.0 (Ubuntu 9.3.0-17ubuntu1~20.04)
built with OpenSSL 1.1.1f  31 Mar 2020
TLS SNI support enabled
configure arguments: --with-cc-opt=... --with-http_ssl_module --with-http_v2_module ...

유용한 시나리오:

  • 호환성 확인: 특정 기능이나 모듈이 현재 설치된 Nginx 버전에서 지원되는지 확인할 때.

  • 보안 취약점 점검: 사용 중인 Nginx 버전에 알려진 보안 취약점이 있는지 확인할 때.

  • 문제 해결: 특정 컴파일 옵션(예: --with-http_ssl_module)이 포함되어 있는지 확인하여 SSL 관련 문제 등을 진단할 때.

8. Nginx 서비스 활성화/비활성화 (시스템 부팅 시 자동 시작 설정)

시스템 부팅 시 Nginx 서비스를 자동으로 시작하거나 시작하지 않도록 설정합니다.

  • 자동 시작 활성화:

    sudo systemctl enable nginx

  • 자동 시작 비활성화:

    sudo systemctl disable nginx

유용한 시나리오:

  • 서버 운영 정책 변경: 서버 부팅 후 Nginx를 자동으로 시작할지 여부를 결정할 때.

  • 문제 해결 중 임시 비활성화: 특정 문제로 인해 Nginx 자동 시작을 잠시 막아야 할 때.

9. Nginx 모니터링 관련 명령어 및 기법

Nginx의 상태를 파악하고 문제를 진단하기 위한 모니터링은 매우 중요합니다. 다음은 Nginx 모니터링에 유용한 명령어와 기법입니다.

가. 실시간 로그 확인: tail -f

Nginx 접근 로그(access log)나 오류 로그(error log)를 실시간으로 확인하여 현재 발생하는 요청이나 오류를 즉시 파악할 수 있습니다.

  • 접근 로그 실시간 확인:

    sudo tail -f /var/log/nginx/access.log

  • 오류 로그 실시간 확인:

    sudo tail -f /var/log/nginx/error.log

    (로그 파일 경로는 Nginx 설정에 따라 다를 수 있습니다.)

유용한 시나리오:

  • 특정 요청 문제 해결: 사용자가 특정 페이지 접근 시 오류를 겪을 때, 실시간 로그를 보며 해당 요청이 서버에 도달하는지, 어떤 응답 코드를 반환하는지, 오류가 발생하는지 등을 즉시 확인할 수 있습니다.

  • 트래픽 급증 확인: 갑작스러운 트래픽 변화나 특정 IP 주소로부터의 과도한 요청 등을 실시간으로 감지할 수 있습니다.

  • 배포 후 즉각적인 오류 감지: 새로운 코드를 배포하거나 설정을 변경한 직후 발생할 수 있는 오류를 빠르게 파악할 수 있습니다.

나. Nginx 상태 모듈 (Stub Status Module)

Nginx는 ngx_http_stub_status_module이라는 모듈을 통해 기본적인 서버 상태 정보를 제공할 수 있습니다. 이 모듈은 컴파일 시 포함되어야 하며, 설정을 통해 특정 URL에서 상태 정보를 확인할 수 있도록 해야 합니다.

  • 설정 예시 (nginx.conf 또는 가상 호스트 설정 파일 내):

    location /nginx_status {
    stub_status;
    allow 127.0.0.1; # 로컬에서만 접근 허용
    # allow your_monitoring_ip; # 특정 IP에서만 접근 허용
    deny all;       # 그 외 모든 접근 차단
}

    위 설정 후 Nginx를 reload하면 http://your_server_ip/nginx_status (또는 설정한 주소)로 접속하여 상태 정보를 볼 수 있습니다.

  • 확인 가능한 정보:

    • Active connections: 현재 활성화된 클라이언트 연결 수.

    • server accepts handled requests: (누적) 처리한 총 연결 수, 성공적으로 처리된 연결 수, 총 요청 수.

    • Reading: Nginx가 요청 헤더를 읽고 있는 연결 수.

    • Writing: Nginx가 클라이언트에 응답을 쓰고 있는 연결 수.

    • Waiting: Keep-alive 상태로 대기 중인 유휴 클라이언트 연결 수.

유용한 시나리오:

  • 기본적인 서버 부하 상태 확인: 현재 Nginx가 얼마나 많은 연결을 처리하고 있는지, 대기 중인 연결은 얼마나 되는지 등의 기본적인 부하 상태를 빠르게 파악할 수 있습니다.

  • 간단한 모니터링 시스템 연동: 이 URL을 주기적으로 호출하여 Nginx 상태를 모니터링하는 간단한 스크립트나 도구와 연동할 수 있습니다.

주의: stub_status 페이지는 서버의 내부 정보를 노출할 수 있으므로, allow와 deny 지시어를 사용하여 접근 제어를 철저히 해야 합니다.

다. 시스템 레벨 모니터링 도구 활용

Nginx 자체의 모니터링 외에도, 시스템 전체의 리소스 사용량을 파악하는 것이 중요합니다.

  • top 또는 htop:

    실시간으로 시스템의 프로세스 목록과 CPU, 메모리 사용량 등을 보여줍니다. Nginx 워커 프로세스들이 CPU나 메모리를 과도하게 사용하는지 확인할 수 있습니다.

    top
htop # top보다 사용하기 편리한 인터페이스 제공 (설치 필요: sudo apt install htop)

  • netstat 또는 ss:

    네트워크 연결 상태, 리스닝 소켓, 라우팅 테이블 등을 보여줍니다. Nginx가 사용하는 포트(80, 443)가 정상적으로 리스닝 중인지, 특정 IP와의 연결 상태 등을 확인할 수 있습니다.

    sudo netstat -tulnp | grep nginx # Nginx 관련 리스닝 포트 확인
sudo ss -tulnp | grep nginx     # netstat 대안으로 더 빠르고 상세한 정보 제공

  • vmstat:

    시스템의 메모리, 스왑, I/O, CPU 활동 등에 대한 통계를 보여줍니다.

    vmstat 1 # 1초 간격으로 통계 출력

  • iostat:

    CPU 사용 통계 및 디스크 I/O 통계를 보여줍니다. Nginx가 정적 파일을 많이 서비스하거나 로그를 많이 기록할 때 디스크 I/O 병목 현상이 있는지 확인할 수 있습니다.

    iostat -xz 1 # 1초 간격으로 확장된 디스크 통계 출력 (sysstat 패키지 필요)

유용한 시나리오:

  • 성능 병목 지점 파악: Nginx 응답이 느릴 때, CPU, 메모리, 네트워크, 디스크 I/O 중 어디에서 병목이 발생하는지 시스템 전반의 상황을 파악하여 원인을 좁힐 수 있습니다.

  • 리소스 고갈 문제 진단: 메모리 부족, CPU 사용률 과다 등의 문제를 진단하고 Nginx 워커 프로세스 수 조정 등의 조치를 취할 수 있습니다.

라. 전문 모니터링 솔루션 활용 (예: Prometheus, Grafana, Datadog, New Relic)

더 체계적이고 시각적인 모니터링을 위해서는 전문 모니터링 도구를 사용하는 것이 좋습니다. 이러한 도구들은 Nginx의 상세한 메트릭을 수집하고, 대시보드를 통해 시각화하며, 임계치 기반 알림 설정 등의 고급 기능을 제공합니다.

  • Nginx Exporter for Prometheus: Prometheus와 함께 사용하여 Nginx 메트릭을 수집할 수 있습니다.

로그 파일 위치 (참고)

Nginx의 기본 로그 파일 위치는 일반적으로 다음과 같습니다. 문제 해결 시 이 로그들을 확인하는 것이 중요합니다.

  • Access Log (접근 로그): /var/log/nginx/access.log

  • Error Log (오류 로그): /var/log/nginx/error.log

설정 파일에서 로그 경로를 변경했을 수도 있으므로, nginx.conf 파일을 확인하여 정확한 경로를 파악해야 합니다.

결론

위에 소개된 명령어들은 Nginx를 효과적으로 관리하고 문제를 해결하는 데 필수적입니다. 특히 nginx -t로 설정을 검사하고 nginx -s reload (또는 systemctl reload nginx)로 서비스 중단 없이 설정을 적용하는 습관은 안정적인 웹 서비스 운영에 큰 도움이 됩니다. 또한, 실시간 로그 분석, stub_status 활용, 시스템 레벨 모니터링을 통해 Nginx의 상태를 꾸준히 관찰하고 문제 발생 시 신속하게 대응하는 것이 중요합니다. 각 명령어의 사용법과 적절한 시나리오를 잘 이해하고 활용하여 Nginx를 능숙하게 다루시길 바랍니다.

그래프 뷰

최근 게시글