From 217124cb3b634787ee933abd7af98833478e5bec Mon Sep 17 00:00:00 2001 From: Eugene Bujak Date: Thu, 6 Dec 2018 17:17:42 +0300 Subject: [PATCH] readme -- Update config field descriptions and clarify about coredns. --- README.md | 45 ++++++++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index b9916574..438c3eb1 100644 --- a/README.md +++ b/README.md @@ -104,25 +104,32 @@ Upon the first execution, a file named `AdGuardHome.yaml` will be created, with Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possible parameters that you can configure are listed below: - * `bind_host` — Web interface IP address to listen on - * `bind_port` — Web interface IP port to listen on - * `auth_name` — Web interface optional authorization username - * `auth_pass` — Web interface optional authorization password - * `dns` — DNS configuration section - * `port` — DNS server port to listen on - * `filtering_enabled` — Filtering of DNS requests based on filter lists - * `safebrowsing_enabled` — Filtering of DNS requests based on safebrowsing - * `safesearch_enabled` — Enforcing "Safe search" option for search engines, when possible - * `parental_enabled` — Parental control-based DNS requests filtering - * `parental_sensitivity` — Age group for parental control-based filtering, must be either 3, 10, 13 or 17 - * `querylog_enabled` — Query logging (also used to calculate top 50 clients, blocked domains and requested domains for statistic purposes) - * `bootstrap_dns` — DNS server used for initial hostname resolution in case if upstream server name is a hostname - * `upstream_dns` — List of upstream DNS servers + * `bind_host` — Web interface IP address to listen on. + * `bind_port` — Web interface IP port to listen on. + * `auth_name` — Web interface optional authorization username. + * `auth_pass` — Web interface optional authorization password. + * `dns` — DNS configuration section. + * `port` — DNS server port to listen on. + * `protection_enabled` — Whether any kind of filtering and protection should be done, when off it works as a plain dns forwarder. + * `filtering_enabled` — Filtering of DNS requests based on filter lists. + * `blocked_response_ttl` — For how many seconds the clients should cache a filtered response. Low values are useful on LAN if you change filters very often, high values are useful to increase performance and save traffic. + * `querylog_enabled` — Query logging (also used to calculate top 50 clients, blocked domains and requested domains for statistical purposes). + * `ratelimit` — DDoS protection, specifies in how many packets per second a client should receive. Anything above that is silently dropped. To disable set 0, default is 20. Safe to disable if DNS server is not available from internet. + * `ratelimit_whitelist` — If you want exclude some IP addresses from ratelimiting but keep ratelimiting on for others, put them here. + * `refuse_any` — Another DDoS protection mechanism. Requests of type ANY are rarely needed, so refusing to serve them mitigates against attackers trying to use your DNS as a reflection. Safe to disable if DNS server is not available from internet. + * `bootstrap_dns` — DNS server used for initial hostname resolution in case if upstream server name is a hostname. + * `parental_sensitivity` — Age group for parental control-based filtering, must be either 3, 10, 13 or 17 if enabled. + * `parental_enabled` — Parental control-based DNS requests filtering. + * `safesearch_enabled` — Enforcing "Safe search" option for search engines, when possible. + * `safebrowsing_enabled` — Filtering of DNS requests based on safebrowsing. + * `upstream_dns` — List of upstream DNS servers. * `filters` — List of filters, each filter has the following values: - * `ID` - filter ID (must be unique) - * `url` — URL pointing to the filter contents (filtering rules) - * `enabled` — Current filter's status (enabled/disabled) - * `user_rules` — User-specified filtering rules + * `enabled` — Current filter's status (enabled/disabled). + * `url` — URL pointing to the filter contents (filtering rules). + * `name` — Name of the filter. If it's an adguard syntax filter it will get updated automatically, otherwise it stays unchanged. + * `last_updated` — Time when the filter was last updated from server. + * `ID` - filter ID (must be unique). + * `user_rules` — User-specified filtering rules. Removing an entry from settings file will reset it to the default value. Deleting the file will reset all settings to the default values. @@ -208,6 +215,6 @@ This software wouldn't have been possible without: * And many more node.js packages. * [whotracks.me data](https://github.com/cliqz-oss/whotracks.me) -You might have seen that coredns was mentioned here before — we've stopped using it in AdGuardHome. While we still use it on our servers, it seemed like an overkill and it impeded with Home features that we wanted to implement. +You might have seen that [CoreDNS](https://coredns.io) was mentioned here before — we've stopped using it in AdGuardHome. While we still use it on our servers for [AdGuard DNS](https://adguard.com/adguard-dns/overview.html) service, it seemed like an overkill for Home as it impeded with Home features that we plan to implement. For a full list of all node.js packages in use, please take a look at [client/package.json](https://github.com/AdguardTeam/AdGuardHome/blob/master/client/package.json) file.