Merge pull request #328 from pi-hole/release/v5.1

Documentation for Pi-hole v5.1
2024-12-06 19:27:12 +01:00 · 2020-07-16 00:30:13 +02:00
parent 5ef467b534 b8e4248b98
commit 7aaa90f7b0
4 changed files with 65 additions and 20 deletions
@@ -1,51 +1,82 @@
 We pre-compile *FTL*DNS for you to save you the trouble of compiling anything yourself. However, sometimes you may want to make your own modifications. To test them, you have to compile *FTL*DNS from source. Luckily, you don't have to be a programmer to build *FTL*DNS from source and install it on your system; you only have to know the basics we provide in here. With just a few commands, you can build *FTL*DNS from source like a pro.

-#### Installing the Required Software
+## Installing the Required Software

 First, we'll install the basic software you'll need to compile from source, like the GCC compiler and other utilities.
 Install them by running the following command in a terminal:

-##### Debian / Ubuntu / Raspbian
+### Debian / Ubuntu / Raspbian

 ```bash
-sudo apt install build-essential libgmp-dev m4
+sudo apt install build-essential libgmp-dev m4 cmake libidn11-dev
 ```

-##### Fedora
+### Fedora

 ```bash
-sudo dnf install gcc gmp-devel gmp-static m4
+sudo dnf install gcc gmp-devel gmp-static m4 cmake libidn-devel
 ```

---
+## Compile `libnettle` from source

-You'll also need to compile `nettle` as *FTL*DNS uses `libnettle` for handling DNSSEC. Compile and install a recent version of `nettle` (we tested and recommend 3.6):
+*FTL*DNS uses a cryptographic library (`libnettle`) for handling DNSSEC signatures.
+Compile and install a recent version using:

 ```bash
 wget https://ftp.gnu.org/gnu/nettle/nettle-3.6.tar.gz
-tar -xvzf nettle-3.6.tar.gz
+tar -xzf nettle-3.6.tar.gz
 cd nettle-3.6
-./configure
-make
+./configure --libdir=/usr/local/lib
+make -j $(nproc)
 sudo make install
 ```

-#### Get the *FTL*DNS source
+Since Ubuntu 20.04, you need to specify the library directory explicitly. Otherwise, the library will be installed in custom locations where it would not be found by `cmake`.
+
+## Get the source

 Now, clone the *FTL*DNS repo (or your own fork) to get the source code of *FTL*DNS:

 ```bash
-git clone https://github.com/pi-hole/FTL.git
-cd FTL
+git clone https://github.com/pi-hole/FTL.git && cd FTL
 ```

-If you want to build another branch and not `master`, use checkout to get to this branch (e.g. `git checkout development`).
-
-*FTL*DNS can now be compiled and installed:
+If you want to build another branch and not `master`, use checkout to get to this branch, like

 ```bash
-make -j $(nproc)
-sudo make install
+git checkout development
+```
+
+## Compile the source
+
+*FTL*DNS can now be compiled using either the build script
+
+```bash
+./build.sh
+```
+
+or manually
+
+```bash
+mkdir -p cmake && cd cmake
+cmake ..
+cmake --build . -- -j $(nproc)
+```
+
+Note that both ways are exactly equivalent and that you do not need `root` priviledges here.
+
+## Install the new binary system-wide
+
+Install the new binary using either
+
+```bash
+./build.sh install
+```
+
+or
+
+```bash
+cd cmake && sudo make install
 ```

 Finally, restart *FTL*DNS to use the new binary:
@@ -34,7 +34,7 @@ Should `FTL` ignore queries coming from the local machine?

 #### `AAAA_QUERY_ANALYSIS=yes|no` {#aaaa_query_analysis data-toc-label='AAAA Query Analysis'}

-Allow `FTL` to analyze AAAA queries from pihole.log?
+Should FTL analyze `AAAA` queries? The DNS server will handle `AAAA` queries the same way, reglardless of this setting. All this does is ignoring `AAAA` queries when computing the statistics of Pi-hole. This setting is considered obsolete may may be removed in a future version.

 #### `ANALYZE_ONLY_A_AND_AAAA=false|true` {#analyze_only_a_and_aaaa data-toc-label='Analyze A and AAAA Only'}

@@ -25,11 +25,25 @@ The following operating systems are **officially** supported:
 | Distribution | Release          | Architecture        |
 | ------------ | ---------------- | ------------------- |
 | Raspbian     | Stretch / Buster | ARM                 |
-| Ubuntu       | 16.x / 18.x      | ARM / x86_64        |
+| Ubuntu       | 16.x / 18.x / 20.x      | ARM / x86_64        |
 | Debian       | 9 / 10           | ARM / x86_64 / i386 |
 | Fedora       | 31 / 32          | ARM / x86_64        |
 | CentOS       | 7 / 8            | x86_64              |

+<!-- markdownlint-disable code-block-style -->
+!!! info
+    One of the first tasks the install script has is to determine your Operating System's compatibility with Pi-hole
+
+    It is possible that Pi-hole will install and run on variants of the above, but we cannot test them all. If you are using an operating system not on this list you may see the following message:
+
+    ![non-supported OS warning](../images/OSWarning.png)
+
+    You can disable this check by setting an environment variable named `PIHOLE_SKIP_OS_CHECK` to `true`, however Pi-hole may have issues installing.
+    If you choose to use this environment variable, please use the [Community Help](https://discourse.pi-hole.net/c/bugs-problems-issues/community-help/36) topic on Discourse to troubleshoot any installation issues you may (or may not!) have.
+
+
+<!-- markdownlint-enable code-block-style -->
+
 ### IP Addressing

 Pi-hole needs a static IP address to properly function (a DHCP reservation is just fine). Users may run into issues because **we currently install `dhcpcd5`, which may conflict with other running network managers** such as `dhclient`, `dhcpcd`, `networkmanager`, and `systemd-networkd`.