NGINX addition module 활용 응답의 전/후 텍스트 추가 가이드

이 포스트에서는 NGINX addition module 을 활용하여, HTML 응답 본문의 앞/뒤에 텍스트를 추가하는 방법에 관해 설명합니다. 이 모듈을 통해 응답에 HTML 코드를 삽입하여 헤더/푸터와 같은 고정된 내용을 추가할 수 있습니다.

해당 모듈은 NGINX OSS/Plus 모두 사용 가능합니다. 패키지 설치 시 자동으로 빌드되나, 컴파일 설치 시 --with-http_addition_module 매개변수를 통해 빌드해야 합니다.

목차

1. NGINX addition module 이란?
 1-1. NGINX addition module 지시문
2. NGINX addition module로 응답에 텍스트 추가
3. 결론

1. NGINX addition module 이란?

NGINX addition module(ngx_http_addition_module)은 응답 본문의 앞/뒤에 텍스트를 추가하는 필터 모듈로, 이 모듈을 사용하여 응답에 HTML 코드를 삽입할 수 있습니다. 이를 통해 헤더나 푸터처럼 응답에 고정된 내용을 추가할 수 있습니다. 기본값은 text/html MIME 타입의 응답에 추가하도록 설정되어 있으나, 설정을 적용할 MIME 타입을 설정할 수도 있습니다.

1-1. NGINX addition module 지시문

1. add_before_body uri;
기본 : –
컨텍스트 : http, server, location

응답 본문의 앞에 텍스트를 추가합니다. 빈 문자열(“”)로 설정하면 상위 컨텍스트에서 상속된 추가 설정이 취소됩니다.

2. add_after_body uri;
기본 : –
컨텍스트 : http, server, location

응답 본문의 뒤에 텍스트를 추가합니다. 빈 문자열(“”)로 설정하면 상위 컨텍스트에서 상속된 추가 설정이 취소됩니다.

3. addition_types mime-type …;
기본 : addition_types text/html;
컨텍스트 : http, server, location

모듈을 적용할 응답의 MIME 타입을 지정합니다. * 값으로 설정 시 모든 MIME 타입에 설정됩니다.

2. NGINX addition module로 응답에 텍스트 추가

모듈을 사용하여 응답에 텍스트를 추가하기 전의 NGINX 서버는 다음과 같은 페이지를 표시하도록 구성했습니다.

모듈을 통해 응답의 앞/뒤에 추가할 텍스트는 다음 HTML 파일들로 구성했습니다.

head-banner.html

<div class="intro-banner" style="
    position: relative;
    width: 100%;
    padding: 20px;
    text-align: center;
    border-bottom: 2px solid #00acc1;
">
    <h2 style="color: #4380a9; font-size: 1.8em; margin: 0;">NGINX addition module</h2>
</div>

단순한 텍스트가 포함된 HTML 파일입니다.

banner.html

<div class="announcement-banner" style="
    position: fixed;
    bottom: 0;
    left: 0;
    width: 100%;
    background: #f8d7da;
    padding: 10px;
    text-align: center;
    z-index: 9999;
">
    <p style="color: #000;">🔔 시스템 점검 안내: 2024년 12월 25일 02:00 ~ 04:00</p>
</div>

시스템 점검 공지를 나타내는 형식의 HTML 파일입니다.

기존 페이지로 요청을 프록시 하면서, 위의 HTML 파일을 응답의 앞/뒤에 추가하도록 설정 파일을 구성했습니다.

banner.conf

server {
        listen 801;

        root /usr/share/nginx/html; # HTML 파일 디렉토리 설정
        charset utf-8;              # 한글 깨짐 방지를 위한 html 설정

        addition_types text/html; # 기본 설정
        add_before_body /head-banner.html; # 응답의 앞에 설정할 텍스트
        add_after_body  /banner.html;      # 응답의 뒤에 설정할 텍스트

        location / {
                proxy_pass http://192.168.200.176;  # 기존 페이지로 요청 프록시
        }

        location /nginx {
                alias /usr/share/nginx/html;  # 지정 디렉토리에서 index 파일을 찾도록 설정
                index default_index.html;

                add_after_body ""; # server 블록에 정의된 add_after_body 지시문 취소
        }
}

• server 블록 내부의 text/html 형식의 응답에 텍스트가 추가됩니다.
• 응답의 앞에는 /usr/share/nginx/html/head-banner.html 파일의 내용이 추가됩니다.
• 응답의 뒤에는 /usr/share/nginx/html/banner.html 파일의 내용이 추가됩니다.
• / 경로 요청 시 응답의 앞/뒤에 모두 추가됩니다.
• alias 지시문을 통해 /nginx 경로 요청 시 /usr/share/nginx/html/nginx 디렉토리가 아닌, /usr/share/nginx/html 디렉토리에서 index 파일을 찾습니다.
• /nginx 경로 요청 시 NGINX 기본 페이지를 반환하며, 응답의 앞에만 내용이 추가됩니다.

설정을 적용 후 801번 포트를 통해 접속합니다.

응답의 앞/뒤에 모두 HTML 파일이 추가되어 위와 같이 나타납니다.

/nginx 경로 접속 시 위와 같이 응답의 앞에만 HTML 파일이 추가됩니다.
location 블록 내부의 add_after_body ""; 지시문을 통해 server 블록의 응답 추가 설정을 취소하여, 해당 location의 응답 뒤에는 파일이 추가되지 않습니다.

3. 결론

이번 포스트에서는 NGINX addition module을 사용하여 HTML 응답의 전/후에 텍스트를 추가하는 방법을 알아봤습니다. 추가할 텍스트로 HTML 파일을 설정하여, 웹 페이지에 헤더/푸터를 삽입하듯이 활용했습니다.

NGINX addition module의 지시문은 http, server, location 블록에 모두 사용할 수 있어 NGINX 서버 전체에 일관되게, 혹은 일부에 적용할 수 있습니다. 또한 지시문의 값을 빈값(“”)으로 설정하여 서버 전체에 적용하면서 일부 경로만 제외하여 적용하도록 설정할 수 있습니다. 예시와 같이 시스템 점검을 나타내는 배너를 손쉽게 전체 응답에 추가하도록 활용할 수 있습니다.

NGINX addition module을 포함한 다양한 기능이 있는 NGINX OSS의 엔터프라이즈 버전인 NGINX Plus를 체험해 보고 싶으시다면 NGINX STORE를 통해 문의해 무료로 NGINX Plus trial을 체험해 보세요.