From 8d23e2919073895c28c4217fce0ff98ca4dbff03 Mon Sep 17 00:00:00 2001 From: Eugene Bujak Date: Thu, 20 Sep 2018 15:03:34 +0300 Subject: [PATCH 1/2] Update readme. * Link directly to binary downloads * Move "how to run" section right after binaries. * Add "How does AdGuard DNS work" and "How is this different from public AdGuard DNS servers" sections. * Update phrasing to emphasize that it's "your AdGuard DNS" server. * Remove yarn from `brew install` line. * Mention terminal for bash commands. * Add 32-bit ARM and 32-bit Intel binary links. --- README.md | 74 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index aff71ecf..9fb50864 100644 --- a/README.md +++ b/README.md @@ -4,49 +4,46 @@ AdGuard DNS is an ad-filtering DNS server with built-in phishing protection and optional family-friendly protection. +## How does AdGuard DNS work? + +If you configure your network to use this DNS server, every time a website sends an ad or phishing request, the server sends back a null response. AdGuard has a database of domain names that serve for ad, tracking or phishing purposes, and this database is regularly updated. + +## How is this different from public AdGuard DNS servers? + +Running your own AdGuard DNS offers you more options: + * Enable/disable blocking of ads on the fly. + * Enable/disable blocking of phishing and malware websites on the fly. + * Enable/disable blocking of adult websites on the fly. + * Enable/disable enforcing of family friendly search results in search engines like Google, Yandex and Bing. + * See which DNS requests are being made by which computer in your network by using query log. + * Add your own filtering rules on the fly. + This repository describes how to set up and run your self-hosted instance of AdGuard DNS -- it comes with a web dashboard that can be accessed from browser to control the DNS server and change its settings, it also allows you to add your filters in both AdGuard and hosts format. -If this seems too complicated, you can always use AdGuard DNS servers that provide same functionality — https://adguard.com/en/adguard-dns/overview.html +If this seems too complicated, you can always use our public AdGuard DNS servers -- they are running same code from this repository and provide same functionality — https://adguard.com/en/adguard-dns/overview.html ## Installation -Go to https://github.com/AdguardTeam/AdguardDNS/releases and download the binaries for your platform: - ### Mac -Download file `AdguardDNS_*_darwin_amd64.tar.gz`, then unpack it and follow [how to run](#How-to-run) instructions below. +Download file [AdguardDNS_0.1_MacOS.zip](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_MacOS.zip), then unpack it and follow [how to run](#how-to-run) instructions below. -### Linux -Download file `AdguardDNS_*_linux_amd64.tar.gz`, then unpack it and follow [how to run](#How-to-run) instructions below. +### Linux 64-bit Intel +Download file [AdguardDNS_0.1_linux_amd64.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_amd64.tar.gz), then unpack it and follow [how to run](#how-to-run) instructions below. -## How to build your own +### Linux 32-bit Intel +Download file [AdguardDNS_0.1_linux_386.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_386.tar.gz), then unpack it and follow [how to run](#how-to-run) instructions below. -### Prerequisites - -You will need: - * [go](https://golang.org/dl/) - * [node.js](https://nodejs.org/en/download/) - -You can either install it from these websites or use [brew.sh](https://brew.sh/) if you're on Mac: -```bash -brew install go node yarn -``` - -### Building -Open Terminal and execute these commands: -```bash -git clone https://github.com/AdguardTeam/AdguardDNS -cd AdguardDNS -make -``` +### Raspberry Pi (32-bit ARM) +Download file [AdguardDNS_0.1_linux_arm.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_arm.tar.gz), then unpack it and follow [how to run](#how-to-run) instructions below. ## How to run -DNS works on port 53, which requires superuser privileges. Therefore, you need to run it with sudo: +DNS works on port 53, which requires superuser privileges. Therefore, you need to run it with sudo in terminal: ```bash sudo ./AdguardDNS ``` -Now open the browser and point it to http://localhost:3000/ to control AdGuard DNS server. +Now open the browser and point it to http://localhost:3000/ to control your AdGuard DNS server. ### Running without superuser @@ -60,7 +57,7 @@ If the file does not exist, create it and put these two lines down. ### Additional configuration -Open first execution, a file `AdguardDNS.yaml` will be created, with default values written in it. You can modify the file while AdGuard DNS is not running, otherwise any changes to the file will be lost because they will be overwritten by the server. +Open first execution, a file `AdguardDNS.yaml` will be created, with default values written in it. You can modify the file while your AdGuard DNS is not running, otherwise any changes to the file will be lost because they will be overwritten by the program. Explanation of settings: @@ -84,6 +81,27 @@ Explanation of settings: Removing an entry from settings file will reset it to default value. Deleting the file will reset all settings to default values. +## How to build your own + +### Prerequisites + +You will need: + * [go](https://golang.org/dl/) + * [node.js](https://nodejs.org/en/download/) + +You can either install it from these websites or use [brew.sh](https://brew.sh/) if you're on Mac: +```bash +brew install go node +``` + +### Building +Open Terminal and execute these commands: +```bash +git clone https://github.com/AdguardTeam/AdguardDNS +cd AdguardDNS +make +``` + ## Contributing You are welcome to fork this repository, make your changes and submit a pull request — https://github.com/AdguardTeam/AdguardDNS/pulls From a76fd7618abce834aa4eced0200e3ecfe77298e0 Mon Sep 17 00:00:00 2001 From: Eugene Bujak Date: Thu, 20 Sep 2018 18:15:52 +0300 Subject: [PATCH 2/2] Proofreading by @vbagirov --- README.md | 96 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 9fb50864..ef48afbe 100644 --- a/README.md +++ b/README.md @@ -2,100 +2,112 @@ # Self-hosted AdGuard DNS -AdGuard DNS is an ad-filtering DNS server with built-in phishing protection and optional family-friendly protection. +AdGuard DNS is an alternative way to block ads, trackers and phishing websites, and also a parental control instrument. ## How does AdGuard DNS work? -If you configure your network to use this DNS server, every time a website sends an ad or phishing request, the server sends back a null response. AdGuard has a database of domain names that serve for ad, tracking or phishing purposes, and this database is regularly updated. +If you configure your network to use this DNS server, every time a website sends an ad or phishing request, our server sends back a null ("empty") response. AdGuard has a database of domain names that serve for an ad, tracking or phishing purposes (and adult content, in case of parental control mode), and this database is regularly updated. ## How is this different from public AdGuard DNS servers? Running your own AdGuard DNS offers you more options: - * Enable/disable blocking of ads on the fly. - * Enable/disable blocking of phishing and malware websites on the fly. - * Enable/disable blocking of adult websites on the fly. - * Enable/disable enforcing of family friendly search results in search engines like Google, Yandex and Bing. - * See which DNS requests are being made by which computer in your network by using query log. - * Add your own filtering rules on the fly. + * Enable/disable ad blocking on the fly. + * Enable/disable blocking of phishing and malware websites. + * Enable/disable blocking of websites with adult content. + * Optional ability to enforce "Safe search" option in Google, Yandex and Bing. + * See DNS query log — it shows what requests were sent by which clients and why a request was blocked. + * Add your own custom filtering rules. -This repository describes how to set up and run your self-hosted instance of AdGuard DNS -- it comes with a web dashboard that can be accessed from browser to control the DNS server and change its settings, it also allows you to add your filters in both AdGuard and hosts format. +This repository describes how to set up and run your self-hosted instance of AdGuard DNS — it comes with a web dashboard that can be accessed via browser to control the DNS server and change its settings, it also allows to add your own filters written in both "hosts" and AdGuard syntaxes. -If this seems too complicated, you can always use our public AdGuard DNS servers -- they are running same code from this repository and provide same functionality — https://adguard.com/en/adguard-dns/overview.html +If this seems too complicated, you can always use our public AdGuard DNS servers — they are running the same code as in this repository and provide the same ad blocking/phishing protection/parental control functionality — https://adguard.com/en/adguard-dns/overview.html ## Installation ### Mac -Download file [AdguardDNS_0.1_MacOS.zip](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_MacOS.zip), then unpack it and follow [how to run](#how-to-run) instructions below. + +Download this file: [AdguardDNS_0.1_MacOS.zip](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_MacOS.zip), then unpack it and follow ["How to run"](#how-to-run) instructions below. ### Linux 64-bit Intel -Download file [AdguardDNS_0.1_linux_amd64.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_amd64.tar.gz), then unpack it and follow [how to run](#how-to-run) instructions below. + +Download this file: [AdguardDNS_0.1_linux_amd64.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_amd64.tar.gz), then unpack it and follow ["How to run"](#how-to-run) instructions below. ### Linux 32-bit Intel -Download file [AdguardDNS_0.1_linux_386.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_386.tar.gz), then unpack it and follow [how to run](#how-to-run) instructions below. + +Download this file: [AdguardDNS_0.1_linux_386.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_386.tar.gz), then unpack it and follow ["How to run"](#how-to-run) instructions below. ### Raspberry Pi (32-bit ARM) -Download file [AdguardDNS_0.1_linux_arm.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_arm.tar.gz), then unpack it and follow [how to run](#how-to-run) instructions below. + +Download this file: [AdguardDNS_0.1_linux_arm.tar.gz](https://github.com/AdguardTeam/AdguardDNS/releases/download/v0.1/AdguardDNS_0.1_linux_arm.tar.gz), then unpack it and follow ["How to run"](#how-to-run) instructions below. ## How to run -DNS works on port 53, which requires superuser privileges. Therefore, you need to run it with sudo in terminal: +DNS works on port 53, which requires superuser privileges. Therefore, you need to run it with `sudo` in terminal: + ```bash sudo ./AdguardDNS ``` -Now open the browser and point it to http://localhost:3000/ to control your AdGuard DNS server. +Now open the browser and navigate to http://localhost:3000/ to control your AdGuard DNS server. ### Running without superuser -You can run it without superuser privileges, but you need to instruct it to use other port rather than 53. You can do that by opening `AdguardDNS.yaml` and adding this line: +You can run AdGuard DNS without superuser privileges, but you need to instruct it to use a different port rather than 53. You can do that by editing `AdguardDNS.yaml` and finding these two lines: + ```yaml coredns: - port: 53535 + port: 53 ``` -If the file does not exist, create it and put these two lines down. +You can change port 53 to anything above 1024 to avoid requiring superuser privileges. + +If the file does not exist, create it in the same folder, type these two lines down and save. ### Additional configuration -Open first execution, a file `AdguardDNS.yaml` will be created, with default values written in it. You can modify the file while your AdGuard DNS is not running, otherwise any changes to the file will be lost because they will be overwritten by the program. +Upon the first execution, a file named `AdguardDNS.yaml` will be created, with default values written in it. You can modify the file while your AdGuard DNS is not running. Otherwise, any changes to the file will be lost because the running program will overwrite them. -Explanation of settings: +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 - * `coredns` -- CoreDNS 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 when accessing search engines - * `parental_enabled` -- Filtering of DNS requests based on parental safety - * `parental_sensitivity` -- Age group for filtering based on parental safety - * `querylog_enabled` -- Query logging, also used to calculate top 50 clients, blocked domains and requested domains for stats - * `upstream_dns` -- List of upstream DNS servers - * `filters` -- List of filters, each filter has these values: - * `url` -- URL pointing to the filter contents - * `enabled` -- Enable/disable current filter - * `user_rules` -- User-defined filtering rules + * `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 + * `coredns` — CoreDNS 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) + * `upstream_dns` — List of upstream DNS servers + * `filters` — List of filters, each filter has the following values: + * `url` — URL pointing to the filter contents (filtering rules) + * `enabled` — Current filter's status (enabled/disabled) + * `user_rules` — User-specified filtering rules -Removing an entry from settings file will reset it to default value. Deleting the file will reset all settings to default values. +Removing an entry from settings file will reset it to the default value. Deleting the file will reset all settings to the default values. -## How to build your own +## How to build from source ### Prerequisites You will need: + * [go](https://golang.org/dl/) * [node.js](https://nodejs.org/en/download/) -You can either install it from these websites or use [brew.sh](https://brew.sh/) if you're on Mac: +You can either install it via the provided links or use [brew.sh](https://brew.sh/) if you're on Mac: + ```bash brew install go node ``` ### Building + Open Terminal and execute these commands: + ```bash git clone https://github.com/AdguardTeam/AdguardDNS cd AdguardDNS @@ -108,4 +120,4 @@ You are welcome to fork this repository, make your changes and submit a pull req ## Reporting issues -If you come across any problem, or have a suggestion, head to [this page](https://github.com/AdguardTeam/AdguardDNS/issues) and click on the `New issue` button. +If you run into any problem or have a suggestion, head to [this page](https://github.com/AdguardTeam/AdguardDNS/issues) and click on the `New issue` button.