DNSBox

IP 기반 호스트 이름을 위한 DNS와 HTTPS

*.dnsbox.io를 통해 공용 HTTP 서비스에 접속하거나, 사설 네트워크에서 DNSBox를 직접 실행하세요.

v0.5.2에서 제공하는 기능

v0.4.x에서 업그레이드하시나요? 기존 설치를 교체하기 전에 마이그레이션 안내를 따르세요. 마이그레이션 안내

공용 서비스 사용하기

계정이나 도메인 등록이 필요하지 않습니다. 백엔드는 허용된 공인 IP를 사용하고 포트 80에서 HTTP 서비스를 실행해야 하며, DNSBox에서 접근할 수 있어야 합니다.

198.51.100.20을 서버의 공인 IPv4 주소로 바꾸세요:

https://198-51-100-20.dnsbox.io

DNS는 호스트 이름을 DNSBox 프록시 주소로 확인합니다. 프록시는 HTTPS 연결을 종료 처리하고, 호스트 이름에 인코딩된 IP로 HTTP 요청을 전달합니다. 사용자 서버에 인증서를 설치하지는 않습니다.

Let's Encrypt는 DNS-01로 호스트 이름을 검증합니다. 인증서는 IP 주소 자체가 아닌 해당 호스트 이름에 발급됩니다. 인증서를 발급하는 동안 첫 TLS 연결에 시간이 더 걸릴 수 있습니다.

브라우저와 DNSBox 사이의 연결은 HTTPS를 사용합니다. DNSBox와 백엔드 사이의 연결은 HTTP를 사용합니다. WebSocket 업그레이드를 지원합니다.

IPv6 백엔드는 2a01-4f8-c17-b8f--1.dnsbox.io처럼 인코딩할 수 있습니다. 하이픈 하나는 콜론을, 하이픈 두 개는 ::를 나타냅니다.

DNS 확인 후 HTTPS를 확인하세요. 이 테스트에는 접근 가능한 자체 HTTP 백엔드를 사용하세요:

dig +short 198-51-100-20.dnsbox.io
curl -v https://198-51-100-20.dnsbox.io/

DNS 응답은 프록시 주소입니다. 유효한 TLS 연결과 성공적인 백엔드 HTTP 응답은 각각 별도로 확인해야 합니다.

사설 네트워크에서 실행하기

로컬 TLS 모드는 공용 DNS, 포트 포워딩, 인터넷 연결 없이 작동합니다. DNSBox가 자체 인증 기관을 생성합니다. 클라이언트는 이 CA를 신뢰하도록 설정해야 합니다.

예: DNSBox는 192.168.1.2에서, HTTP 백엔드는 192.168.1.0/24에서 실행합니다:

./dnsboxd --domain=home.arpa --ip=192.168.1.2 \
  --tls-mode=local --allowed-cidrs=192.168.1.0/24 \
  --dns-listen=192.168.1.2:53 --https-listen=192.168.1.2:443 \
  --data-dir=/var/lib/dnsbox

LAN 리졸버에서 home.arpa 영역만 192.168.1.2로 전달하세요. DNSBox는 자체 영역의 권한 서버이며, 범용 재귀 리졸버가 아닙니다.

로컬 인증서 하나를 발급해 CA를 만든 다음, 각 클라이언트의 신뢰할 수 있는 CA 저장소에 /var/lib/dnsbox/ca/root.crt를 설치하세요. root.pem은 비공개로 보관하세요. 배포 안내에 초기 설정 명령이 있습니다.

192.168.1.50의 백엔드에 접속하려면 https://192-168-1-50.home.arpa를 여세요. LAN 클라이언트는 DNSBox의 DNS 및 HTTPS 포트에 접근할 수 있어야 하며, DNSBox는 백엔드의 HTTP 포트에 접근할 수 있어야 합니다.

사설 네트워크 설정

Let's Encrypt로 직접 호스팅하기

직접 제어하는 도메인이나 하위 도메인을 사용하고, 해당 DNS 영역을 DNSBox 네임서버에 위임하세요. 노드 하나로도 영역을 서비스할 수 있으며, 여러 노드를 사용하면 이중화할 수 있습니다.

공용 DNS-01 검증을 위해 인바운드 UDP 53과 TCP 53, 아웃바운드 HTTPS 및 DNS 조회를 허용하세요. 인바운드 포트 80은 필요하지 않습니다. 포트 443은 서비스를 이용할 클라이언트에서만 접근할 수 있으면 됩니다.

DNS-01 검증이 공개적으로 가능하면 사설 HTTP 백엔드에도 공개적으로 신뢰되는 호스트 이름 인증서를 사용할 수 있습니다. --allowed-cidrs로 해당 백엔드를 명시적으로 허용하고 클라이언트의 DNS와 라우팅을 설정하세요.

여러 노드를 사용할 때는 모든 노드에 같은 네임서버 목록과 레코드를 설정하고, 챌린지 복제용 상호 TLS를 구성하세요. 설정된 모든 피어가 챌린지 수신을 확인해야 인증서 발급이 진행됩니다.

Linux, macOS, Windows용 릴리스 압축 파일을 제공합니다. 설치 프로그램은 수동 실행이나 다른 프로세스 관리자를 위한 --no-systemd 옵션을 지원합니다. 시스템 리졸버를 비활성화하지 않습니다.

설치 및 클러스터 설정

ocserv 및 다른 서비스를 위한 인증서

공용 서비스는 개인 키를 내보내지 않습니다. 서비스에 인증서 파일이 필요하다면 직접 제어하는 영역을 위임하고 DNSBox를 자체 호스팅하세요.

해당 영역에서 IP를 인코딩한 호스트 이름과 함께 --issue를 실행하세요. DNSBox는 PEM 인증서 체인과 개인 키를 <data-dir>/certs에 저장한 뒤 종료합니다. ACME 발급 중에는 DNS를 서비스하지만 HTTPS 포트 443은 사용하지 않습니다.

명시적인 A/AAAA 레코드를 사용해 해당 호스트 이름이 서비스로 직접 연결되도록 하세요. ocserv에서는 server-cert와 server-key를 설정하세요. DNSBox의 HTTP 프록시는 OpenConnect나 DTLS를 구현하지 않습니다.

갱신 절차를 마련하고 파일이 변경되면 서비스를 다시 로드하세요. 일회성 명령은 종료 후 인증서를 갱신하지 않습니다. 같은 데이터 디렉터리를 사용하는 DNSBox 프로세스 두 개를 동시에 실행하지 마세요.

인증서 내보내기 예시

자주 묻는 질문

공용 서비스에서 사설 IP를 사용할 수 있나요?

아니요. 공용 프록시는 허용된 공용 백엔드용입니다. 사설 주소에는 명시적인 CIDR 허용 목록을 설정한 자체 인스턴스를 사용하세요.

IP가 바뀌면 어떻게 되나요?

IP는 호스트 이름의 일부입니다. 새 IP에는 새 호스트 이름을 사용하세요. 기존 이름을 사용하는 클라이언트는 계속 기존 주소로 접속합니다.

DNSBox가 백엔드 IP의 소유권을 확인하나요?

DNS-01은 DNS 호스트 이름에 대한 제어 권한을 확인합니다. 백엔드 IP의 소유권이나 그곳에서 제공하는 콘텐츠는 검증하지 않습니다.

인증서가 자동으로 갱신되나요?

실행 중인 DNSBox 서비스는 관리 중인 인증서를 갱신합니다. 내보낸 인증서는 별도의 갱신 절차와 해당 인증서를 사용하는 서비스의 다시 로드가 필요합니다.

백엔드가 오프라인이면 어떻게 되나요?

DNS와 TLS는 계속 작동할 수 있지만, 프록시는 애플리케이션 콘텐츠를 반환할 수 없습니다. 백엔드의 HTTP 리스너, 방화벽, 연결 가능 여부를 확인하세요.

문제는 어디에 신고하나요?

DNSBox 버전, 배포 모드, 관련 오류 메시지를 포함해 GitHub 이슈를 등록하세요. 개인 키, 토큰 및 기타 비밀 정보는 제거하세요.

GitHub 이슈

기술 참고

설정 참고

소스 코드