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/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/mkdocs.yml b/mkdocs.yml index 9bf929f..09c7ae9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,15 +8,30 @@ theme: language: 'en' markdown_extensions: +# Code highlighting in ``` ``` blocks - codehilite(guess_lang=true) +# Table of Contents - toc(permalink=true) +# block-styled side content - admonition +# linkafies URL and email links without having to wrap them in Markdown syntax. Also, allows shortens repository issue, pull request, and commit links. - pymdownx.magiclink +# Task lists (https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/) - pymdownx.tasklist(custom_checkbox=true) +# Highlight words with ==mark me== - pymdownx.mark +# Adds support for deletion ~~Delete me~~ and subscript text~a\ subscript~ - pymdownx.tilde +# This extension is a convenience extension, and it currently provides no other additional features - pymdownx.extra +# Adds syntax for defining footnotes in Markdown documents (https://python-markdown.github.io/extensions/footnotes/) - footnotes +# Typograph extension + - smarty +# Adds the ability to define abbreviations + - abbr +# Include files in other documents like {!some/dir/in/docs/filename.md!} + - markdown_include.include(base_path=docs) pages: - 'Overview & Support': 'index.md' - 'Getting Started':