diff --git a/README.md b/README.md index 8531803..8dd03f0 100644 --- a/README.md +++ b/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 ``` diff --git a/docs/abbreviations.md b/docs/abbreviations.md new file mode 100644 index 0000000..52e7a0e --- /dev/null +++ b/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 diff --git a/docs/ftldns/blockingmode.md b/docs/ftldns/blockingmode.md index 244f5ac..9c818ba 100644 --- a/docs/ftldns/blockingmode.md +++ b/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!} diff --git a/docs/ftldns/compatibility.md b/docs/ftldns/compatibility.md index 8ccfc21..c705780 100644 --- a/docs/ftldns/compatibility.md +++ b/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!} diff --git a/docs/ftldns/compile.md b/docs/ftldns/compile.md index 5b8d835..161c18f 100644 --- a/docs/ftldns/compile.md +++ b/docs/ftldns/compile.md @@ -36,3 +36,5 @@ Finally, restart *FTL*DNS to use the new binary: ``` sudo service pihole-FTL restart ``` + +{!abbreviations.md!} diff --git a/docs/ftldns/configfile.md b/docs/ftldns/configfile.md index baa02da..f660f06 100644 --- a/docs/ftldns/configfile.md +++ b/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!} diff --git a/docs/ftldns/database.md b/docs/ftldns/database.md index 582fc53..5379770 100644 --- a/docs/ftldns/database.md +++ b/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!} diff --git a/docs/ftldns/debugging.md b/docs/ftldns/debugging.md index 066f1f4..c85479a 100644 --- a/docs/ftldns/debugging.md +++ b/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. + +{!abbreviations.md!} diff --git a/docs/ftldns/dns-resolver.md b/docs/ftldns/dns-resolver.md index bdcc9d8..868f268 100644 --- a/docs/ftldns/dns-resolver.md +++ b/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!} diff --git a/docs/ftldns/in-depth.md b/docs/ftldns/in-depth.md index 6ea449e..6023c7e 100644 --- a/docs/ftldns/in-depth.md +++ b/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!} diff --git a/docs/ftldns/index.md b/docs/ftldns/index.md index 7af0648..cb835ac 100644 --- a/docs/ftldns/index.md +++ b/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!} diff --git a/docs/ftldns/privacylevels.md b/docs/ftldns/privacylevels.md index e11ec95..82a47ce 100644 --- a/docs/ftldns/privacylevels.md +++ b/docs/ftldns/privacylevels.md @@ -34,3 +34,5 @@ This setting disables - Clients over time - Query Log - Long-term database logging + +{!abbreviations.md!} diff --git a/docs/ftldns/regex.md b/docs/ftldns/regex.md index 8b7ac78..4a0d186 100644 --- a/docs/ftldns/regex.md +++ b/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`;
`[0-9]{2,4}` matches two- to four-digit numbers like `12`, `123`, and `1234` but not `1` or `12345`;
`[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!} diff --git a/docs/ftldns/telnet-api.md b/docs/ftldns/telnet-api.md index 8650fc4..00ac35d 100644 --- a/docs/ftldns/telnet-api.md +++ b/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!} diff --git a/docs/index.md b/docs/index.md index 5652d80..10f8820 100644 --- a/docs/index.md +++ b/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!} diff --git a/docs/main/basic-install.md b/docs/main/basic-install.md index 021d588..6ebed49 100644 --- a/docs/main/basic-install.md +++ b/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 -``` \ No newline at end of file +``` + +{!abbreviations.md!} diff --git a/docs/main/post-install.md b/docs/main/post-install.md index b2fc5db..ab3aef9 100644 --- a/docs/main/post-install.md +++ b/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. \ No newline at end of file +As a last resort, you can always manually set each device to use Pi-hole as their DNS server. + +{!abbreviations.md!} diff --git a/docs/main/prerequesites.md b/docs/main/prerequesites.md index a05b327..3a2836f 100644 --- a/docs/main/prerequesites.md +++ b/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. \ No newline at end of file + The use of lighttpd on port _80_ is optional if you decide not to install the Web dashboard during installation. + +{!abbreviations.md!} diff --git a/docs/main/update.md b/docs/main/update.md index 5894f35..61299c3 100644 --- a/docs/main/update.md +++ b/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]` \ No newline at end of file +`[Placeholder for solutions to issues]` + +{!abbreviations.md!}