Pihole & Unbound: Installation for Pihole V6 (read description)

[MickLesk]

Pi-hole v6 Migration Guide

Overview

With the release of Pi-hole v6, significant changes have been introduced, particularly in the way configurations are managed. This guide outlines the key changes and provides a migration path for users, especially those utilizing Unbound as their upstream DNS resolver.

---

Key Changes in Pi-hole v6

1. Migration to TOML Configuration

   • Pi-hole now uses /etc/pihole/pihole.toml instead of setupVars.conf for settings.
   • The migration is automatically handled by Pi-hole and does not require manual intervention.

2. Updated Unbound Configuration Handling

   • Previous configurations using setupVars.conf or dnsmasq.d/01-pihole.conf for upstream DNS must be adjusted.
   • The new method involves setting upstream DNS in pihole.toml.

3. DHCP Server Defaults Changed

   • The built-in DHCP server is disabled by default.
   • Users who rely on Pi-hole’s DHCP functionality must manually enable it.

4. NTP Sync Changes

   • NTP synchronization is enabled by default but can be disabled in pihole.toml.

5. New Command-Line Configuration Options

   • Some settings can now be modified dynamically via pihole-FTL --config.

---

Migration Steps

1. Verify Migration

Pi-hole v6 automatically migrates existing configurations and stores previous versions in:

/etc/pihole/migrations_v6

After updating, check the migration log to ensure a smooth transition.

2. Adjust Upstream DNS (for Unbound Users)

If you previously modified setupVars.conf, update /etc/pihole/pihole.toml as follows:

Modify the [dns] section:

[dns]
  upstreams = ["127.0.0.1#5335"]
  domainNeeded = true
  expandHosts = true

Restart Pi-hole:

systemctl restart pihole-FTL

3. Ensure DHCP Settings (if used)

For those using Pi-hole as a DHCP server, ensure it is enabled in pihole.toml:

[dhcp]
  active = true

Apply the changes:

systemctl restart pihole-FTL

4. Disable NTP Sync (if needed)

By default, NTP sync is active. To disable it, modify:

[ntp.sync]
  active = false
  interval = 0

Apply the change:

pihole-FTL --config ntp.sync.active false

---

Common Issues & Fixes

Issue: no upstream servers configured

Fix: Ensure upstreams is properly set in pihole.toml and restart Pi-hole:

[dns]
  upstreams = ["127.0.0.1#5335", "8.8.8.8"]

systemctl restart pihole-FTL

Issue: DHCP Not Working After Update

Fix: Verify that [dhcp] active = true is set and restart Pi-hole.

---

Summary

Pi-hole v6 introduces automatic configuration migration but requires manual updates for Unbound users. Ensure your DNS settings are correctly configured in pihole.toml, verify DHCP settings, and adjust NTP synchronization if necessary.

For further details, refer to the official Pi-hole documentation.

🔗 Related PR / Discussion / Issue

Link: #2485

✅ Prerequisites

Before this PR can be reviewed, the following must be completed:

• Self-review performed – Code follows established patterns and conventions.
• Testing performed – Changes have been thoroughly tested and verified.

🛠️ Type of Change

Select all that apply:

• 🐞 Bug fix – Resolves an issue without breaking functionality.
• ✨ New feature – Adds new, non-breaking functionality.
• 💥 Breaking change – Alters existing functionality in a way that may require updates.