네이티브 모듈 (개발자용)

일반적인 사용에는 모듈이 필요하지 않습니다. 이 안내는 네이티브 라이브러리로 Windows나 Linux 서비스의 기능을 확장하려는 개발자와 관리자를 위한 것입니다. 모듈은 서비스 내부에서 서비스 권한으로 실행됩니다. 신뢰할 수 있는 코드만 설치하고 모듈 파일, 의존 파일, 설정 파일은 관리자가 소유하도록 유지하세요.

모듈 로드

서비스는 설정 파일 옆의 modules.d 디렉터리에서 *.conf 파일을 읽습니다. 기본 위치는 다음과 같습니다.

운영체제	모듈 설정 위치	라이브러리 형식
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

각 파일에는 라이브러리의 절대 경로를 한 줄에 하나씩 적습니다. 예를 들어 /etc/mudfish-dns/modules.d/10-policy.conf의 내용은 다음과 같습니다.

/usr/lib/mudfish-dns/modules/policy.so

파일 이름 순서로 읽고, 각 파일 안에서는 줄 순서로 읽습니다. 빈 줄과 #으로 시작하는 줄은 무시합니다. 경로를 따옴표로 감싸거나 환경 변수, 줄 끝 주석을 사용하지 마세요. 이러한 표현은 해석되지 않습니다. Windows에서도 공백이 있는 경로를 포함해 전체 절대 경로를 파일 안에 적으세요.

모듈을 추가, 변경, 제거한 뒤에는 서비스를 다시 시작하세요. Linux에서는 다음 명령을 사용합니다.

sudo systemctl restart mudfish-dns.service

Windows에서는 서비스 관리에서 Mudfish DNS 서비스를 다시 시작하세요. 앱의 DNS 시작, DNS 중지, 설정 적용은 모듈을 다시 로드하지 않습니다. 설정 파일을 읽을 수 없거나 경로가 잘못되었거나 로드 및 초기화 오류가 발생하면 서비스가 시작되지 않습니다. 모듈 디렉터리가 없거나 비어 있는 것은 허용됩니다.

개발 중에는 --module 인자를 반복해서 지정하여 인자 순서대로 라이브러리를 로드할 수 있습니다. 이 경우 modules.d 자동 로드를 대체합니다. --config FILE은 설정 파일 옆의 모듈 디렉터리 위치도 바꿉니다. --restore-dns는 모듈을 로드하지 않고 복구를 수행합니다.

훅 구현

mudfish_dns_module.h 헤더를 읽거나 mudfish_dns_module.h를 다운로드하세요. 이 헤더는 모듈에서 사용하는 구조체, 훅, 동작과 데이터 수명 규칙을 정의합니다. 이 안내에서는 C ABI v2를 사용합니다. mudfish_dns_module_init_v2()를 외부로 노출하고, 훅을 채우기 전에 MUDFISH_DNS_MODULE_ABI_V2와 전달된 구조체 크기를 확인하세요. 초기화에 성공하면 0을 반환합니다.

훅	호출 시점
on_dns_query	파싱된 질의를 받아들인 뒤, 캐시 조회나 전달을 하기 전.
on_dns_response	응답이 선택된 뒤, 캐시에 저장하거나 클라이언트에 반환하기 전. 캐시된 응답도 이 훅을 거칩니다.
on_web_hello	초기 HTTP Host/TLS SNI 검사가 끝난 뒤, 연결하거나 초기 데이터를 처리하기 전.
on_web_data	후속 클라이언트 데이터나 서버 데이터를 읽은 뒤, 전달하기 전.

DNS 동작

v2 DNS 훅은 성공 시 0을 반환하고 result->action을 설정합니다.

동작	효과
MUDFISH_DNS_CONTINUE	다음 모듈과 일반 처리를 계속합니다.
MUDFISH_DNS_ALLOW	현재 훅 체인을 끝내고 일반 DNS 조회를 계속하거나 선택된 응답을 반환합니다.
MUDFISH_DNS_BLOCK	REFUSED를 반환합니다.
MUDFISH_DNS_DROP	DNS 응답을 보내지 않고 버립니다.
MUDFISH_DNS_ANSWER	제공한 IPv4/IPv6 주소와 TTL로 응답을 생성합니다.
MUDFISH_DNS_REPLACE	모듈이 제공하는 완전한 DNS 와이어 형식 응답을 사용합니다.

v2 DNS 훅에서 동작 상수를 직접 반환하지 마세요. 함수가 0이 아닌 값을 반환하거나 결과가 유효하지 않으면 SERVFAIL이 발생합니다. ALLOW는 현재 훅 체인만 끝내며 도메인 규칙, 통신 방식 허용 여부, 인증서 검사를 우회하지 않습니다. DROP을 제외한 질의 결과는 응답 훅도 거칩니다.

웹 훅은 MUDFISH_DNS_CONTINUE 또는 MUDFISH_DNS_REJECT를 직접 반환합니다. 웹 요청을 거부하면 연결을 종료합니다. 웹 훅을 사용하려면 웹 보호가 켜져 있어야 하며, 복호화된 HTTPS 내용은 제공되지 않습니다.

버퍼, 스레드, 캐시

입력 이벤트와 버퍼는 읽기 전용이며 콜백 실행 중에만 유효합니다. 대체 응답은 모듈이 소유한 메모리를 사용해야 하며 해당 모듈의 다음 콜백이나 종료 시점까지 유효해야 합니다. 스택 메모리나 이벤트에서 빌린 포인터를 반환하지 마세요. 대체 응답의 DNS ID, opcode, 질문은 원래 질의와 일치해야 합니다. 한 인스턴스의 콜백은 순차적으로 실행되지만 서로 다른 스레드에서 호출될 수 있습니다. 콜백은 짧게 끝내고 ABI 경계를 넘어 예외를 전파하지 마세요.

생성, 교체, 차단, 폐기한 결과는 호스트 캐시에 저장하지 않습니다. 캐시된 응답을 교체해도 원래 캐시 항목은 바뀌지 않습니다. 호스트는 대체 응답의 AD 플래그를 지우며 DNSSEC 검증이나 재서명을 수행하지 않습니다. 서명된 데이터를 수정하는 모듈은 무효화된 서명을 직접 처리해야 합니다.

예제와 헤더

아래 페이지에는 전체 예제 소스와 필요한 헤더가 있습니다. 미꾸라지 DNS 소스 트리를 별도로 내려받을 필요는 없습니다.

파일	내용
policy.c — DNS 정책 예제	DNS 질의 허용, 차단, 폐기, IP 응답 생성, 응답 주소와 TTL 변경. Linux 빌드 및 테스트 명령도 포함합니다.
mudfish_dns_module.h — 모듈 헤더	ABI 선언, 훅 시그니처, 동작 상수, 버퍼 소유권 규칙.

빌드 전에 policy.c와 mudfish_dns_module.h를 같은 디렉터리에 다운로드하세요. 예제의 빌드 명령은 Linux .so 라이브러리를 생성합니다.