From 6fcb2dda77f54af3c38ef95d4a85e3abf6e75ccc Mon Sep 17 00:00:00 2001 From: Mario Kleinsasser Date: Sun, 27 May 2018 21:31:29 +0200 Subject: [PATCH] Add addition documentation for hosts plugin, fix #1825 (#1836) Signed-off-by: Mario Kleinsasser Rework the documentation Signed-off-by: Mario Kleinsasser --- plugin/hosts/README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/plugin/hosts/README.md b/plugin/hosts/README.md index f213f5b1d..b2a041548 100644 --- a/plugin/hosts/README.md +++ b/plugin/hosts/README.md @@ -6,13 +6,33 @@ ## Description -The hosts plugin is useful for serving zones from a /etc/hosts file. It serves from a preloaded +The hosts plugin is useful for serving zones from a `/etc/hosts` file. It serves from a preloaded file that exists on disk. It checks the file for changes and updates the zones accordingly. This plugin only supports A, AAAA, and PTR records. The hosts plugin can be used with readily available hosts files that block access to advertising servers. This plugin can only be used once per Server Block. +## The hosts file + +Commonly the entries are of the from `IP_address canonical_hostname [aliases...]` as explained by the hosts(5) man page. + +Examples: + +~~~ +# The following lines are desirable for IPv4 capable hosts +127.0.0.1 localhost +192.168.1.10 example.com example + +# The following lines are desirable for IPv6 capable hosts +::1 localhost ip6-localhost ip6-loopback +fdfc:a744:27b5:3b0e::1 example.com example +~~~ + +### PTR records + +PTR records for reverse lookups are generated automatically by CoreDNS (based on the hosts file entries) and cannot be created manually. + ## Syntax ~~~ @@ -74,3 +94,7 @@ Load hosts file inlined in Corefile. } } ~~~ + +## See also + +The form of the entries in the `/etc/hosts` file are based on IETF [RFC 952](https://tools.ietf.org/html/rfc952) which was updated by IETF [RFC 1123](https://tools.ietf.org/html/rfc1123).