From ed1a6914a78d9f648a2d0af7477a700cb2159d98 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Thu, 3 May 2018 20:45:41 +0200 Subject: [PATCH] Add linux capabilites section Signed-off-by: DL6ER --- docs/extra.css | 5 +++-- docs/ftldns/in-depth.md | 14 ++++++++++++++ mkdocs.yml | 4 +++- 3 files changed, 20 insertions(+), 3 deletions(-) create mode 100644 docs/ftldns/in-depth.md diff --git a/docs/extra.css b/docs/extra.css index ebe9442..8b0999f 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -11,7 +11,8 @@ body, input { font-family: "Source Sans Pro", "Roboto","Helvetica Neue",Helvetica,Arial,sans-serif; color: black; } -code { +.md-typeset code, .md-typeset pre { display: inline-block; white-space: pre-wrap; -} \ No newline at end of file + color: rgb(83, 43, 168); +} diff --git a/docs/ftldns/in-depth.md b/docs/ftldns/in-depth.md new file mode 100644 index 0000000..3d29282 --- /dev/null +++ b/docs/ftldns/in-depth.md @@ -0,0 +1,14 @@ +## Linux capabilites +Capabilities (POSIX 1003.1e, [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html)) provide fine-grained control over superuser permissions, allowing use of the `root` user to be avoided. +For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: *privileged processes* (superuser or `root`), and *unprivileged processes*. Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (user and grounp permissions and supplementary process capabilities). Capabilities are implemented on Linux using extended attributes ([xattr(7)](http://man7.org/linux/man-pages/man5/attr.5.html)) in the `security` namespace. Extended attributes are supported by all major Linux file systems, including Ext2, Ext3, Ext4, Btrfs, JFS, XFS, and Reiserfs. + +For your safety and comfort, `pihole-FTL` is run by the entirely unpriviledged user `pihole`. +Wheras `dnsmasq` is running as `root` process, we designed `pihole-FTL` to be run by the entirely unpriviledged user `pihole`. As a consequence, `pihole-FTL` will not be able to access the files of any other user on this system or mess around with your system's configuration. + +However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among some other necessary capabilites related to DHCP services. To establish a strong security model, we explicitly grant the `pihole-FTL` process additional capabilities so that `pihole-FTL` (but no other processes which may be started by `pihole`) can bind to port 53, etc., without giving any additional permissions to the `pihole` user. + +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_ADMIN`: modify routing tables and other network-related operations (to allow for handling DHCP requests) diff --git a/mkdocs.yml b/mkdocs.yml index e862607..fca4da9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,7 +24,9 @@ pages: - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' - 'Updating': 'main/update.md' -- 'FTLDNS': "ftldns/index.md" +- 'FTLDNS': + - 'Overview': "ftldns/index.md" + - 'In-depth manual': "ftldns/in-depth.md" - 'Guides': - 'Pi-hole and OpenVPN Server': - 'Overview': 'guides/vpn/overview.md'