Communitygithub.com

홈랩 Pi-hole DNS

Pi-hole 설치, 블록리스트 관리, DNS-over-HTTPS 설정, DHCP 통합, 로컬 DNS 레코드 및 홈 네트워크에서 DNS 해석 문제 해결을 위한 스킬입니다. 작업이 Pi-hole과 명시적으로 관련된 경우(설치, 블록리스트 관리, DoH 또는 DHCP 구성, 로컬 DNS 레코드 추가, Pi-hole 경로에서 DNS 해석 진단) 사용하십시오.

홈랩 Pi-hole DNS란 무엇인가요?

이 스킬은 Raspberry Pi 또는 Linux 호스트에서 실행되는 네트워크 전체 DNS 광고 차단기인 Pi-hole의 설치, 구성 및 문제 해결을 위한 포괄적인 가이드입니다. Pi-hole을 Docker 또는 베어메탈로 설치하는 방법, StevenBlack 및 Blocklist Project와 같은 권장 블록리스트를 관리하는 방법, cloudflared를 사용하여 DNS-over-HTTPS(DoH) 업스트림 확인자를 설정하는 방법, 라우터 DHCP 설정 또는 Pi-hole 자체 DHCP 서버를 통해 네트워크 장치를 Pi-hole로 연결하는 방법을 다룹니다. 또한 로컬 DNS 레코드(CNAME 포함)를 생성하여 서비스에 쉽게 접근할 수 있도록 하고, 차단된 사이트 화이트리스트 추가, DNS 쿼리 로그 확인, 'pihole -q', 'dig'와 같은 명령어를 사용한 DNS 문제 진단 등 일반적인 문제 해결 시나리오를 설명합니다. 베스트 프랙티스에는 정적 IP 설정, 중복성을 위한 보조 Pi-hole, 정기적인 블록리스트 업데이트가 포함되며, 단일 장애 지점이나 라우터 DHCP와의 충돌과 같은 안티 패턴을 피하도록 안내합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/affaan-m/everything-claude-code/tree/main/skills/homelab-pihole-dns
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

홈랩 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은 블록리스트와 대조합니다.
차단된 도메인은 널 응답을 반환합니다 — 광고/트래커가 로드되지 않습니다.
허용된 도메인은 업스트림 확인자(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를 설정하고, 600으로 권한을 변경하며, git에 넣지 마십시오 — 비밀번호를 컴포즈 파일에 직접 넣지 마십시오.

웹 관리에 접근: 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/버전에 대해 Pi-hole이 문서화한 패키지 또는 설치 프로그램 경로를 선호합니다.
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과 같은 공용 대체는 롤아웃 중 가용성을 향상시키지만
             클라이언트가 이를 쿼리할 수 있으므로 차단을 우회할 수 있습니다.

  모든 장치는 다음 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: DHCP 서버로서의 Pi-hole (라우터 DHCP 대체)
  Pi-hole 관리 → 설정 → DHCP → 활성화
  먼저 라우터에서 DHCP를 비활성화하십시오 — 동일한 네트워크에 두 개의 DHCP 서버가 있으면 충돌이 발생합니다.
  장점: 호스트 이름 확인이 자동으로 작동합니다 (장치가 이름을 등록).

블록리스트 관리

# Pi-hole 관리 → 광고 목록 → 새 광고 목록 추가

# 권장 블록리스트:
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # 기본 — 20만개 이상의 도메인

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

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

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

# 차단되지 말아야 할 사이트가 차단된 경우 (오탐):
  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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

accessibility

Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA. Use when building or auditing UI that must meet WCAG 2.2 Level AA, or when reviewing a change for keyboard, contrast, or screen-reader support.

affaan-m/claude-api

Anthropic Claude API patterns for Python and TypeScript. Covers Messages API, streaming, tool use, vision, extended thinking, batches, prompt caching, and Claude Agent SDK. Use when building applications with the Claude API or Anthropic SDKs.

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

affaan-m/everything-claude-code

Development conventions and patterns for everything-claude-code. JavaScript project with conventional commits.

affaan-m/everything-claude-code-conventions

Development conventions and patterns for everything-claude-code. JavaScript project with conventional commits.

affaan-m/frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use when the user asks to build web components, pages, or applications and the visual direction matters as much as the code quality.

affaan-m/gget

gget CLI and Python workflow for quick genomic database queries, sequence lookup, BLAST-style searches, enrichment checks, and reproducible bioinformatics evidence logs.

affaan-m/literature-review

Systematic literature-review workflow for academic, biomedical, technical, and scientific topics, including search planning, source screening, synthesis, citation checks, and evidence logging.

affaan-m/motion-ui

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

affaan-m/project-guidelines-example

Example project-specific skill template based on a real production application.

affaan-m/pubmed-database

Direct PubMed and NCBI E-utilities search workflows for biomedical literature, MeSH queries, PMID lookup, citation retrieval, and API-backed literature monitoring.

affaan-m/scholar-evaluation

Structured scholarly-work evaluation for papers, proposals, literature reviews, methods sections, evidence quality, citation support, and research-writing feedback.

affaan-m/uspto-database

USPTO patent and trademark data workflow for official record lookup, PatentSearch queries, TSDR checks, assignment data, and reproducible IP research logs.

agent-architecture-audit

Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature. Use when an agent or LLM feature misbehaves and the failing layer is unknown, or before shipping an agent stack.

agent-eval

Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics. Use when choosing between coding agents, or when a change to an agent setup needs measured pass rate, cost, and time rather than an impression.

agent-harness-construction

Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates. Use when defining or revising an agent

agentic-engineering

Operate as an agentic engineer using eval-first execution, decomposition, and cost-aware model routing. Use when planning or executing engineering work that agents will carry out end to end.

agentic-os

Build persistent multi-agent operating systems on Claude Code. Covers kernel architecture, specialist agents, slash commands, file-based memory, scheduled automation, and state management without external databases. Use when building a persistent multi-agent system on Claude Code with its own memory, commands, and scheduling.

agent-introspection-debugging

Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports. Use when an agent run fails and you need a reproducible diagnosis instead of a retry.

agent-payment-x402

Add x402 payment execution to AI agents with per-task budgets, spending controls, and non-custodial wallets. Supports Base through agentwallet-sdk and X Layer through OKX Payments / OKX Agent Payments Protocol. Use when an agent must pay for something itself and needs per-task budgets, spending controls, and a non-custodial wallet.

관련 스킬

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community