홈랩 Pi-hole DNS

홈랩 Pi-hole DNS은(는) 무엇을 하나요?

Pi-hole은 Raspberry Pi 또는 모든 Linux 호스트에서 실행되는 네트워크 전체 DNS 광고 차단기입니다. 네트워크에 연결된 모든 기기는 자동으로 광고 및 악성 도메인 차단을 받습니다 — 브라우저 확장이 필요하지 않습니다.

사용 시기

• Raspberry Pi 또는 Linux 호스트에 Pi-hole 설치
• 홈 네트워크의 DNS 서버로 Pi-hole 구성
• 블록리스트 추가 또는 관리
• DNS-over-HTTPS(DoH) 업스트림 리졸버 설정
• 로컬 DNS 레코드 생성 (예: nas.home.lan, pi.home.lan)
• Pi-hole 설치 후 인터넷에 접속할 수 없는 기기 문제 해결
• DHCP와 함께 또는 대신 Pi-hole 실행

Pi-hole 작동 방식

정상 흐름(Pi-hole 없음):
  기기 → ads.tracker.com 요청 → ISP DNS → 실제 IP → 광고 로드

Pi-hole 사용 시:
  기기 → ads.tracker.com 요청 → Pi-hole DNS → 차단 (0.0.0.0 반환) → 광고 없음

모든 DNS 쿼리는 먼저 Pi-hole을 통과합니다.
Pi-hole은 블록리스트와 대조하여 확인합니다.
차단된 도메인은 null 응답을 반환합니다 — 광고/트래커는 로드되지 않습니다.
허용된 도메인은 업스트림 리졸버(Cloudflare, Google 등)로 전달됩니다.

설치

Docker (권장)

Docker는 Pi-hole을 설치하는 가장 쉬운 방법이며 업데이트와 백업이 간단합니다.

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # 웹 관리자
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # .env 파일 또는 시크릿으로 설정
      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
      DNSMASQ_LISTENING: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN              # Pi-hole이 DHCP를 제공하는 경우에만 필요

배포 전에 <pinned-release-tag>를 현재 Pi-hole 릴리스 태그로 바꾸세요. 장기 DNS 인프라의 경우 업그레이드를 신중하게 검토할 수 있도록 latest는 피하세요.

docker-compose.yml 옆에 .env 파일에 PIHOLE_WEBPASSWORD를 설정하고, chmod를 600으로 설정한 후 git에 포함하지 마세요 — 비밀번호를 compose 파일에 직접 넣지 마세요.

웹 관리자 접속: http://<pi-ip>/admin

베어메탈 설치 (Raspberry Pi OS / Debian / Ubuntu)

Pi-hole을 설치하기 전에 정적 IP가 필요합니다.

# 1단계: 정적 IP 할당 (Pi OS의 경우 /etc/dhcpcd.conf 편집)
sudo nano /etc/dhcpcd.conf
# 맨 아래에 추가:
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# 2단계: 설치 프로그램을 다운로드하고 실행하기 전에 검토합니다.
# OS/버전에 맞는 패키지 또는 설치 프로그램 경로를 선호합니다.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # 진행 전 검토

# 3단계: 실행
bash pi-hole-install.sh

# 대화형 설치 프로그램을 따르세요:
# 1. 네트워크 인터페이스 선택 (유선 권장 — eth0)
# 2. 업스트림 DNS 선택 (Cloudflare 또는 기본값 유지 — 나중에 변경 가능)
# 3. 정적 IP 확인
# 4. 웹 관리자 인터페이스 설치 (권장)
# 5. 마지막에 표시되는 관리자 비밀번호 기록

네트워크를 Pi-hole에 연결하기

# 방법 1: 라우터 DHCP 설정에서 DNS 변경 (권장)
  라우터 관리자 UI → DHCP 설정 → DNS 서버
  기본 DNS: 192.168.3.2  (Pi-hole IP)
  보조 DNS: 엄격한 차단을 위해 비워두거나, 두 번째 Pi-hole 사용.
            1.1.1.1과 같은 공용 대체 DNS는 롤아웃 중 가용성을 높이지만
            클라이언트가 쿼리할 수 있으므로 차단을 우회할 수 있습니다.

  모든 기기는 다음 DHCP 갱신 시 자동으로 Pi-hole을 DNS로 받습니다.
  강제 갱신: Wi-Fi 재연결 또는 Linux에서 'sudo dhclient -r && sudo dhclient' 실행

# 방법 2: 기기별 DNS (네트워크 전체 롤아웃 전 테스트에 유용)
  Windows: 제어판 → 네트워크 어댑터 → IPv4 속성 → 수동으로 DNS 설정
  macOS: 시스템 설정 → 네트워크 → 세부정보 → DNS → 수동 설정
  Linux: /etc/resolv.conf 또는 NetworkManager

# 방법 3: Pi-hole을 DHCP 서버로 사용 (라우터 DHCP 대체)
  Pi-hole 관리자 → 설정 → DHCP → 활성화
  먼저 라우터의 DHCP를 비활성화하세요 — 동일한 네트워크에 두 개의 DHCP 서버가 있으면 충돌이 발생합니다.
  장점: 호스트 이름 해석이 자동으로 작동합니다 (기기가 이름을 등록).

블록리스트 관리

# Pi-hole 관리자 → Adlists → 새 adlist 추가

# 권장 블록리스트:
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # 기본 — 200k+ 도메인

  https://blocklistproject.github.io/Lists/malware.txt
  # 악성 도메인

  https://blocklistproject.github.io/Lists/tracking.txt
  # 추적/원격 측정

# 리스트 추가 후:
  도구 → Gravity 업데이트 (모든 블록리스트 다운로드 및 컴파일)

# 차단되지 말아야 할 사이트가 차단된 경우 (false positive):
  Pi-hole 관리자 → 허용 목록 → 도메인 추가
  예: api.my-legitimate-service.com

# 실시간으로 차단되는 내용 확인:
  대시보드 → 쿼리 로그 (차단/허용 상태가 포함된 실시간 DNS 쿼리 스트림)

DNS-over-HTTPS 업스트림

DNS-over-HTTPS는 DNS 쿼리를 암호화하여 ISP가 해석하는 사이트를 볼 수 없도록 합니다.

# cloudflared 설치 (Cloudflare의 DoH 프록시).
# 자동 서명된 패키지 확인을 위해 Cloudflare의 패키지 저장소를 선호합니다.
# 바이너리를 직접 다운로드하는 경우 릴리스 버전을 고정하고 체크섬을 확인하세요.
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# 설치 전 Cloudflare의 릴리스 노트에서 체크섬/서명을 확인하세요.
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# cloudflared 설정 파일 생성
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml << EOF
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
EOF

# systemd 서비스 생성
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# 이제 Pi-hole을 로컬 DoH 프록시로 지정:
# Pi-hole 관리자 → 설정 → DNS → 사용자 지정 업스트림 DNS
# 다음으로 설정: 127.0.0.1#5053
# 다른 모든 업스트림 리졸버 선택 해제

로컬 DNS 레코드

서비스를 이름으로 접근 가능하게 만드세요 (예: nas.home.lan, grafana.home.lan).

도메인 이름 참고: .home.lan은 홈랩에서 널리 사용되며 실제로 작동합니다. IETF가 로컬 사용을 위해 예약한 접미사는 .home.arpa입니다(RFC 8375) — 표준을 따르려면 이를 사용하세요. Pi-hole DNS 레코드에는 .local을 피하세요. mDNS/Bonjour와 충돌합니다.

# Pi-hole 관리자 → 로컬 DNS → DNS 레코드

  도메인              IP
  nas.home.lan        192.168.30.10
  pi.home.lan         192.168.30.2
  grafana.home.lan    192.168.30.3
  proxmox.home.lan    192.168.30.4

# 네트워크의 모든 기기에서:
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → Grafana 대시보드

# 서브도메인의 경우 CNAME 추가:
  Pi-hole 관리자 → 로컬 DNS → CNAME 레코드
  도메인: portainer.home.lan → 대상: pi.home.lan

문제 해결

# Pi-hole이 차단하지 말아야 할 것을 차단하는 경우
pihole -q example.com          # 도메인이 차단되었는지와 어떤 목록인지 확인
pihole -w example.com          # 즉시 허용 목록에 추가

# DNS가 전혀 해석되지 않는 경우
pihole status                  # pihole-FTL이 실행 중인지 확인
dig @192.168.3.2 google.com   # Pi-hole을 통해 직접 DNS 테스트

# Pi-hole DNS 재시작
pihole restartdns

# 특정 기기에 대한 쿼리 로그 확인
pihole -t                      # 모든 쿼리 실시간 추적
# 또는 웹 관리자 쿼리 로그에서 클라이언트별 필터링

# Pi-hole gravity 업데이트 (블록리스트 새로고침)
pihole -g

안티 패턴

# 나쁜 예: 복구 경로 없이 하나의 Pi-hole에 의존
# Pi-hole이 충돌하거나 Pi 전원이 손실되면 DNS가 중단될 수 있음
# 좋은 예: 설정 중 롤백을 위해 문서화된 라우터 대체 수단 유지
# 더 좋은 예: 중복성을 위해 두 개의 Pi-hole 인스턴스 실행; 엄격한 차단을 위해 공용 대체 DNS 사용 금지

# 나쁜 예: 정적 IP 없이 Pi-hole 설치
# Pi가 새로운 DHCP IP를 받으면 모든 기기가 DNS를 잃음
# 좋은 예: 먼저 정적 IP 설정 후 Pi-hole 설치

# 나쁜 예: 라우터 DHCP를 먼저 비활성화하지 않고 Pi-hole DHCP 활성화
# 동일한 네트워크에 두 개의 DHCP 서버가 있으면 충돌하는 IP를 할당
# 좋은 예: 라우터 DHCP 비활성화 후 Pi-hole DHCP 활성화

# 나쁜 예: gravity(블록리스트)를 업데이트하지 않음
# 새로운 광고 및 악성 도메인이 누적되므로 오래된 목록은 놓침
# 좋은 예: 매주 gravity 업데이트 예약: pihole -g (또는 설정 → API에서 활성화)

모범 사례

• Pi-hole을 설치하기 전에 Pi에 정적 IP 또는 DHCP 예약을 지정하세요.
• Pi-hole을 기본 DNS로 사용하세요. 중복성을 위해 엄격한 차단이 필요한 경우 공용 리졸버 대신 두 번째 Pi-hole을 추가하세요.
• cloudflared로 DoH(DNS-over-HTTPS)를 활성화하여 암호화된 업스트림 쿼리를 사용하세요.
• home.lan을 로컬 도메인으로 설정하고 모든 서비스에 대한 DNS 레코드를 생성하세요.
• 가끔 쿼리 로그를 검토하세요 — 차단된 쿼리는 기기가 무엇을 하고 있는지 보여줍니다.

관련 스킬

• homelab-network-setup
• homelab-vlan-segmentation
• homelab-wireguard-vpn