🎯 nginx 동적모듈(dynamic module) 빌드해서 적용하기

정적 모듈 vs 동적 모듈

정적 모듈: Nginx 컴파일 시 소스코드에 포함되어 함께 빌드되며, 항상 메모리에 로드되어 있어서 사용하지 않아도 리소스를 차지한다. 정적모듈은 적용 시 무중단이 불가능하다.
동적 모듈: 별도의 .so 파일로 컴파일되어 필요할 때만 로드하며 유연성이 높고 메모리 효율적이다. 동적모듈은 적용 시 무중단이 가능하다.
 
동적모듈 예시
 

• ngx_http_image_filter_module: 이미지 처리
• ngx_http_geoip_module: IP 기반 지리 정보
• ngx_http_xslt_module: XML/XSLT 변환
• ngx_stream_module: TCP/UDP 로드밸런싱
• ngx_http_perl_module: Perl 스크립트 실행

 

so 파일은 뭘까?

.so 파일은 Shared Object 파일이며, 리눅스/유닉스 시스템에서 사용하는 동적 링크 라이브러리(Dynamic Link Library) 파일이다. 동적모듈 최종 파일이라고 보면 된다.
 

동적모듈의 장점

• 런타임에 로드: 프로그램 실행 중에 필요할 때 메모리에 적재
• 코드 공유: 여러 프로그램이 동일한 .so 파일을 공유해서 사용 가능
• 메모리 효율: 중복 코드를 메모리에 한 번만 로드
• 독립적 업데이트: 메인 프로그램 재컴파일 없이 라이브러리만 교체 가능
• 무중단 배포 가능

 

1. 동적모듈 소스 다운로드

nginx version을 확인해서 이와 맞는 모듈 소스코드를 다운받아 서버에 업로드 한 뒤 파일의 압축을 푼다.
나는 nginx version이 1.28이라서 해당 tar.gz 파일을 다운받았다. (버전이 맞지 않는다면 nignx -t에서 오류 발생하기에 버전 확인 필수!)
C 파일(.c)과 헤더 파일(.h), config 파일 등으로 구성되어 있다.
공식 다운로드 사이트: https://nginx.org/download/

tar -xzvf nginx-1.28.0.tar.gz

 
 

2. 동적모듈 빌드

동적모듈을 빌드할때 각종 오류가 나는데 보통 의존성 라이브러리가 설치되어있지 않아 오류가 발생했다.
어떤 모듈인지에 따라 필요한 의존성 라이브러리는 각각 다르며, 오류 문구에서 나오는 라이브러리를 설치하면 된다.

# Nginx 소스 디렉토리로 이동
cd /usr/local/src/nginx-1.28.0

# configure 실행 (동적 모듈 추가)
# 의존성 라이브러리 설치가 모두 완료되어야 오류없이 실행 가능
./configure --with-compat --with-http_xslt_module=dynamic

# 모듈에 따라 실행 문법 확인
./configure --help | grep {모듈명}

# 모듈만 빌드
# 이 명령으로 .so 파일(공유 라이브러리)이 생성 
# 빌드된 .so 파일은 objs/ 디렉토리에 생성
make modules

# 빌드된 .so 파일을 모듈 디렉토리로 복사
# 모듈을 빌드하면 nginx-1.28.0/objs 디렉토리 밑에 so 파일이 생성된다.
cp objs/ngx_http_geoip2_module.so /usr/lib64/nginx/modules/

 

⭐ 동적모듈 빌드 옵션 설명

./configure

Nginx 빌드 환경을 설정하는 스크립트입니다. Makefile을 /usr/local/src/nginx-1.28.0 디렉토리 안에 생성합니다.

--with-compat

호환성 모드 활성화

• Nginx 바이너리와 동적 모듈 간의 ABI(Application Binary Interface) 호환성을 보장 ( 이미 설치된 Nginx에 나중에 동적 모듈만 따로 추가할 때 필수 옵션)
• 이게 없으면 모듈이 제대로 로드되지 않을 수 있음

--with-http_xslt_module=dynamic

XSLT 모듈을 동적 모듈로 빌드

• 모듈에 따라서 --with-{모듈명}=dynamic 형식
• --with-http_xslt_module: XSLT 모듈 포함
• =dynamic: 정적이 아닌 동적 모듈(.so 파일)로 빌드하라는 의미
• =dynamic을 안 붙이면 정적 모듈로 컴파일되며, make modules이 안 먹히고, so 파일도 안 만들어진다.

3. 모듈 로드 및 사용

# nginx.conf 파일 수정
vi /etc/nginx/nginx.conf

# nginx.conf 파일 최상단에 추가
# 모듈을 사용하기 위함
include /usr/share/nginx/modules/*.conf;

 
/usr/share/nginx/modules/ 안에 conf 파일을 만들어서 모듈을 로드한다.

# conf 파일 생성 후 파일 안에 load_module 추가
vi /usr/share/nginx/modules/mod-http-image-filter.conf

# 파일 안에 추가
load_module "/usr/lib64/nginx/modules/ngx_http_image_filter_module.so";

 

4. 설정 확인 및 재시작

# 설정 파일 문법 검사
nginx -t

# Nginx 재시작 (무중단)
systemctl reload nginx

 
설정파일 문법 검사 시, 아래와 같이 OK와 successful을 확인했다면 재시작한다.
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
 
 

정적/동적에 따른 Nginx 재시작 방법

# 정적모듈: Nginx 바이너리 자체가 교체되므로 재시작 필요 (중지 발생)
systemctl restart nginx  

# 동적모듈: .so 파일만 교체 후 reload만으로 가능 (무중단)
systemctl reload nginx