homelab-pihole-dns

Homelab 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と併用、または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"          # Web管理画面
    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で追跡しないようにしてください。パスワードをコンポーズファイルに直接記述しないでください。

Web管理画面にアクセス: 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. Web管理インターフェースをインストール（推奨）
# 5. 最後に表示される管理パスワードをメモする

ネットワークをPi-holeに向ける

# 方法1: ルーターのDHCP設定でDNSを変更（推奨）
  ルーター管理UI → DHCP設定 → DNSサーバー
  プライマリDNS: 192.168.3.2  (Pi-holeのIP)
  セカンダリDNS: 厳格なブロックの場合は空白のまま、または2台目の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: Pi-holeをDHCPサーバーとして使用（ルーターのDHCPを置き換え）
  Pi-hole管理画面 → 設定 → DHCP → 有効化
  先にルーターのDHCPを無効にしてください — 同じネットワーク上に2つの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） — 標準に従う場合はそれを使用してください。 mDNS/Bonjourと競合するため、Pi-holeのDNSレコードには .local を避けてください。

# 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                      # すべてのクエリのライブテール
# またはWeb管理画面のクエリログでクライアントでフィルタリング

# Pi-hole gravity更新（ブロックリストのリフレッシュ）
pihole -g

アンチパターン

# 悪い例: 回復手段なしに単一のPi-holeに依存する
# Pi-holeがクラッシュしたり、Piの電源が落ちたりすると、DNSが機能しなくなる可能性があります
# 良い例: セットアップ中にロールバックするための、文書化されたルーターフォールバックを維持する
# さらに良い例: 冗長性のために2つのPi-holeインスタンスを実行する。厳格なブロックのためにはパブリックフォールバックDNSを避ける

# 悪い例: 静的IPなしでPi-holeをインストールする
# Piが新しいDHCP IPを取得すると、すべてのデバイスがDNSを失います
# 良い例: 最初に静的IPを設定し、その後Pi-holeをインストールする

# 悪い例: ルーターのDHCPを無効にせずにPi-hole DHCPを有効にする
# 同じネットワーク上の2つのDHCPサーバーは、競合するIPを払い出します
# 良い例: ルーターのDHCPを無効にし、次にPi-hole DHCPを有効にする

# 悪い例: gravity（ブロックリスト）を決して更新しない
# 新しい広告やマルウェアドメインが蓄積され、古いリストはそれらを見逃します
# 良い例: 毎週のgravity更新をスケジュールする: pihole -g（または設定 → APIで有効にする）

ベストプラクティス

• Pi-holeをインストールする前に、Piに静的IPまたはDHCP予約を割り当ててください
• Pi-holeをプライマリDNSとして使用します。冗長性のために、厳格なブロックが必要な場合はパブリックリゾルバの代わりに2台目のPi-holeを追加してください
• cloudflaredを使用してDoH（DNS-over-HTTPS）を有効にし、アップストリームクエリを暗号化します
• home.lan をローカルドメインとして設定し、すべてのサービスにDNSレコードを作成してください
• 時々クエリログを確認してください — ブロックされたクエリはデバイスの動作を示しています

関連スキル

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