Merge branch 'master' into ftldns/dnsmasq_details

Signed-off-by: DL6ER <dl6er@dl6er.de>

Conflicts:
	mkdocs.yml

README.md

@@ -6,7 +6,7 @@ Linux Mint / Ubuntu instructions:
 git clone git@github.com:pi-hole/docs.git
 cd docs
 sudo pip install mkdocs
-sudo pip install mkdocs-material
+sudo pip install mkdocs-material markdown-include
 mkdocs serve --dev-addr 0.0.0.0:8000
 ```
 

docs/abbreviations.md

@@ -0,0 +1,36 @@
+
+*[DNS]: Domain Name Service (decentralized naming system for computers, services, or other resources connected to the Internet)
+*[FTL]: Pi-hole's Faster Than Light daemon
+*[DHCP]: Dynamic Host Configuration Protocol (network management protocol for configuring Internet Protocol version 4 (IPv4) hosts with IP addresses)
+*[DHCPv6]: Dynamic Host Configuration Protocol version 6 (a network protocol for configuring Internet Protocol version 6 (IPv6) hosts with IP addresses)
+*[IPv4]: Internet Protocol version 4 (addresses like 192.168.0.1)
+*[IPv6]: Internet Protocol version 6 (addresses like 2001:db8::ff00:42:8329)
+*[HTTP]: Hypertext Transfer Protocol (HTTP), an application protocol for distributed, collaborative, and hypermedia information systems
+*[HTTPS]: HTTP Secure (HTTPS), an extension of the Hypertext Transfer Protocol (HTTP) for secure communication over a computer network
+*[TCP]: Transmission Control Protocol (protocol providing reliable, ordered, and error-checked delivery of data between applications running on hosts communicating via an IP network)
+*[UDP]: User Datagram Protocol (a network communications method for sending messages as datagrams)
+*[API]: Application Programming Interface (a set of subroutine definitions, protocols, and tools for building application software)
+*[PID]: Process identifier (a number used to identify a process)
+*[HOSTS]: The computer file /etc/hosts is an operating system file that maps hostnames to IP addresses
+*[POSIX]: Portable Operating System Interface (a family of standards specified by the IEEE Computer Society for maintaining compatibility between operating systems)
+*[Ext2]: second extended filesystem is a file system for the Linux kernel (introduced 1993)
+*[Ext3]: third extended filesystem is a file system for the Linux kernel (introduced 2001)
+*[Ext4]: fourth extended filesystem is a file system for the Linux kernel (stable as of 2008)
+*[Btrfs]: B-tree file system
+*[JFS]: journaling file system by IBM
+*[XFS]: journaling file system created by Silicon Graphics, Inc
+*[ReiserFS]: general-purpose, journaled computer file system
+*[ERE]: Extended Regular Expressions
+*[TLD]: Top-level domain (domains at the highest level in the hierarchical Domain Name System of the Internet., e.g. ".com", ".org", etc.)
+*[IP]: Internet protocol address
+*[IPs]: Internet protocol addresses
+*[CPU]: Central processing unit, also known as "processor"
+*[CLI]: Command Line Interface
+*[OS]: Operating system
+*[GCC]: the GNU compiler collection (compiler system produced by the GNU Project supporting various programming languages)
+*[repo]: Repository on GitHub
+*[RegEx]: Regular expression
+*[SQLite3]: Database engine that handles an SQL databases in a file
+*[ID]: Indentifier
+*[SSH]: Secure Shell is a cryptographic network protocol for operating network services securely over an unsecured network
+*[TFTP]: Trivial File Transfer Protocol is a simple lockstep File Transfer Protocol which allows a client to get a file from or put a file onto a remote host

docs/ftldns/blockingmode.md

@@ -42,3 +42,5 @@ Queries DNS queries will be answered with an empty response (no answer section)
 
 ##### Disadvantage
 - Blocking page cannot be shown and whitelisting has to be performed from the dashboard or CLI
+
+{!abbreviations.md!}

docs/ftldns/compatibility.md

@@ -20,3 +20,5 @@ We tested *FTL*DNS on the following devices:
 <!-- |  |  |  |  |  | -->
 
 Devices we do not officially support include MIPS and `armv5` (or lower) devices. You may, however, be successful with building binaries yourself from the source code, but we do not provide pre-built binaries for these targets.
+
+{!abbreviations.md!}

docs/ftldns/compile.md

@@ -36,3 +36,5 @@ Finally, restart *FTL*DNS to use the new binary:
 ```
 sudo service pihole-FTL restart
 ```
+
+{!abbreviations.md!}

docs/ftldns/configfile.md

@@ -45,7 +45,7 @@ How often do we store queries in FTL's database [minutes]?
 ### DBFILE
 `DBFILE=/etc/pihole/pihole-FTL.db`
 
-Specify path and filename of FTL's SQLite long-term database. Setting this to `DBFILE=` disables the database altogether
+Specify path and filename of FTL's SQLite3 long-term database. Setting this to `DBFILE=` disables the database altogether
 
 **[More details](database.md)**
 
@@ -84,3 +84,5 @@ Should `FTL` reply queries to blocked domains with IPs or `NXDOMAIN`?
 If defined, `FTL` will block all incoming queries which match this RegEx.
 
 **[More details](regex.md)**
+
+{!abbreviations.md!}

docs/ftldns/database.md

@@ -100,3 +100,5 @@ www.pi-hole.net|132483
 posteo.de|130243
 ```
 showing the domain and the number of times it was found in the long-term database. Note that such a request might take very long for computation as the entire history of queries have to be processed for this.
+
+{!abbreviations.md!}

docs/ftldns/debugging.md

@@ -10,3 +10,5 @@ Once you are used to it, you can skip most of the steps. Debugging *FTL*DNS is a
 7. When `pihole-FTL` has crashed, copy&paste the terminal output into a (new) issue. Also type `backtrace` and include its output. We might ask for additional information in order to isolate your particular issue.
 
 <!-- When you want to detach the debugger from `FTL` without terminating the process, you can hit `Ctrl+C` and enter `detach` followed by `quit`. -->
+
+{!abbreviations.md!}

docs/ftldns/dns-resolver.md

@@ -21,3 +21,5 @@ The DNS forward destination determination algorithm in *FTL*DNS's is modified to
 We keep the exceptions, i.e., we try all possible forward destinations if `SERVFAIL` or `REFUSED` is received or if a timeout occurs.
 Overall, this change has proven to greatly reduce the number of actually performed queries in typical Pi-hole environments. It may even be understood as being preferential in terms of privacy (as we send queries much less often to all servers).
 This has been implemented in commit [d1c163e](https://github.com/pi-hole/FTL/commit/d1c163e499a5cd9f311610e9da1e9365bbf81e89) on the `FTLDNS` branch.
+
+{!abbreviations.md!}

docs/ftldns/in-depth.md

@@ -38,7 +38,9 @@ However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among som
 We specifically add the following capabilities to `pihole-FTL`:
 
 - `CAP_NET_BIND_SERVICE`: Allows *FTL*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
-- `CAP_NET_RAW`: use RAW and PACKET sockets (we need a RAW socket for handling DHCPv6 requests)
+- `CAP_NET_RAW`: use raw and packet sockets (we need a RAW socket for handling DHCPv6 requests)
 - `CAP_NET_ADMIN`: modify routing tables and other network-related operations (to allow for handling DHCP requests)
 
 Users that cannot use Linux capabilites for various reasons (lacking kernel or file system support) can modify the startup scripts of `pihole-FTL` to ensure the daemon is started as `root`. However, be aware of that you do so on your own risk (although we don't expect problems to arise).
+
+{!abbreviations.md!}

docs/ftldns/index.md

@@ -3,3 +3,4 @@
 *FTL*DNS[™](https://pi-hole.net/trademark-rules-and-brand-guidelines/) (`pihole-FTL`) offers DNS services within the Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) project.
 It provides blazing fast DNS and DHCP services. It can also provide TFTP and more as the resolver part based on the popular `dnsmasq`. Furthermore, FTL offers an interactive API where extensive network analysis data and statistics may be queried.
 
+{!abbreviations.md!}

docs/ftldns/privacylevels.md

@@ -34,3 +34,5 @@ This setting disables
 - Clients over time
 - Query Log
 - Long-term database logging
+
+{!abbreviations.md!}

docs/ftldns/regex.md

@@ -1,5 +1,5 @@
 A regular expression, or RegEx for short, is a pattern that can be used for building arbitrarily complex blocking rules in *FTL*DNS.
-We implement the Extended Regular Expressions (ERE) flavor similar to the one used by the UNIX `egrep` (or `grep -E`) command.
+We implement the ERE flavor similar to the one used by the UNIX `egrep` (or `grep -E`) command.
 
 Our implementation is computationally inexpensive as each domain is only checked once for a match (if you query `google.com`, it will be checked against your RegEx. Any subsequent query to the same domain will not be checked again until you restart `pihole-FTL`).
 
@@ -132,3 +132,5 @@ Expression | Meaning | Example
 `[^]`| Negation | `[^0-9]` matches any character *except* `0` to `9`
 `{ }` | Matches a specified number of occurrences of the previous  | `[0-9]{3}` matches any three-digit number like `315` but not `31`;<br>`[0-9]{2,4}` matches two- to four-digit numbers like `12`, `123`, and `1234` but not `1` or `12345`;<br>`[0-9]{2,}` matches any number with two or more digits like `1234567`, `123456789`, but not `1`
 `\` | Used to escape a special character not inside `[]` | `google\.com` matches `google.com`
+
+{!abbreviations.md!}

docs/ftldns/telnet-api.md

@@ -2,7 +2,7 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1
 
 - `>quit`: Closes connection to client
 
-- `>kill`: Terminates FTL
+- `>kill`: Terminates `FTL`
 
 - `>stats` : Get current statistics
  ```
@@ -121,7 +121,7 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1
  date 2017-03-26 13:10:43 +0200
  ```
 
-- `>dbstats` : Get some statistics about the FTL long-term storage database (this request may take some time for processing in case of a large database file)
+- `>dbstats` : Get some statistics about `FTL`'s' long-term storage database (this request may take some time for processing in case of a large database file)
  ```
  queries in database: 2700304
  database filesize: 199.20 MB
@@ -142,3 +142,5 @@ Connect via e.g. `telnet 127.0.0.1 4711` or use `echo ">command" | nc 127.0.0.1
  cache-live-freed: 0
  cache-inserted: 15529
  ```
+
+{!abbreviations.md!}

docs/index.md

@@ -38,3 +38,5 @@ Issues should be reported on the repositories:
 ## Social Media
 - Twitter : [@the_pi_hole](https://twitter.com/the_pi_hole)
 - Facebook :  [ThePiHole](https://facebook.com/ThePiHole)
+
+{!abbreviations.md!}

docs/main/basic-install.md

@@ -7,8 +7,8 @@ curl -sSL https://install.pi-hole.net | bash
 
 !!! info
     [Piping to `bash` is a controversial topic](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash), as it prevents you from [reading code that is about to run](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) on your system.
-     
-    If you would prefer to review the code before installation, we provide these alternative installation methods. 
+
+    If you would prefer to review the code before installation, we provide these alternative installation methods.
 
 #### Alternative 1: Clone our repository and run
 ```BASH
@@ -21,4 +21,6 @@ sudo bash basic-install.sh
 ```BASH
 wget -O basic-install.sh https://install.pi-hole.net
 sudo bash basic-install.sh
-```
+```
+
+{!abbreviations.md!}

docs/main/post-install.md

@@ -4,4 +4,6 @@ Once the installer has been run, you will need to [configure your router to have
 
 If your router does not support setting the DNS server, you can [use Pi-hole's built in DHCP server](https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026); just be sure to disable DHCP on your router first (if it has that feature available).
 
-As a last resort, you can always manually set each device to use Pi-hole as their DNS server.
+As a last resort, you can always manually set each device to use Pi-hole as their DNS server.
+
+{!abbreviations.md!}

docs/main/prerequesites.md

@@ -4,8 +4,8 @@ Pi-hole is very lightweight, and does not require much processing power
 - ~52MB of free space
 - 512MB RAM
 
-Despite the name, you are not limited to running Pi-hole on a Raspberry Pi. 
-Any hardware that runs one of the supported operating systems will do! 
+Despite the name, you are not limited to running Pi-hole on a Raspberry Pi.
+Any hardware that runs one of the supported operating systems will do!
 
 ###Supported Operating Systems
 
@@ -19,9 +19,9 @@ The following operating systems are **officially** supported:
 
 ###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`.  
+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`.
 
-As part of our install process, **we append some lines to `/etc/dhcpcd.conf` in order to statically assign an IP address**, so take note of this prior to installing. 
+As part of our install process, **we append some lines to `/etc/dhcpcd.conf` in order to statically assign an IP address**, so take note of this prior to installing.
 
 Please be aware of this fact because it [may cause confusion](https://github.com/pi-hole/pi-hole/issues/1713#issue-260746084).  This is not the ideal situation for us to be in, but since a significant portion of our users are running Pi-hole on Raspbian; and because Pi-hole's roots began with the Raspberry Pi, it's a problem that is [difficult problem to get away from](https://github.com/pi-hole/pi-hole/issues/1713#issuecomment-332317532).
 
@@ -36,4 +36,6 @@ Due to the complexity of different ways of setting an IP address across differen
 |pihole-FTL | 4711|FTL is our API engine and by default uses port 4711, but will increment if it's already in use by something else.|
 
 !!! info
-    The use of lighttpd on port _80_ is optional if you decide not to install the Web dashboard during installation.
+    The use of lighttpd on port _80_ is optional if you decide not to install the Web dashboard during installation.
+
+{!abbreviations.md!}

docs/main/update.md

@@ -4,4 +4,6 @@ Updating is as simple as running the following command:
 
 ### Common issues with updating:
 
-`[Placeholder for solutions to issues]`
+`[Placeholder for solutions to issues]`
+
+{!abbreviations.md!}