homelab-pihole-dns

Homelab Pi-hole DNS

Pi-holeは、Raspberry PiやLinuxホスト上で動作するネットワーク全体のDNS広告ブロッカーです。 ネットワーク上のすべてのデバイスが自動的に広告・マルウェアドメインのブロックを受けます — ブラウザ拡張機能は不要です。

使用するタイミング

• Raspberry PiやLinuxホストへのPi-holeのインストール
• Pi-holeをホームネットワークのDNSサーバーとして設定する
• ブロックリストの追加または管理
• 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は避け、アップグレードを計画的かつレビュー可能にします。

PIHOLE_WEBPASSWORDはdocker-compose.ymlと同じディレクトリの.envファイルに設定し、chmod 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）です — 標準に従う場合はこれを使用してください。 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                      # すべてのクエリのライブテール
# またはWeb管理画面のクエリログでクライアントでフィルタ

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

アンチパターン

# 悪い例: 復旧手段のない1台の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