Skip to content

Home

Jump to bottom Edit New page
Jack'lul edited this page Nov 7, 2025 · 35 revisions

Pi-hole for Entware wiki

Table of contents:

Requirements

  • Entware installed in standard mode
  • Your device's CPU must support one of these architectures: AArch64, ARMv7, x86_64
  • You will need around 100-150 MB of free memory to run this
    • Around 50 MB for the daemon and 50-100 MB more to be able to update the gravity database
    • Memory requirements increase as you add more blocklists
  • Swap file is highly recommended

Installation

Warning

Pi-hole is normally installed through an official installer, unfortunately there is no way to make it compatible with Entware and with every device.
Installing this package does not run the official installer, so a lot of things the installer would normally do are set to defaults or must be done manually.

Note

For device or firmware specific guides please check the sidebar!

Installing the package

  1. Install Entware first - check their wiki for instructions

  2. Add this repository to OPKG configuration by appending the following line to /opt/etc/opkg.conf:

src/gz pi-hole https://jacklul.github.io/entware-pi-hole/[architecture]
# see the table below for available values
Architecture URL
AArch64 https://jacklul.github.io/entware-pi-hole/aarch64-k3.10/
ARMv7 https://jacklul.github.io/entware-pi-hole/armv7sf-k3.2/
x86_64 https://jacklul.github.io/entware-pi-hole/x64-k3.2/
  1. Install the package: opkg update && opkg install pi-hole

Note

If OPKG fails to fetch from the repository due to wget error - install required packages to support HTTPS repositories - opkg install wget-ssl ca-certificates.

Launching the service

Important

Pi-hole expects pihole user to be available in the system (/etc/passwd, /etc/group), it should be added as a system user without a login shell.
Unfortunately, there is no universal way to do this that will work on every device so you will have to do some research.
As a fallback, the provided init.d script can start the service as the user nobody or even root but please note that this not an officially supported method and some issues may occur.

Warning

If the default ports are taken then the service will fail to start!

To start the Pi-hole service run: /opt/etc/init.d/S65pihole-FTL start

Configuration

After successfully starting the service and gaining access to the web interface go to Settings -> DNS section and configure your upstream DNS servers and DNS domain settings, there are also a few more options there which depend on your preference.

Remember that you have to configure your devices to use the Pi-hole as their DNS server.
Please consult the official Pi-hole documentation for more information.

Recommendations

Note

Since version 2025.09.04-1 these changes are applied automatically for new installs (when pihole.toml is missing).

The following changes in /opt/etc/pihole/pihole.toml are recommended:

# Disable query logging to pihole.log file to reduce the writes to storage drive
[dns]
  queryLogging = false

# Disable NTP features as they may interfere with firmware time sync
[ntp]
  [ntp.ipv4]
    active = false # Disable IPv4 NTP server
  [ntp.ipv6]
    active = false # Disable IPv6 NTP server
  [ntp.sync]
    active = false # Disable NTP synchronization

# Reduce the maximum number of days to keep the queries in the database to reduce database size
[database]
  maxDBdays = 31

# Reduce the maximum number of threads for the webserver to reduce memory usage
[webserver]
  threads = 10

[misc]
  # Do not change the priority of the process as it may deprioritize system services
  nice = -999

Support

Because how different each device can be I won't be able to help with every issue that can be device-specific but feel free to report them anyway.

Potential issues

Ports conflict

Pi-hole tries to bind on ports 53, 80 and 443 by default which may be in use by your device's firmware.
If the service fails to start then check the log files in /opt/var/log/pihole to figure out which ports to change in /opt/etc/pihole/pihole.toml.

Change the ports to something that will be less likely used:

/opt/bin/pihole-FTL --config dns.port 5053
/opt/bin/pihole-FTL --config webserver.port "5080,5443s"

NTP sync conflict

Pi-hole comes with NTP server and time synchronization feature enabled by default which may interfere with your device's firmware, the best solution is to disable those:

/opt/bin/pihole-FTL --config ntp.ipv4.active false
/opt/bin/pihole-FTL --config ntp.ipv6.active false
/opt/bin/pihole-FTL --config ntp.sync.active false

pi.hole domain not opening Pi-hole's web interface

Most embedded devices already run their web server on port 80 so you will not be able to use pi.hole to access Pi-hole's web interface.
The solution for this is to create a dedicated IP address for the Pi-hole's webserver to listen on.

dnsmasq warning: using interface X instead

This warning can be safely ignored as it only indicates that one of the interfaces is either virtual or labeled.

mptcp_add_sock failed in syslog

This error might show in syslog - could be a bug in the kernel, mptcp module or caused by Pi-hole FTL.
To get rid of this message spam you will have to disable MPTCP (echo 0 > /proc/sys/net/mptcp/mptcp_enabled).
Do not disable this if you're using any kind of link aggregation as it will break it.

Add a custom footer

Pi-hole for Entware wiki

Device-specific installation:

Extras:


Clone this wiki locally