xavye/ascoetpi
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Actualiser pi-hole/install.md

Browse Source
This commit is contained in:
xavye
2026-01-15 16:47:24 +00:00
parent 72e33ec163
commit 994963376c
1 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
pi-hole/install.md Normal file
View File

@@ -0,0 +1,119 @@
<h1>Prerequisites</h1>
<h2 id="ip-addressing"><abbr title="Internet protocol address">IP</abbr> Addressing<a class="headerlink" href="#ip-addressing" title="Permanent link">&para;</a></h2>
<p>Pi-hole needs a static <abbr title="Internet protocol address">IP</abbr> address to properly function (a <abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> reservation is just fine).</p>
<h2 id="ports">Ports<a class="headerlink" href="#ports" title="Permanent link">&para;</a></h2>
<table>
<thead>
<tr>
<th>Service</th>
<th>Port</th>
<th>Protocol</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr></td>
<td>53 (<abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr>)</td>
<td><abbr title="Transmission Control Protocol (protocol providing reliable, ordered, and error-checked delivery of data between applications running on hosts communicating via an IP network)">TCP</abbr>/<abbr title="User Datagram Protocol (a network communications method for sending messages as datagrams)">UDP</abbr></td>
<td>If you happen to have another <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> server running, such as BIND, you will need to turn it off in order for Pi-hole to respond to <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> queries.</td>
</tr>
<tr>
<td>pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr></td>
<td>67 (<abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr>)</td>
<td><abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr> <abbr title="User Datagram Protocol (a network communications method for sending messages as datagrams)">UDP</abbr></td>
<td>The <abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> server is an optional feature that requires additional ports.</td>
</tr>
<tr>
<td>pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr></td>
<td>547 (<abbr title="Dynamic Host Configuration Protocol version 6 (a network protocol for configuring Internet Protocol version 6 (IPv6) hosts with IP addresses)">DHCPv6</abbr>)</td>
<td><abbr title="Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)">IPv6</abbr> <abbr title="User Datagram Protocol (a network communications method for sending messages as datagrams)">UDP</abbr></td>
<td>The <abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> server is an optional feature that requires additional ports.</td>
</tr>
<tr>
<td>pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr></td>
<td>80 (<abbr title="Hypertext Transfer Protocol (HTTP), an application protocol for distributed, collaborative, and hypermedia information systems">HTTP</abbr>)<br/>443 (<abbr title="HTTP Secure (HTTPS), an extension of the Hypertext Transfer Protocol (HTTP) for secure communication over a computer network">HTTPS</abbr>)</td>
<td><abbr title="Transmission Control Protocol (protocol providing reliable, ordered, and error-checked delivery of data between applications running on hosts communicating via an IP network)">TCP</abbr></td>
<td>If you have another webserver already listening on port <code>80</code>/<code>443</code>, then <code>pihole-FTL</code> will attempt to bind to <code>8080</code>/<code>8443</code> instead. If neither of these ports are available, <code>pihole-FTL</code>'s webserver will be unavailable until ports are configured manually (see configuration option <code>webserver.port</code>)</td>
</tr>
<tr>
<td>pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr></td>
<td>123 (<abbr title="Network Time Protocol is used to synchronize the clocks of computers over a network">NTP</abbr>)</td>
<td><abbr title="User Datagram Protocol (a network communications method for sending messages as datagrams)">UDP</abbr></td>
<td>The <abbr title="Network Time Protocol is used to synchronize the clocks of computers over a network">NTP</abbr> server is an optional feature that requires an additional port.</td>
</tr>
</tbody>
</table>
<div class="admonition info">
<p class="admonition-title">Info</p>
<p>The use of pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr> on ports <em>67</em> or <em>547</em> is optional, but required if you use the <abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> functions of Pi-hole.
The use of port <em>123</em> is required when using pihole-<abbr title="Pi-hole's Faster Than Light daemon">FTL</abbr> as <abbr title="Network Time Protocol is used to synchronize the clocks of computers over a network">NTP</abbr>-Server.</p>
</div>
<h2 id="firewalls">Firewalls<a class="headerlink" href="#firewalls" title="Permanent link">&para;</a></h2>
<p>Below are some examples of firewall rules that will need to be set on your Pi-hole server in order to use the functions available. These are only shown as guides, the actual commands used will be found with your distribution's documentation.
Because Pi-hole was designed to work inside a local network, the following rules will block the traffic from the Internet for security reasons. <code>192.168.0.0/16</code> is the most common local network <abbr title="Internet protocol address">IP</abbr> range for home users but it can be different in your case, for example other common local network <abbr title="Internet protocol addresses">IPs</abbr> are <code>10.0.0.0/8</code> and <code>172.16.0.0/12</code>.</p>
<p><strong>Check your local network settings before applying these rules.</strong></p>
<h3 id="iptables">IPTables<a class="headerlink" href="#iptables" title="Permanent link">&para;</a></h3>
<p>IPTables uses two sets of tables. One set is for <abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr> chains, and the second is for <abbr title="Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)">IPv6</abbr> chains. If only <abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr> blocking is used for the Pi-hole installation, only apply the rules for IP4Tables. Full Stack (<abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr> and <abbr title="Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)">IPv6</abbr>) require both sets of rules to be applied. <em>Note: These examples insert the rules at the front of the chain. Please see your distribution's documentation for the exact proper command to use.</em></p>
<p>IPTables (<abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr>)</p>
<div class="highlight"><pre><span></span><code>iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-s<span class="w"> </span><span class="m">192</span>.168.0.0/16<span class="w"> </span>-p<span class="w"> </span>tcp<span class="w"> </span>-m<span class="w"> </span>tcp<span class="w"> </span>--dport<span class="w"> </span><span class="m">80</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-s<span class="w"> </span><span class="m">192</span>.168.0.0/16<span class="w"> </span>-p<span class="w"> </span>tcp<span class="w"> </span>-m<span class="w"> </span>tcp<span class="w"> </span>--dport<span class="w"> </span><span class="m">443</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-s<span class="w"> </span><span class="m">127</span>.0.0.0/8<span class="w"> </span>-p<span class="w"> </span>tcp<span class="w"> </span>-m<span class="w"> </span>tcp<span class="w"> </span>--dport<span class="w"> </span><span class="m">53</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-s<span class="w"> </span><span class="m">127</span>.0.0.0/8<span class="w"> </span>-p<span class="w"> </span>udp<span class="w"> </span>-m<span class="w"> </span>udp<span class="w"> </span>--dport<span class="w"> </span><span class="m">53</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-s<span class="w"> </span><span class="m">192</span>.168.0.0/16<span class="w"> </span>-p<span class="w"> </span>tcp<span class="w"> </span>-m<span class="w"> </span>tcp<span class="w"> </span>--dport<span class="w"> </span><span class="m">53</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-s<span class="w"> </span><span class="m">192</span>.168.0.0/16<span class="w"> </span>-p<span class="w"> </span>udp<span class="w"> </span>-m<span class="w"> </span>udp<span class="w"> </span>--dport<span class="w"> </span><span class="m">53</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-p<span class="w"> </span>udp<span class="w"> </span>--dport<span class="w"> </span><span class="m">67</span>:68<span class="w"> </span>--sport<span class="w"> </span><span class="m">67</span>:68<span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span><span class="m">1</span><span class="w"> </span>-p<span class="w"> </span>udp<span class="w"> </span>--dport<span class="w"> </span><span class="m">123</span><span class="w"> </span>-j<span class="w"> </span>ACCEPT
iptables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span>-m<span class="w"> </span>conntrack<span class="w"> </span>--ctstate<span class="w"> </span>RELATED,ESTABLISHED<span class="w"> </span>-j<span class="w"> </span>ACCEPT
</code></pre></div>
<p>IP6Tables (<abbr title="Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)">IPv6</abbr>)</p>
<div class="highlight"><pre><span></span><code>ip6tables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span>-p<span class="w"> </span>udp<span class="w"> </span>-m<span class="w"> </span>udp<span class="w"> </span>--sport<span class="w"> </span><span class="m">546</span>:547<span class="w"> </span>--dport<span class="w"> </span><span class="m">546</span>:547<span class="w"> </span>-j<span class="w"> </span>ACCEPT
ip6tables<span class="w"> </span>-I<span class="w"> </span>INPUT<span class="w"> </span>-m<span class="w"> </span>conntrack<span class="w"> </span>--ctstate<span class="w"> </span>RELATED,ESTABLISHED<span class="w"> </span>-j<span class="w"> </span>ACCEPT
</code></pre></div>
<h3 id="firewalld">FirewallD<a class="headerlink" href="#firewalld" title="Permanent link">&para;</a></h3>
<p>Using the <code>--permanent</code> argument will ensure the firewall rules persist reboots. If only <abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr> blocking is used for the Pi-hole installation, the <code>dhcpv6</code> service can be removed from the commands below. Finally <code>--reload</code> to have the new firewall configuration take effect immediately.</p>
<div class="highlight"><pre><span></span><code>firewall-cmd<span class="w"> </span>--permanent<span class="w"> </span>--add-service<span class="o">=</span>http<span class="w"> </span>--add-service<span class="o">=</span>https<span class="w"> </span>--add-service<span class="o">=</span>dns<span class="w"> </span>--add-service<span class="o">=</span>dhcp<span class="w"> </span>--add-service<span class="o">=</span>dhcpv6<span class="w"> </span>--add-service<span class="o">=</span>ntp
firewall-cmd<span class="w"> </span>--reload
</code></pre></div>
<h3 id="ufw">ufw<a class="headerlink" href="#ufw" title="Permanent link">&para;</a></h3>
<p>ufw stores all rules persistently, so you just need to execute the commands below.</p>
<p><abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr>:</p>
<div class="highlight"><pre><span></span><code>ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">80</span>/tcp
ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">443</span>/tcp
ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">53</span>/tcp
ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">53</span>/udp
ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">67</span>/tcp
ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">67</span>/udp
ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">123</span>/udp
</code></pre></div>
<p><abbr title="Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)">IPv6</abbr> (include above <abbr title="Internet Protocol version 4 (addresses like 192.168.0.1)">IPv4</abbr> rules):</p>
<div class="highlight"><pre><span></span><code>ufw<span class="w"> </span>allow<span class="w"> </span><span class="m">546</span>:547/udp
</code></pre></div>
<h1>Post-Install</h1>
<h2 id="making-your-network-take-advantage-of-pi-hole">Making your network take advantage of Pi-hole<a class="headerlink" href="#making-your-network-take-advantage-of-pi-hole" title="Permanent link">&para;</a></h2>
<p>Once the installer has been run, you will need to <a href="https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245">configure your router to have <strong><abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> clients use Pi-hole as their <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> server</strong></a> which ensures all devices connected to your network will have content blocked without any further intervention.</p>
<p>If your router does not support setting the <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> server, you can <a href="https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026">use Pi-hole's built-in <abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> server</a>; just be sure to disable <abbr title="Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)">DHCP</abbr> on your router first (if it has that feature available).</p>
<p>As a last resort, you can manually set each device to use Pi-hole as its <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> server.</p>
<h2 id="making-your-pi-hole-host-use-pi-hole">Making your Pi-hole host use Pi-hole<a class="headerlink" href="#making-your-pi-hole-host-use-pi-hole" title="Permanent link">&para;</a></h2>
<p>Pi-hole will not be used by the host automatically after installation. To have the host resolve through Pi-hole and your configured blocking lists, you can make the host use Pi-hole as upstream <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> server:</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>If your Pi-hole host is using Pi-hole as upstream <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> server and Pi-hole fails, your host loses <abbr title="Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)">DNS</abbr> resolution. This can prevent successful repair attempts, e.g. by <code>pihole -r</code> as it needs a working internet connection.</p>
</div>
<p>If your <abbr title="Operating system">OS</abbr> uses <code>dhcpcd</code> for network configuration, you can add to your <code>/etc/dhcpcd.conf</code></p>
<div class="highlight"><pre><span></span><code>static domain_name_servers=127.0.0.1
</code></pre></div>
<h2 id="adding-your-local-user-to-the-pihole-group">Adding your local user to the 'pihole' group<a class="headerlink" href="#adding-your-local-user-to-the-pihole-group" title="Permanent link">&para;</a></h2>
<p>Pi-hole v6 uses a new <abbr title="Application Programming Interface (a set of subroutine definitions, protocols, and tools for building application software)">API</abbr> for authentication. All <abbr title="Command-line Interface">CLI</abbr> commands use this <abbr title="Application Programming Interface (a set of subroutine definitions, protocols, and tools for building application software)">API</abbr> instead of e.g. direct database manipulation. If a password is set for <abbr title="Application Programming Interface (a set of subroutine definitions, protocols, and tools for building application software)">API</abbr> access, the <abbr title="Command-line Interface">CLI</abbr> commands also need to authenticate. To avoid entering the password everytime on <abbr title="Command-line Interface">CLI</abbr>, Pi-hole allows users which are members of the 'pihole' group to authenticate without manually entering the password (this can be disabled by setting <code>webserver.api.cli_pw</code> to <code>false</code>.)
To add your local user to the 'pihole' group use the following command</p>
<p>For Debian/Ubuntu/Raspberry Pi <abbr title="Operating system">OS</abbr>/Armbian/Fedora/CentOS</p>
<div class="highlight"><pre><span></span><code>sudo usermod -aG pihole $USER
</code></pre></div>
<p>For Alpine</p>
<div class="highlight"><pre><span></span><code>sudo addgroup pihole $USER
</code></pre></div>