NGINX 의 ngx_http_sub_module 모듈을 통한 응답 본문 수정

NGINX 는 다양한 모듈을 통해 기능을 확장할 수 있습니다. 그중 ngx_http_sub_module 모듈은 HTTP 응답 본문에서 특정 문자열을 동적으로 찾아 교체하는 데 유용합니다.

이를 통해 NGINX를 이용한 응답 본문 수정이 가능하며, 웹사이트 콘텐츠의 동적 변환 및 간단한 텍스트 교체 작업을 효율적으로 처리할 수 있습니다.

이 블로그 포스트에서는 ngx_http_sub_module 모듈을 활용하여 NGINX에서 응답 본문을 수정하는 방법을 소개하고, 이를 설정하는 과정과 주요 사용 사례를 다룹니다.

목차

1. NGINX ngx_http_sub_module 모듈 개요
 1-1. ngx_http_sub_module의 주요 기능
 1-2. ngx_http_sub_module 활성화
2. NGINX ngx_http_sub_module을 통한 응답 본문 수정
3. 결론 및 요약

1. NGINX ngx_http_sub_module 모듈 개요

NGINX 의 ngx_http_sub_module 모듈을 통한 응답 본문 수정

ngx_http_sub_module 모듈은 NGINX에서 HTTP 응답 본문을 동적으로 수정할 수 있도록 지원하는 기능을 제공합니다.

이 모듈을 통해 특정 문자열을 찾아 다른 문자열로 치환하거나, 조건에 따라 응답 본문을 변경할 수 있습니다. 기본적으로 정규 표현식을 지원하여 보다 유연한 문자열 매칭과 수정이 가능하며, 다양한 웹 애플리케이션과 함께 사용할 수 있습니다.

이 목차에서는 ngx_http_sub_module의 주요 기능과 이를 활성화하는 방법에 대해 설명합니다.

1-1. ngx_http_sub_module의 주요 기능

ngx_http_sub_module은 HTTP 응답 본문에서 특정 문자열을 동적으로 찾아 다른 문자열로 대체할 수 있는 기능을 제공합니다.

이를 통해 서버 응답 내용의 일부를 실시간으로 수정하거나, 특정 조건에 따라 다른 정보를 출력하는 것이 가능합니다. 이 모듈은 정규 표현식을 지원하여 복잡한 문자열 패턴을 매칭할 수 있으며, 이를 활용해 다양한 시나리오에 맞게 응답 본문을 변경할 수 있습니다.

이를 통해 NGINX 서버에서 보다 유연하고 효율적인 콘텐츠 관리가 가능합니다.

1-2. ngx_http_sub_module 활성화

먼저, NGINX에서 해당 모듈이 지원되는지 확인해야 합니다. ngx_http_sub_module은 기본적으로 NGINX에 포함되어 있지만, 설치된 버전에 따라 다를 수 있으므로 확인하는 것이 중요합니다.

nginx -V 2>&1 | grep --color -o 'http_sub_module'

위 명령어를 실행했을 때 출력 결과에 http_sub_module이 나타나면 모듈이 포함되어 있는 것입니다.

이제 NGINX 구성 파일을 열고 아래를 참고하여 필요에 따라 sub_filter 지시문을 삽입합니다.

Syntax:	sub_filter string replacement;

Default:	—
Context:	http, server, location

sub_filter

대소문자를 구분하지 않고 교체할 문자열과 대체 문자열을 설정합니다. 교체할 문자열(1.9.4)과 대체 문자열에는 변수를 포함할 수 있습니다. 여러 개의 sub_filter 지시문을 동일한 설정 레벨에서 지정할 수 있으며(1.9.4), 현재 레벨에 sub_filter 지시문이 정의되지 않은 경우에만 이전 설정 레벨에서 이 지시문이 상속됩니다.

Syntax:	sub_filter_last_modified on | off;

Default:	
sub_filter_last_modified off;
Context:	http, server, location
This directive appeared in version 1.5.1.

sub_filter_last_modified

원본 응답의 “Last-Modified” 헤더 필드를 교체 중에도 유지하여 응답 캐싱을 용이하게 합니다.

기본적으로는 응답의 내용이 처리 중에 변경되기 때문에 해당 헤더 필드가 제거됩니다.

Syntax:	sub_filter_once on | off;

Default:	
sub_filter_once on;
Context:	http, server, location

sub_filter_once

교체할 문자열을 한 번만 찾을지 반복적으로 찾을지 여부를 나타냅니다.

Syntax:	sub_filter_types mime-type ...;

Default:	
sub_filter_types text/html;
Context:	http, server, location

sub_filter_types

“text/html” 외에 지정된 MIME 타입의 응답에서도 문자열 교체를 활성화합니다. 특별 값 “*”는 모든 MIME 타입과 일치합니다 (0.8.29).

2. NGINX ngx_http_sub_module을 통한 응답 본문 수정

다음은 sub_filter 모듈을 적용한 NGINX 구성 파일입니다.

NGINX STORE GitHub – nginx-sub-filter.conf

server {
    listen       80;
    server_name localhost;

    access_log  /var/log/nginx/host.access.log  main;

    root /usr/share/nginx/html/;

    location / {
        index test.html;
        sub_filter 'alex@example.com' '***@example.com';
        sub_filter '1234-5678-9101-1121' '1234-****-9101-****'; # 카드번호 마스킹
        sub_filter_once off; # 여러 번 등장하는 경우에도 대체하도록 설정
    }

    #error_page  404              /404.html;

    # redirect server error pages to the static page /50x.html
    #
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

HTML의 응답 중 특정 문자열을 sub_filter 모듈로 마스킹합니다.

# curl localhost

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>User Name : Alex</p>
<p>User Email : ***@example.com</p>
<p>Credit Card Number : 1234-****-9101-****</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

sub_filter 지시문을 주석처리하고 요청할 시 응답 마스킹이 되지 않습니다.

# curl localhost
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>User Name : Alex</p>
<p>User Email : alex@example.com</p>
<p>Credit Card Number : 1234-5678-9101-1121</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

3. 결론 및 요약

이 포스트에서는 NGINX의 ngx_http_sub_module 모듈을 활용하여 HTTP 응답 본문을 수정하는 방법에 대해 살펴보았습니다.

sub_filter 지시자를 사용해 특정 문자열을 대소문자 구분 없이 대체하고, 정규 표현식과 변수를 활용해 더욱 유연한 설정이 가능합니다.

이를 통해 동적 콘텐츠 수정, 로케일 변경, 마케팅 캠페인 텍스트 업데이트 등 다양한 실무 활용 사례에서 효율적으로 사용할 수 있습니다.

다양한 NGINX 사용 사례를 알아보려면 NGINX STORE 블로그의 NGINX 카테고리를 참조하세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required