From 84693121098a4b497a9f9b36098e6ad3e6157c7c Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Fri, 15 Dec 2023 20:24:48 +0300 Subject: [PATCH 1/5] Add the AdGuard Home secion, move a few articles This change is the first in the series that migrates the current AdGuard Home Wiki () to the DNS Knowledge Base. More articles and edits are coming soon. Updates AdguardTeam/AdGuardHome#5013. --- docs/adguard-home/_category_.json | 6 + docs/adguard-home/faq.md | 475 ++++++++++++++++++++++++++ docs/adguard-home/getting-started.md | 256 ++++++++++++++ docs/adguard-home/overview.md | 10 + docs/adguard-home/running-securely.md | 79 +++++ docs/miscellaneous/_category_.json | 4 +- 6 files changed, 828 insertions(+), 2 deletions(-) create mode 100644 docs/adguard-home/_category_.json create mode 100644 docs/adguard-home/faq.md create mode 100644 docs/adguard-home/getting-started.md create mode 100644 docs/adguard-home/overview.md create mode 100644 docs/adguard-home/running-securely.md diff --git a/docs/adguard-home/_category_.json b/docs/adguard-home/_category_.json new file mode 100644 index 000000000..f4bdf2f1b --- /dev/null +++ b/docs/adguard-home/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 6, + "label": "AdGuard Home", + "collapsible": true, + "collapsed": true +} diff --git a/docs/adguard-home/faq.md b/docs/adguard-home/faq.md new file mode 100644 index 000000000..18d881aa8 --- /dev/null +++ b/docs/adguard-home/faq.md @@ -0,0 +1,475 @@ +--- +title: FAQ +sidebar_position: 3 +--- + +## Why AdGuard Home doesn't block ads? {#doesntblock} + +Suppose that AdGuard Home must block `somebadsite.com` but for some reason it doesn't. Let's try to resolve this issue. + +Most likely you didn't configure your device to use AdGuard Home as its default DNS server. To check if you're using AdGuard Home as the default DNS server: + +1. On Windows, open a Terminal window (Start → Run → `cmd.exe`). On other systems, open your Terminal application. + +1. Execute `nslookup example.org`. It will print something like this: + + ```none + Server: 192.168.0.1 + Address: 192.168.0.1#53 + + Non-authoritative answer: + Name: example.org + Address: + Name: example.org + Address: + ``` + +1. Check if the `Server` IP address is the one on which AdGuard Home is running. If not, you need to configure your device, see [below](#defaultdns). + +1. Ensure that your request to `example.org` appears in the AdGuard Home UI on the *Query Log* page. If not, you need to configure AdGuard Home to listen on the specified network interface. The most straightforward way to do so is to reinstall AdGuard Home with default settings. + +If you are sure that your device uses AdGuard Home as its default DNS server, but the problem persists, it might have something to do with an AdGuard Home misconfiguration. Please check and ensure that: + +1. You have the “Block domains using filters and hosts files” setting enabled on the *Settings → General settings* page. + +1. You have the appropriate safety mechanisms, such as Parental Control, enabled on the *Settings → General settings* page. + +1. You have the appropriate filters enabled on the *Filters → DNS blocklists* page. + +1. You don't have any exception rule lists that may allow the requests enabled on the *Filters → DNS allowlists* page. + +1. You don't have any DNS rewrites that may interfere with the *Filters → DNS rewrites* page. + +1. You don't have any custom filtering rules that may interfere with the *Filters → Custom filtering rules* page. + +## Where can I inspect the logs? {#logs} + +The default location of the plain-text logs (not to be confused with the query logs) depends on the operating system and installation mode: + + + +- **OpenWrt Linux:** use the `logread -e AdGuardHome` command. + +- **Linux** systems with **systemd** and other **Unix** systems with **SysV-style init:** `/var/log/AdGuardHome.err`. + +- **macOS:** `/var/log/AdGuardHome.stderr.log`. + +- **Linux** systems with **Snapcraft** use the `snap logs adguard-home` command. + +- **FreeBSD:** `/var/log/daemon.log` (**since v0.108.0-b.4**). Before **v0.108.0-b.4** no logs are written by default. + +- **OpenBSD:** `/var/log/daemon` (**since v0.108.0-b.4**). Before **v0.108.0-b.4** no logs are written by default. + +- On **Windows:** the [Windows Event Log][wlog] is used. + +[wlog]: https://docs.microsoft.com/en-us/windows/win32/wes/windows-event-log + +## How to configure AdGuard Home to write verbose-level logs? {#verboselog} + +To troubleshoot a complicated issue, the verbose-level logging is sometimes required. Here's how to enable it: + +1. Stop AdGuard Home: + + ```sh + ./AdGuardHome -s stop + ``` + +1. Configure AdGuard Home to write verbose-level logs: + + 1. Open `AdGuardHome.yaml` in your editor. + + 1. Set `log.file` to the desired path of the log file, for example `/tmp/aghlog.txt`. Note that the directory must exist. + + 1. Set `log.verbose` to `true`. + + **NOTE:** Before v0.107.34 use `verbose` and `log_file` properties. + +1. Restart AdGuard Home and reproduce the issue: + + ```sh + ./AdGuardHome -s start + ``` + +## How to show a custom block page? {#customblock} + +### A note about HTTPS + +Before doing any of this, please note that modern browsers are set up to use HTTPS, so they validate the authenticity of the web server certificate. That means that using any of these will result in warning screens. + +There are a couple of proposed extensions that, when they become reasonably well supported by clients, would allow for a better user experience, including the [RFC 8914 Extended DNS Error codes][rfc8914] and the [DNS Access Denied Error Page RFC draft][rfcaccess]. We'll implement them when browsers actually start to support them. + +[rfc8914]: https://datatracker.ietf.org/doc/html/rfc8914 +[rfcaccess]: https://datatracker.ietf.org/doc/html/draft-reddy-dnsop-error-page-08 + +### Prerequisites + +To use any of these ways to show a custom block page, you'll need an HTTP server running on some IP address and serving the page in question on all routes. Something like [`pixelserv-tls`][pxsrv]. + +[pxsrv]: https://github.com/kvic-z/pixelserv-tls + +### Custom block page for Parental Control and Safe Browsing filters + +There is currently no way to set these parameters from the UI, so you'll need to edit the configuration file manually: + +1. Stop AdGuard Home: + + ```sh + ./AdGuardHome -s stop + ``` + +1. Open `AdGuardHome.yaml` in your editor. + +1. Set the `dns.parental_block_host` or `dns.safebrowsing_block_host` settings to the IP address of the server (in this example, `192.168.123.45`): + + ```yaml + # … + dns: + # … + + # NOTE: Change to the actual IP address of your server. + parental_block_host: 192.168.123.45 + safebrowsing_block_host: 192.168.123.45 + ``` + +1. Restart AdGuard Home: + + ```sh + ./AdGuardHome -s start + ``` + +### Custom block page for other filters + +1. Open the web UI. + +1. Open the *Settings → DNS settings* page. + +1. In the “DNS server configuration” section, select the “Custom IP” radio button in the “Blocking mode” selector and enter the IPv4 and IPv6 addresses of the server. + +1. Click “Save”. + +## How to change dashboard interface's address? {#webaddr} + +1. Stop AdGuard Home: + + ```sh + ./AdGuardHome -s stop + ``` + +1. Open `AdGuardHome.yaml` in your editor. + +1. Set the `http.address` setting to a new network interface. For example: + + - `0.0.0.0:0` to listen on all network interfaces; + - `0.0.0.0:8080` to listen on all network interfaces with port `8080`; + - `127.0.0.1:0` to listen on the local loopback interface only. + +1. Restart AdGuard Home: + + ```sh + ./AdGuardHome -s start + ``` + +## How to set up AdGuard Home as default DNS server? {#defaultdns} + +See the [“Configuring Devices” section](getting-started.md#configure-devices) on the *Getting Started* page. + +## Are there any known limitations? {#limitations} + +Here are some examples of what cannot be blocked by a DNS-level blocker: + +- YouTube, Twitch ads. + +- Facebook, Twitter, Instagram sponsored posts. + +Essentially, any advertising that shares a domain with content cannot be blocked by a DNS-level blocker. + +### Is there a chance to handle this in the future? + +DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the standalone AdGuard applications. We're going to bring this feature support to AdGuard Home in the future. Unfortunately, even in this case, there still will be cases when this won't be enough or would require quite complicated configuration. + +## Why am I getting `bind: address already in use` error when trying to install on Ubuntu? {#bindinuse} + +This happens because the port 53 on `localhost`, which is used for DNS, is already taken by another program. Ubuntu comes with a local DNS called `systemd-resolved`, which uses the address `127.0.0.53:53` and thus prevents AdGuard Home from binding to `127.0.0.1:53`. You can see that by running: + +```sh +sudo lsof -i :53 +``` + +The output should be similar to: + +```none +COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME +systemd-r 14542 systemd-resolve 13u IPv4 86178 0t0 UDP 127.0.0.53:domain +systemd-r 14542 systemd-resolve 14u IPv4 86179 0t0 TCP 127.0.0.53:domain +``` + +To fix this, you need to either disable the `systemd-resolved` daemon or choose a different network interface and bind to an accessible IP address on it, for instance, the IP address of your router inside your network. But if you do need to listen on `localhost`, there are several solutions. + +Firstly, AdGuard Home can detect such configurations and disable `systemd-resolved` for you if you press the “Fix” button, which is shown near the `address already in use` message on the installation screen. + +Secondly, if that doesn't work, follow the guide below. Note that if you're using AdGuard Home with docker or snap, you'll have to do it yourself. + +1. Create the `/etc/systemd/resolved.conf.d` directory, if necessary: + + ```sh + sudo mkdir -p /etc/systemd/resolved.conf.d + ``` + +1. Deactivate `DNSStubListener` and update DNS server address. To do that, create a new file, `/etc/systemd/resolved.conf.d/adguardhome.conf`, with the following content: + + ```service + [Resolve] + DNS=127.0.0.1 + DNSStubListener=no + ``` + + Specifying `127.0.0.1` as DNS server address **is necessary** because otherwise the nameserver will be `127.0.0.53` which doesn't work without `DNSStubListener`. + +1. Activate another `resolv.conf` file: + + ```sh + sudo mv /etc/resolv.conf /etc/resolv.conf.backup + sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf + ``` + +1. Restart `DNSStubListener`: + + ```sh + sudo systemctl reload-or-restart systemd-resolved + ``` + +After that, `systemd-resolved` shouldn't be shown in the output of `lsof`, and AdGuard Home should be able to bind to `127.0.0.1:53`. + +## How to configure a reverse proxy server for AdGuard Home? {#reverseproxy} + +If you're already running a web server and want to access the AdGuard Home dashboard UI from a URL like `http://YOUR_SERVER/aghome/`, you can use this configuration for your web server: + +### nginx + +```nginx +location /aghome/ { + proxy_cookie_path / /aghome/; + proxy_pass http://AGH_IP:AGH_PORT/; + proxy_redirect / /aghome/; + proxy_set_header Host $host; +} +``` + +### caddy + +```none +:80/aghome/* { + route { + uri strip_prefix /aghome + reverse_proxy AGH_IP:AGH_PORT + } +} +``` + +Or, if you just want to serve AdGuard Home with automatic TLS, use a configuration similar to the example shown below: + +```none +DOMAIN { + encode gzip zstd + tls YOUR_EMAIL@DOMAIN + reverse_proxy AGH_IP:AGH_PORT +} +``` + +### Disable DoH encryption on AdGuard Home + +When you use TLS on your reverse proxy server, there's no need to use TLS on AdGuard Home. Set `allow_unencrypted_doh: true` in `AdGuardHome.yaml` to allow AdGuard Home respond to DoH requests without TLS encryption. + +### Real IP addresses of clients + +**Since v0.107.0,** you can set the parameter `trusted_proxies` to the IP address(es) of your HTTP proxy to make AdGuard Home take the headers containing the real client IP address into account. See the [configuration][conf] and [encryption][encr] pages for more information. + +[encr]: https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption#reverse-proxy +[conf]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration + +## How to fix `permission denied` errors on Fedora? {#fedora} + +1. Move the `AdGuardHome` binary to `/usr/local/bin`. + +1. As `root`, execute the following command to change the security context of the file: + + ```sh + chcon -t bin_t /usr/local/bin/AdGuardHome + ``` + +1. Add the required firewall rules in order to make it reachable through the network. For example: + + ```sh + firewall-cmd --new-zone=adguard --permanent + firewall-cmd --zone=adguard --add-source=192.168.0.14/24 --permanent + firewall-cmd --zone=adguard --add-port=3000/tcp --permanent + firewall-cmd --zone=adguard --add-port=53/udp --permanent + firewall-cmd --zone=adguard --add-port=80/tcp --permanent + firewall-cmd --reload + ``` + +If you are still getting `code=exited status=203/EXEC` or similar errors from `systemctl`, try uninstalling AdGuard Home and installing *directly* into `/usr/local/bin` by using the `-o` option of the install script: + +```sh +curl -s -S -L 'https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh' | sh -s -- -o '/usr/local/bin' -v +``` + +See [issue 765] and [issue 3281]. + +[issue 3281]: https://github.com/AdguardTeam/AdGuardHome/issues/3281 +[issue 765]: https://github.com/AdguardTeam/AdGuardHome/issues/765#issuecomment-752262353 + +## How to fix `incompatible file system` errors? {#incompatfs} + +You should move your AdGuard Home installation or working directory to another location. See the [limitations section](getting-started.md#limitations) on the *Getting Started* page. + +## How to update AdGuard Home manually? {#manual-update} + +In case the button isn't shown or an automatic update has failed, you can update manually. In the examples below, we'll use AdGuard Home releases for Linux and Windows for AMD64 CPUs. + +### Unix (Linux, macOS, BSD) {#manual-update-unix} + +1. Download the new AdGuard Home package from the [releases page][releases]. If you want to perform this step from the command line: + + ```sh + curl -L -S -o '/tmp/AdGuardHome_linux_amd64.tar.gz' -s\ + 'https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz' + ``` + + Or, with `wget`: + + ```sh + wget -O '/tmp/AdGuardHome_linux_amd64.tar.gz'\ + 'https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz' + ``` + +1. Navigate to the directory where AdGuard Home was installed. On most Unix systems the default directory is `/opt/AdGuardHome`, but on macOS it's `/Applications/AdGuardHome`. + +1. Stop AdGuard Home: + + ```sh + sudo ./AdGuardHome -s stop + ``` + + (On OpenBSD you probably want to use `doas` instead of `sudo`.) + +1. Backup your data. That is, your configuration file and the data directory (`AdGuardHome.yaml` and `data/` by default). For example, to backup your data to a new directory called `~/my-agh-backup`: + + ```sh + mkdir -p ~/my-agh-backup + cp -r ./AdGuardHome.yaml ./data ~/my-agh-backup/ + ``` + +1. Unpack the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your `~/Downloads` directory and want to unpack it to `/tmp/`: + + ```sh + tar -C /tmp/ -f ~/Downloads/AdGuardHome_linux_amd64.tar.gz -x -v -z + ``` + + On macOS, something like: + + ```sh + unzip -d /tmp/ ~/Downloads/AdGuardHome_darwin_amd64.zip + ``` + +1. Replace the old AdGuard Home executable file with the new one. On most Unix systems the command would look something like: + + ```sh + sudo cp /tmp/AdGuardHome/AdGuardHome /opt/AdGuardHome/AdGuardHome + ``` + + On macOS, something like: + + ```sh + sudo cp /tmp/AdGuardHome/AdGuardHome /Applications/AdGuardHome/AdGuardHome + ``` + + You may also want to copy the documentation parts of the package, such as the change log (`CHANGELOG.md`), the README file (`README.md`), and the license (`LICENSE.txt`). + + You can now remove the temporary directory. + +1. Restart AdGuard Home: + + ```sh + sudo ./AdGuardHome -s start + ``` + +(On OpenBSD you probably want to use `doas` instead of `sudo`.) + +[releases]: https://github.com/AdguardTeam/AdGuardHome/releases/latest + +### Windows (Using PowerShell) {#manual-update-win} + +In all examples below, the PowerShell must be run as Administrator. + +1. Download the new AdGuard Home package from the [releases page][releases]. If you want to perform this step from the command line: + + ```ps1 + $outFile = Join-Path -Path $Env:USERPROFILE -ChildPath 'Downloads\AdGuardHome_windows_amd64.zip' + $aghUri = 'https://static.adguard.com/adguardhome/release/AdGuardHome_windows_amd64.zip' + Invoke-WebRequest -OutFile "$outFile" -Uri "$aghUri" + ``` + +1. Navigate to the directory where AdGuard Home was installed. In the examples below, we'll use `C:\Program Files\AdGuardHome`. + +1. Stop AdGuard Home: + + ```ps1 + .\AdGuardHome.exe -s stop + ``` + +1. Backup your data. That is, your configuration file and the data directory (`AdGuardHome.yaml` and `data/` by default). For example, to backup your data to a new directory called `my-agh-backup`: + + ```ps1 + $newDir = Join-Path -Path $Env:USERPROFILE -ChildPath 'my-agh-backup' + New-Item -Path $newDir -ItemType Directory + Copy-Item -Path .\AdGuardHome.yaml, .\data -Destination $newDir -Recurse + ``` + +1. Unpack the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your `Downloads` directory and want to unpack it to a temporary directory: + + ```ps1 + $outFile = Join-Path -Path $Env:USERPROFILE -ChildPath 'Downloads\AdGuardHome_windows_amd64.zip' + Expand-Archive -Path "$outFile" -DestinationPath $Env:TEMP + ``` + +1. Replace the old AdGuard Home executable file with the new one. For example: + + ```ps1 + $aghExe = Join-Path -Path $Env:TEMP -ChildPath 'AdGuardHome\AdGuardHome.exe' + Copy-Item -Path "$aghExe" -Destination .\AdGuardHome.exe + ``` + + You may also want to copy the documentation parts of the package, such as the change log (`CHANGELOG.md`), the README file (`README.md`), and the license (`LICENSE.txt`). + + You can now remove the temporary directory. + +1. Restart AdGuard Home: + + ```ps1 + .\AdGuardHome.exe -s start + ``` + +## How to uninstall AdGuard Home? {#uninstall} + +The way to uninstall AdGuard Home depends on how you installed it. + +**IMPORTANT:** After uninstalling AdGuard Home, don't forget to change your devices configuration and point them to a different DNS server. + +### Regular installation + +In this case you need to do the following: + +- Unregister AdGuard Home service: `./AdGuardHome -s uninstall`. + +- Remove the AdGuard Home directory. + +### Docker + +Simply stop and remove the image. + +### Snap Store + +```sh +snap remove adguard-home +``` diff --git a/docs/adguard-home/getting-started.md b/docs/adguard-home/getting-started.md new file mode 100644 index 000000000..c2f95b61c --- /dev/null +++ b/docs/adguard-home/getting-started.md @@ -0,0 +1,256 @@ +--- +title: Getting started +sidebar_position: 2 +--- + +## Installation {#installation} + +### Official releases + +Download the archive with the binary file for your operating system from the [latest stable release page][releases]. The full list of supported platforms as well as links to beta and edge (unstable) releases can be found on [our platforms page][platforms]. + +To install AdGuard Home as a service, unpack the archive, enter the `AdGuardHome` directory, and run: + +```sh +./AdGuardHome -s install +``` + +#### Notes + +- Users of **Fedora Linux** and its derivatives: install AdGuard Home into the `/usr/local/bin` directory. Otherwise, it may cause issues with SELinux and permissions. See [issue 765] and [issue 3281]. + +- Users of **macOS 10.15 Catalina** and newer should place the AdGuard Home working directory inside the `/Applications` directory. + +### Docker and Snap + +We also provide an [official AdGuard Home docker image][docker] and an [official Snap Store package][snap] for experienced users. + +### Other + +Some other unofficial options include: + +- (Maintained by @frenck) [Home Assistant add-on][has]. + +- (Maintained by @kongfl888) [OpenWrt LUCI app][luci]. + +- (Maintained by @graysky2) [Arch Linux][arch], [Arch Linux ARM][archarm], and other Arch-based OSs, may build via the [`adguardhome` package][aghaur] in the [AUR][aur]. + +- (Maintained by @gramakri) [Cloudron app][cloudron]. + +[aghaur]: https://aur.archlinux.org/packages/adguardhome/ +[arch]: https://www.archlinux.org/ +[archarm]: https://archlinuxarm.org/ +[aur]: https://wiki.archlinux.org/index.php/Arch_User_Repository +[cloudron]: https://git.cloudron.io/cloudron/adguard-home-app +[docker]: https://hub.docker.com/r/adguard/adguardhome +[has]: https://github.com/hassio-addons/addon-adguard-home +[issue 3281]: https://github.com/AdguardTeam/AdGuardHome/issues/3281 +[issue 765]: https://github.com/AdguardTeam/AdGuardHome/issues/765#issuecomment-752262353 +[luci]: https://github.com/kongfl888/luci-app-adguardhome +[platforms]: https://github.com/AdguardTeam/AdGuardHome/wiki/Platforms +[releases]: https://github.com/AdguardTeam/AdGuardHome/releases/latest +[snap]: https://snapcraft.io/adguard-home + +## First start {#first-time} + +First of all, check your firewall settings. To install and use AdGuard Home, the following ports and protocols must be available: + +- 3000/TCP for the initial installation; +- 80/TCP for the web interface; +- 53/UDP for the DNS server. + +You may need to open additional ports for protocols other than plain DNS, for example DNS-over-HTTPS. + +DNS servers bind to port 53, which requires superuser privileges most of the time, [see below](#running-without-superuser). Therefore, on unix systems you need to run it with `sudo` or `doas` in terminal: + +```sh +sudo ./AdGuardHome +``` + +On Windows, run `cmd.exe` or PowerShell with admin privileges and run `AdGuardHome.exe` from there. + +When you run AdGuard Home for the first time, it starts listening to `0.0.0.0:3000` and prompts you to open it in your browser: + +```none +AdGuard Home is available at the following addresses: +go to http://127.0.0.1:3000 +go to http://[::1]:3000 +[…] +``` + +There you will go through the initial configuration wizard. + +![AdGuard Home network interface selection screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install2.png) + +![AdGuard Home user creation screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install3.png) + +See [our article on running AdGuard Home securely](running-securely.md) for guidance on how to select the initial configuration that fits you best. + +## Running as a service {#service} + +The next step would be to register AdGuard Home as a system service (aka daemon). To install AdGuard Home as a service, run: + +```sh +sudo ./AdGuardHome -s install +``` + +On Windows, run `cmd.exe` with admin privileges and run `AdGuardHome.exe -s install` to register a windows service. + +Here are the other commands you might need to control the service: + +- `AdGuardHome -s uninstall`: Uninstall the AdGuard Home service. +- `AdGuardHome -s start`: Start the service. +- `AdGuardHome -s stop`: Stop the service. +- `AdGuardHome -s restart`: Restart the service. +- `AdGuardHome -s status`: Show the current service status. + +### Logs + +By default, the logs are written to stderr when you run AdGuard Home in a terminal. If you run it as a service, the log output depends on the platform: + +- On macOS, the log is written to `/var/log/AdGuardHome.*.log` files. + +- On other unixes, the log is written to `syslog` or `journald`. + +- On Windows, the log is written to the Windows event log. + +You can change this behavior in the AdGuard Home [configuration file][conf]. + +[conf]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration + +## Updating {#update} + +![An example of an update notification](https://cdn.adtidy.org/content/kb/dns/adguard-home/updatenotification.png) + +When a new version is released, AdGuard Home's UI shows a notification message and the “Update now” button. Click this button, and AdGuard Home will be automatically updated to the latest version. Your current AdGuard Home executable file is saved inside the `backup` directory along with the current configuration file, so you can revert the changes, if necessary. + +### Manual update {#manual-update} + +In case the button isn't shown or an automatic update has failed, you can update manually. We have a [detailed guide on manual updates][mupd], but in short: + +1. Download the new AdGuard Home package. + +1. Unpack it to a temporary directory. + +1. Replace the old AdGuard Home executable file with the new one. + +1. Restart AdGuard Home. + +[mupd]: https://github.com/AdguardTeam/AdGuardHome/wiki/FAQ#manual-update + +### Docker, Home Assistant, and Snapcraft updates + +Auto-updates for Docker, Hass.io/Home Assistant, and Snapcraft installations are disabled. Update the image instead. + +### Command-line update + +To update AdGuard Home package without the need to use Web API run: + +```sh +./AdGuardHome --update +``` + +## Configuring devices {#configure-devices} + +### Router + +This setup will automatically cover all devices connected to your home router, and you won't need to configure each of them manually. + +1. Open the preferences for your router. Usually, you can access it from your browser via a URL, such as or . You may be prompted to enter a password. If you don't remember it, you can often reset the password by pressing a button on the router itself, but be aware that if this procedure is chosen, you will probably lose the entire router configuration. If your router requires an app to set it up, please install the app on your phone or PC and use it to access the router’s settings. + +1. Find the DHCP/DNS settings. Look for the DNS letters next to a field which allows two or three sets of numbers, each broken into four groups of one to three digits. + +1. Enter your AdGuard Home server addresses there. + +1. On some router types, a custom DNS server cannot be set up. In that case, setting up AdGuard Home as a DHCP server may help. Otherwise, you should check the router manual on how to customize DNS servers on your specific router model. + +### Windows + +1. Open Control Panel through Start menu or Windows search. + +1. Go to Network and Internet category and then to Network and Sharing Center. + +1. On the left side of the screen find the “Change adapter settings” button and click it. + +1. Select your active connection, right-click it and choose Properties. + +1. Find “Internet Protocol Version 4 (TCP/IPv4)” (or, for IPv6, “Internet Protocol Version 6 (TCP/IPv6)”) in the list, select it and then click Properties again. + +1. Choose “Use the following DNS server addresses” and enter your AdGuard Home server addresses. + +### macOS + +1. Click the Apple icon and go to System Preferences. + +1. Click Network. + +1. Select the first connection in your list and click Advanced. + +1. Select the DNS tab and enter your AdGuard Home server addresses. + +### Android + +1. From the Android Menu home screen, tap Settings. + +1. Tap Wi-Fi on the menu. The screen listing all of the available networks will be shown (it is impossible to set custom DNS for mobile connection). + +1. Long press the network you're connected to and tap Modify Network. + +1. On some devices, you may need to check the box for Advanced to see further settings. To adjust your Android DNS settings, you will need to switch the IP settings from DHCP to Static. + +1. Change set DNS 1 and DNS 2 values to your AdGuard Home server addresses. + +### iOS + +1. From the home screen, tap Settings. + +1. Choose Wi-Fi in the left menu (it is impossible to configure DNS for mobile networks). + +1. Tap the name of the currently active network. + +1. In the DNS field enter your AdGuard Home server addresses. + +## Running without superuser (Linux only) {#running-without-superuser} + +You can run AdGuard Home without superuser privileges, but you need to either grant the binary a capability (on Linux) or instruct it to use a different port (all platforms). + +### Granting the necessary capabilities + +Using this method requires the `setcap` utility. You may need to install it using your Linux distribution's package manager. + +To allow AdGuard Home running on Linux to listen on port 53 without superuser privileges and bind its DNS servers to a particular interface run: + +```sh +sudo setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' ./AdGuardHome +``` + +Then run `./AdGuardHome` as an unprivileged user. + +### Changing the DNS listen port + +To configure AdGuard Home to listen on a port that does not require superuser privileges, stop AdGuard Home, open `AdGuardHome.yaml` in your editor, and find these lines: + +```yaml +dns: + # … + port: 53 +``` + +You can change the port 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. + +## Limitations {#limitations} + +Some file systems don't support the `mmap(2)` system call that the statistics system requires. See also [issue 1188]. + +You can resolve this issue: + +- either by supplying the `--work-dir DIRECTORY` arguments to `AdGuardHome` binary. This option will tell AGH to use another directory for all its files instead of the default `./data` directory. + +- or by creating symbolic links pointing to another file system that supports `mmap(2)` (e.g. tmpfs): + + ```sh + ln -s ${YOUR_AGH_PATH}/data/stats.db /tmp/stats.db + ln -s ${YOUR_AGH_PATH}/data/sessions.db /tmp/sessions.db + ``` + +[issue 1188]: https://github.com/AdguardTeam/AdGuardHome/issues/1188 diff --git a/docs/adguard-home/overview.md b/docs/adguard-home/overview.md new file mode 100644 index 000000000..1d1fed752 --- /dev/null +++ b/docs/adguard-home/overview.md @@ -0,0 +1,10 @@ +--- +title: Overview +sidebar_position: 1 +--- + +## What is AdGuard Home? + +AdGuard Home is a network-wide software for blocking ads and tracking. Unlike AdGuard Public DNS and AdGuard Private DNS, AdGuard Home is intended to be run on users' own machines, which gives experienced users more control over their DNS traffic. + +[This guide](getting-started.md) should help you get started. diff --git a/docs/adguard-home/running-securely.md b/docs/adguard-home/running-securely.md new file mode 100644 index 000000000..b475efdeb --- /dev/null +++ b/docs/adguard-home/running-securely.md @@ -0,0 +1,79 @@ +--- +title: Setting up AdGuard Home securely +sidebar_position: 4 +--- + +This page contains a list of additional recommendations to help ensure the security of your AdGuard home. + +## Choosing server addresses + +The first time you start AdGuard Home, you will be asked which interface it should use to serve plain DNS. The most secure and practical option depends on how you want to run AdGuard Home. You can change the address(es) later, by stopping your AdGuard Home, editing the `dns.bind_hosts` field in the configuration file, and restarting AdGuard Home. + +(Note that the UI currently only allows you to select one interface, but you can actually select multiple addresses through the configuration file. We will be improving the UI in future releases.) + +If you intend to run AdGuard Home on **your computer only,** select the loopback device (also known as “localhost”). It is usually named `localhost`, `lo`, or something similar and has the address `127.0.0.1`. + +If you plan to run AdGuard Home on a **router within a small isolated network,** select the locally-served interface. The names can vary, but they usually contain the words `wlan` or `wlp` and have an address starting with `192.168.`. You should probably also add the loopback address as well, if you want software the router itself to use AdGuard Home too. + +If you intend to run AdGuard Home on a **publicly accessible server,** you'll probably want to select the *All interfaces* option. Note that this may expose your server to DDoS attacks, so please read the sections on access settings and rate limiting below. + +## Access settings + +(If your AdGuard Home is not accessible from the outside, you can skip this section.) + +At the bottom of the *Settings → DNS settings* page you will find the *Access settings* section. These settings allow you to either ban clients that are known to abuse your AdGuard Home instance or to enable the Allowlist mode. The Allowlist mode is recommended for public instances where the number of clients is known and all of the clients are able to use secure DNS. + +To enable the Allowlist mode, enter [ClientIDs][cid] (recommended) or IP addresses for allowed clients in the *Allowed clients* field. + +[cid]: https://github.com/AdguardTeam/AdGuardHome/wiki/Clients#clientid + +## Disabling plain DNS + +(If your AdGuard Home is not accessible from the outside, you can skip this section.) + +If all clients using your AdGuard Home are able to use encrypted protocols, it is a good idea to disable plain DNS or make it unavailable from the outside is a good idea. + +If you want to completely disable plain DNS serving, you can do so on the *Settings → Encryption settings* page. + +If you want to restrict plain DNS to internal use only, stop your AdGuard Home, edit the `dns.bind_hosts` field in the configuration file to contain only the loopback address(es), and restart AdGuard Home. + +## Plain-DNS ratelimiting + +(If your AdGuard Home is not accessible from the outside, you can skip this section.) + +The default plain-DNS ratelimit of 20 should generally be sufficient, but if you have a list of known clients, you can add them to the allowlist and set a stricter ratelimit for other clients. + +## OS service concerns + +In order to prevent privilege escalations through binary planting, it is important that the directory where AdGuard Home is installed has proper ownership and privileges set. + +We thank Go Compile for assistance in this section. + +### Unix (FreeBSD, Linux, macOS, OpenBSD) + +AdGuard Home working directory, which is by default `/Applications/AdGuardHome` on macOS and `/opt/AdGuardHome` on other Unix systems, as well as the binary itself should generally have `root:root` ownership and not be writeable by anyone but `root`. You can check it with the following command, replacing `/opt/AdGuardHome` with your directory and `/opt/AdGuardHome/AdGuardHome` with your binary: + +```sh +ls -d -l /opt/AdGuardHome +ls -l /opt/AdGuardHome/AdGuardHome +``` + +A reasonably secure output should look something like this: + +```none +drwxr-xr-x 4 root root 4096 Jan 1 12:00 /opt/AdGuardHome/ +-rwxr-xr-x 1 root root 29409280 Jan 1 12:00 /opt/AdGuardHome/AdGuardHome +``` + +Note the lack of write permission for anyone but `root` as well as owned by `root`. If any of these are not correct, run the following commands under `root`: + +```sh +chmod 755 /opt/AdGuardHome/ /opt/AdGuardHome/AdGuardHome +chown root:root /opt/AdGuardHome/ /opt/AdGuardHome/AdGuardHome +``` + +### Windows + +The principle is the same on Windows: make sure that the AdGuard Home directory, typically `C:\Program Files\AdGuardHome`, and the `AdGuardHome.exe` binary have the permissions that would only allow regular users to read and execute/list them. + +In the future we plan to release Windows builds as MSI installer files that make sure that this is performed automatically. diff --git a/docs/miscellaneous/_category_.json b/docs/miscellaneous/_category_.json index 00c1136a9..7063deea2 100644 --- a/docs/miscellaneous/_category_.json +++ b/docs/miscellaneous/_category_.json @@ -1,6 +1,6 @@ { - "position": 6, + "position": 7, "label": "Miscellaneous", "collapsible": true, "collapsed": true -} \ No newline at end of file +} From 5e1d5d77ee0fecfb76444e549dafe4a80ca6c583 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Thu, 21 Dec 2023 22:33:05 +0300 Subject: [PATCH 2/5] Improve AdGuard Home docs --- docs/adguard-home/faq.md | 84 +++++++++++++++------------ docs/adguard-home/getting-started.md | 66 ++++++++++----------- docs/adguard-home/overview.md | 2 +- docs/adguard-home/running-securely.md | 34 ++++++++--- 4 files changed, 106 insertions(+), 80 deletions(-) diff --git a/docs/adguard-home/faq.md b/docs/adguard-home/faq.md index 18d881aa8..cdf78b178 100644 --- a/docs/adguard-home/faq.md +++ b/docs/adguard-home/faq.md @@ -3,13 +3,13 @@ title: FAQ sidebar_position: 3 --- -## Why AdGuard Home doesn't block ads? {#doesntblock} +## Why AdGuard Home doesn’t block ads or threats? {#doesntblock} -Suppose that AdGuard Home must block `somebadsite.com` but for some reason it doesn't. Let's try to resolve this issue. +Suppose that you want AdGuard Home to block `somebadsite.com` but for some reason it doesn’t. Let’s try to resolve this issue. -Most likely you didn't configure your device to use AdGuard Home as its default DNS server. To check if you're using AdGuard Home as the default DNS server: +Most likely you didn’t configure your device to use AdGuard Home as its default DNS server. To check if you’re using AdGuard Home as the default DNS server: -1. On Windows, open a Terminal window (Start → Run → `cmd.exe`). On other systems, open your Terminal application. +1. On Windows, open a Terminal window (*Start* → *Run* → `cmd.exe`). On other systems, open your Terminal application. 1. Execute `nslookup example.org`. It will print something like this: @@ -24,23 +24,23 @@ Most likely you didn't configure your device to use AdGuard Home as its default Address: ``` -1. Check if the `Server` IP address is the one on which AdGuard Home is running. If not, you need to configure your device, see [below](#defaultdns). +1. Check if the `Server` IP address is the one on which AdGuard Home is running. If not, you need to configure your device that way. See [below](#defaultdns) how to do it. 1. Ensure that your request to `example.org` appears in the AdGuard Home UI on the *Query Log* page. If not, you need to configure AdGuard Home to listen on the specified network interface. The most straightforward way to do so is to reinstall AdGuard Home with default settings. If you are sure that your device uses AdGuard Home as its default DNS server, but the problem persists, it might have something to do with an AdGuard Home misconfiguration. Please check and ensure that: -1. You have the “Block domains using filters and hosts files” setting enabled on the *Settings → General settings* page. +1. You have the *Block domains using filters and hosts files* setting enabled on the *Settings → General settings* page. 1. You have the appropriate safety mechanisms, such as Parental Control, enabled on the *Settings → General settings* page. 1. You have the appropriate filters enabled on the *Filters → DNS blocklists* page. -1. You don't have any exception rule lists that may allow the requests enabled on the *Filters → DNS allowlists* page. +1. You don’t have any exception rule lists that may allow the requests enabled on the *Filters → DNS allowlists* page. -1. You don't have any DNS rewrites that may interfere with the *Filters → DNS rewrites* page. +1. You don’t have any DNS rewrites that may interfere on the *Filters → DNS rewrites* page. -1. You don't have any custom filtering rules that may interfere with the *Filters → Custom filtering rules* page. +1. You don’t have any custom filtering rules that may interfere on the *Filters → Custom filtering rules* page. ## Where can I inspect the logs? {#logs} @@ -56,9 +56,9 @@ The default location of the plain-text logs (not to be confused with the query l - **Linux** systems with **Snapcraft** use the `snap logs adguard-home` command. -- **FreeBSD:** `/var/log/daemon.log` (**since v0.108.0-b.4**). Before **v0.108.0-b.4** no logs are written by default. +- **FreeBSD:** `/var/log/daemon.log`. -- **OpenBSD:** `/var/log/daemon` (**since v0.108.0-b.4**). Before **v0.108.0-b.4** no logs are written by default. +- **OpenBSD:** `/var/log/daemon`. - On **Windows:** the [Windows Event Log][wlog] is used. @@ -66,7 +66,7 @@ The default location of the plain-text logs (not to be confused with the query l ## How to configure AdGuard Home to write verbose-level logs? {#verboselog} -To troubleshoot a complicated issue, the verbose-level logging is sometimes required. Here's how to enable it: +To troubleshoot a complicated issue, the verbose-level logging is sometimes required. Here’s how to enable it: 1. Stop AdGuard Home: @@ -82,34 +82,36 @@ To troubleshoot a complicated issue, the verbose-level logging is sometimes requ 1. Set `log.verbose` to `true`. - **NOTE:** Before v0.107.34 use `verbose` and `log_file` properties. - 1. Restart AdGuard Home and reproduce the issue: ```sh ./AdGuardHome -s start ``` +1. Once you’re done with the debugging, set `log.verbose` back to `false`. + ## How to show a custom block page? {#customblock} -### A note about HTTPS +:::note A note about HTTPS Before doing any of this, please note that modern browsers are set up to use HTTPS, so they validate the authenticity of the web server certificate. That means that using any of these will result in warning screens. -There are a couple of proposed extensions that, when they become reasonably well supported by clients, would allow for a better user experience, including the [RFC 8914 Extended DNS Error codes][rfc8914] and the [DNS Access Denied Error Page RFC draft][rfcaccess]. We'll implement them when browsers actually start to support them. +There are a couple of proposed extensions that, when they become reasonably well supported by clients, would allow for a better user experience, including the [RFC 8914 Extended DNS Error codes][rfc8914] and the [DNS Access Denied Error Page RFC draft][rfcaccess]. We’ll implement them when browsers actually start to support them. [rfc8914]: https://datatracker.ietf.org/doc/html/rfc8914 [rfcaccess]: https://datatracker.ietf.org/doc/html/draft-reddy-dnsop-error-page-08 +::: + ### Prerequisites -To use any of these ways to show a custom block page, you'll need an HTTP server running on some IP address and serving the page in question on all routes. Something like [`pixelserv-tls`][pxsrv]. +To use any of these ways to show a custom block page, you’ll need an HTTP server running on some IP address and serving the page in question on all routes. Something like [`pixelserv-tls`][pxsrv]. [pxsrv]: https://github.com/kvic-z/pixelserv-tls ### Custom block page for Parental Control and Safe Browsing filters -There is currently no way to set these parameters from the UI, so you'll need to edit the configuration file manually: +There is currently no way to set these parameters from the UI, so you’ll need to edit the configuration file manually: 1. Stop AdGuard Home: @@ -143,11 +145,11 @@ There is currently no way to set these parameters from the UI, so you'll need to 1. Open the *Settings → DNS settings* page. -1. In the “DNS server configuration” section, select the “Custom IP” radio button in the “Blocking mode” selector and enter the IPv4 and IPv6 addresses of the server. +1. In the *DNS server configuration* section, select the *Custom IP* radio button in the *Blocking mode* selector and enter the IPv4 and IPv6 addresses of the server. -1. Click “Save”. +1. Click *Save.* -## How to change dashboard interface's address? {#webaddr} +## How to change dashboard interface’s address? {#webaddr} 1. Stop AdGuard Home: @@ -171,7 +173,7 @@ There is currently no way to set these parameters from the UI, so you'll need to ## How to set up AdGuard Home as default DNS server? {#defaultdns} -See the [“Configuring Devices” section](getting-started.md#configure-devices) on the *Getting Started* page. +See the [*Configuring Devices* section](getting-started.md#configure-devices) on the *Getting Started* page. ## Are there any known limitations? {#limitations} @@ -185,7 +187,9 @@ Essentially, any advertising that shares a domain with content cannot be blocked ### Is there a chance to handle this in the future? -DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the standalone AdGuard applications. We're going to bring this feature support to AdGuard Home in the future. Unfortunately, even in this case, there still will be cases when this won't be enough or would require quite complicated configuration. +DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the [standalone AdGuard applications][adguard]. We’re going to bring this feature support to AdGuard Home in the future. Unfortunately, even in this case, there still will be cases when this won’t be enough or would require quite complicated configuration. + +[adguard]: https://adguard.com/ ## Why am I getting `bind: address already in use` error when trying to install on Ubuntu? {#bindinuse} @@ -205,9 +209,9 @@ systemd-r 14542 systemd-resolve 14u IPv4 86179 0t0 TCP 127.0.0.53:domain To fix this, you need to either disable the `systemd-resolved` daemon or choose a different network interface and bind to an accessible IP address on it, for instance, the IP address of your router inside your network. But if you do need to listen on `localhost`, there are several solutions. -Firstly, AdGuard Home can detect such configurations and disable `systemd-resolved` for you if you press the “Fix” button, which is shown near the `address already in use` message on the installation screen. +Firstly, AdGuard Home can detect such configurations and disable `systemd-resolved` for you if you press the *Fix* button, which is shown near the `address already in use` message on the installation screen. -Secondly, if that doesn't work, follow the guide below. Note that if you're using AdGuard Home with docker or snap, you'll have to do it yourself. +Secondly, if that doesn’t work, follow the guide below. Note that if you’re using AdGuard Home with docker or snap, you’ll have to do it yourself. 1. Create the `/etc/systemd/resolved.conf.d` directory, if necessary: @@ -223,7 +227,7 @@ Secondly, if that doesn't work, follow the guide below. Note that if you're usin DNSStubListener=no ``` - Specifying `127.0.0.1` as DNS server address **is necessary** because otherwise the nameserver will be `127.0.0.53` which doesn't work without `DNSStubListener`. + Specifying `127.0.0.1` as DNS server address **is necessary** because otherwise the nameserver will be `127.0.0.53` which doesn’t work without `DNSStubListener`. 1. Activate another `resolv.conf` file: @@ -238,11 +242,11 @@ Secondly, if that doesn't work, follow the guide below. Note that if you're usin sudo systemctl reload-or-restart systemd-resolved ``` -After that, `systemd-resolved` shouldn't be shown in the output of `lsof`, and AdGuard Home should be able to bind to `127.0.0.1:53`. +After that, `systemd-resolved` shouldn’t be shown in the output of `lsof`, and AdGuard Home should be able to bind to `127.0.0.1:53`. ## How to configure a reverse proxy server for AdGuard Home? {#reverseproxy} -If you're already running a web server and want to access the AdGuard Home dashboard UI from a URL like `http://YOUR_SERVER/aghome/`, you can use this configuration for your web server: +If you’re already running a web server and want to access the AdGuard Home dashboard UI from a URL like `http://YOUR_SERVER/aghome/`, you can use this configuration for your web server: ### nginx @@ -278,11 +282,11 @@ DOMAIN { ### Disable DoH encryption on AdGuard Home -When you use TLS on your reverse proxy server, there's no need to use TLS on AdGuard Home. Set `allow_unencrypted_doh: true` in `AdGuardHome.yaml` to allow AdGuard Home respond to DoH requests without TLS encryption. +When you use TLS on your reverse proxy server, there’s no need to use TLS on AdGuard Home. Set `allow_unencrypted_doh: true` in `AdGuardHome.yaml` to allow AdGuard Home respond to DoH requests without TLS encryption. ### Real IP addresses of clients -**Since v0.107.0,** you can set the parameter `trusted_proxies` to the IP address(es) of your HTTP proxy to make AdGuard Home take the headers containing the real client IP address into account. See the [configuration][conf] and [encryption][encr] pages for more information. +You can set the parameter `trusted_proxies` to the IP address(es) of your HTTP proxy to make AdGuard Home take the headers containing the real client IP address into account. See the [configuration][conf] and [encryption][encr] pages for more information. [encr]: https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption#reverse-proxy [conf]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration @@ -325,7 +329,7 @@ You should move your AdGuard Home installation or working directory to another l ## How to update AdGuard Home manually? {#manual-update} -In case the button isn't shown or an automatic update has failed, you can update manually. In the examples below, we'll use AdGuard Home releases for Linux and Windows for AMD64 CPUs. +In case the button isn’t shown or an automatic update has failed, you can update manually. In the examples below, we’ll use AdGuard Home releases for Linux and Windows for AMD64 CPUs. ### Unix (Linux, macOS, BSD) {#manual-update-unix} @@ -343,7 +347,7 @@ In case the button isn't shown or an automatic update has failed, you can update 'https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz' ``` -1. Navigate to the directory where AdGuard Home was installed. On most Unix systems the default directory is `/opt/AdGuardHome`, but on macOS it's `/Applications/AdGuardHome`. +1. Navigate to the directory where AdGuard Home is installed. On most Unix systems the default directory is `/opt/AdGuardHome`, but on macOS it’s `/Applications/AdGuardHome`. 1. Stop AdGuard Home: @@ -351,7 +355,11 @@ In case the button isn't shown or an automatic update has failed, you can update sudo ./AdGuardHome -s stop ``` - (On OpenBSD you probably want to use `doas` instead of `sudo`.) + :::note OpenBSD + + On OpenBSD you probably want to use `doas` instead of `sudo`. + + ::: 1. Backup your data. That is, your configuration file and the data directory (`AdGuardHome.yaml` and `data/` by default). For example, to backup your data to a new directory called `~/my-agh-backup`: @@ -394,8 +402,6 @@ In case the button isn't shown or an automatic update has failed, you can update sudo ./AdGuardHome -s start ``` -(On OpenBSD you probably want to use `doas` instead of `sudo`.) - [releases]: https://github.com/AdguardTeam/AdGuardHome/releases/latest ### Windows (Using PowerShell) {#manual-update-win} @@ -410,7 +416,7 @@ In all examples below, the PowerShell must be run as Administrator. Invoke-WebRequest -OutFile "$outFile" -Uri "$aghUri" ``` -1. Navigate to the directory where AdGuard Home was installed. In the examples below, we'll use `C:\Program Files\AdGuardHome`. +1. Navigate to the directory where AdGuard Home was installed. In the examples below, we’ll use `C:\Program Files\AdGuardHome`. 1. Stop AdGuard Home: @@ -454,7 +460,11 @@ In all examples below, the PowerShell must be run as Administrator. The way to uninstall AdGuard Home depends on how you installed it. -**IMPORTANT:** After uninstalling AdGuard Home, don't forget to change your devices configuration and point them to a different DNS server. +::: caution + +After uninstalling AdGuard Home, don’t forget to change your devices configuration and point them to a different DNS server. + +::: ### Regular installation diff --git a/docs/adguard-home/getting-started.md b/docs/adguard-home/getting-started.md index c2f95b61c..dab990cd4 100644 --- a/docs/adguard-home/getting-started.md +++ b/docs/adguard-home/getting-started.md @@ -29,13 +29,13 @@ We also provide an [official AdGuard Home docker image][docker] and an [official Some other unofficial options include: -- (Maintained by @frenck) [Home Assistant add-on][has]. +- (Maintained by [@frenck](https://github.com/frenck)) [Home Assistant add-on][has]. -- (Maintained by @kongfl888) [OpenWrt LUCI app][luci]. +- (Maintained by [@kongfl888](https://github.com/kongfl888)) [OpenWrt LUCI app][luci]. -- (Maintained by @graysky2) [Arch Linux][arch], [Arch Linux ARM][archarm], and other Arch-based OSs, may build via the [`adguardhome` package][aghaur] in the [AUR][aur]. +- (Maintained by [@graysky2](https://github.com/graysky2)) [Arch Linux][arch], [Arch Linux ARM][archarm], and other Arch-based OSs, may build via the [`adguardhome` package][aghaur] in the [AUR][aur]. -- (Maintained by @gramakri) [Cloudron app][cloudron]. +- (Maintained by [@gramakri](https://github.com/gramakri)) [Cloudron app][cloudron]. [aghaur]: https://aur.archlinux.org/packages/adguardhome/ [arch]: https://www.archlinux.org/ @@ -69,7 +69,7 @@ sudo ./AdGuardHome On Windows, run `cmd.exe` or PowerShell with admin privileges and run `AdGuardHome.exe` from there. -When you run AdGuard Home for the first time, it starts listening to `0.0.0.0:3000` and prompts you to open it in your browser: +When you run AdGuard Home for the first time, it starts listening on `0.0.0.0:3000` and prompts you to open it in your browser: ```none AdGuard Home is available at the following addresses: @@ -80,9 +80,9 @@ go to http://[::1]:3000 There you will go through the initial configuration wizard. -![AdGuard Home network interface selection screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install2.png) +![AdGuard Home network interface selection screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install2.jpg) -![AdGuard Home user creation screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install3.png) +![AdGuard Home user creation screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install3.jpg) See [our article on running AdGuard Home securely](running-securely.md) for guidance on how to select the initial configuration that fits you best. @@ -94,7 +94,7 @@ The next step would be to register AdGuard Home as a system service (aka daemon) sudo ./AdGuardHome -s install ``` -On Windows, run `cmd.exe` with admin privileges and run `AdGuardHome.exe -s install` to register a windows service. +On Windows, run `cmd.exe` with admin privileges and run `AdGuardHome.exe -s install` to register a Windows service. Here are the other commands you might need to control the service: @@ -106,7 +106,7 @@ Here are the other commands you might need to control the service: ### Logs -By default, the logs are written to stderr when you run AdGuard Home in a terminal. If you run it as a service, the log output depends on the platform: +By default, the logs are written to `stderr` when you run AdGuard Home in a terminal. If you run it as a service, the log output depends on the platform: - On macOS, the log is written to `/var/log/AdGuardHome.*.log` files. @@ -120,13 +120,13 @@ You can change this behavior in the AdGuard Home [configuration file][conf]. ## Updating {#update} -![An example of an update notification](https://cdn.adtidy.org/content/kb/dns/adguard-home/updatenotification.png) +![An example of an update notification](https://cdn.adtidy.org/content/kb/dns/adguard-home/updatenotification.jpg) -When a new version is released, AdGuard Home's UI shows a notification message and the “Update now” button. Click this button, and AdGuard Home will be automatically updated to the latest version. Your current AdGuard Home executable file is saved inside the `backup` directory along with the current configuration file, so you can revert the changes, if necessary. +When a new version is released, AdGuard Home’s UI shows a notification message and the *Update now* button. Click this button, and AdGuard Home will be automatically updated to the latest version. Your current AdGuard Home executable file is saved inside the `backup` directory along with the current configuration file, so you can revert the changes, if necessary. ### Manual update {#manual-update} -In case the button isn't shown or an automatic update has failed, you can update manually. We have a [detailed guide on manual updates][mupd], but in short: +In case the button isn’t shown or an automatic update has failed, you can update manually. We have a [detailed guide on manual updates][mupd], but in short: 1. Download the new AdGuard Home package. @@ -154,9 +154,9 @@ To update AdGuard Home package without the need to use Web API run: ### Router -This setup will automatically cover all devices connected to your home router, and you won't need to configure each of them manually. +This setup will automatically cover all devices connected to your home router, and you won’t need to configure each of them manually. -1. Open the preferences for your router. Usually, you can access it from your browser via a URL, such as or . You may be prompted to enter a password. If you don't remember it, you can often reset the password by pressing a button on the router itself, but be aware that if this procedure is chosen, you will probably lose the entire router configuration. If your router requires an app to set it up, please install the app on your phone or PC and use it to access the router’s settings. +1. Open the preferences for your router. Usually, you can access it from your browser via a URL, such as or . You may be prompted to enter a password. If you don’t remember it, you can often reset the password by pressing a button on the router itself, but be aware that if this procedure is chosen, you will probably lose the entire router configuration. If your router requires an app to set it up, please install the app on your phone or PC and use it to access the router’s settings. 1. Find the DHCP/DNS settings. Look for the DNS letters next to a field which allows two or three sets of numbers, each broken into four groups of one to three digits. @@ -166,49 +166,49 @@ This setup will automatically cover all devices connected to your home router, a ### Windows -1. Open Control Panel through Start menu or Windows search. +1. Open *Control Panel* through Start menu or Windows search. -1. Go to Network and Internet category and then to Network and Sharing Center. +1. Go to *Network and Internet* category and then to *Network and Sharing Center.* -1. On the left side of the screen find the “Change adapter settings” button and click it. +1. On the left side of the screen find the *Change adapter settings* button and click it. -1. Select your active connection, right-click it and choose Properties. +1. Select your active connection, right-click it and choose *Properties.* -1. Find “Internet Protocol Version 4 (TCP/IPv4)” (or, for IPv6, “Internet Protocol Version 6 (TCP/IPv6)”) in the list, select it and then click Properties again. +1. Find *Internet Protocol Version 4 (TCP/IPv4)* (or, for IPv6, *Internet Protocol Version 6 (TCP/IPv6)*) in the list, select it and then click Properties again. -1. Choose “Use the following DNS server addresses” and enter your AdGuard Home server addresses. +1. Choose *Use the following DNS server addresses* and enter your AdGuard Home server addresses. ### macOS -1. Click the Apple icon and go to System Preferences. +1. Click the Apple icon and go to *System Preferences.* -1. Click Network. +1. Click *Network.* -1. Select the first connection in your list and click Advanced. +1. Select the first connection in your list and click *Advanced.* 1. Select the DNS tab and enter your AdGuard Home server addresses. ### Android -1. From the Android Menu home screen, tap Settings. +1. From the Android Menu home screen, tap *Settings.* -1. Tap Wi-Fi on the menu. The screen listing all of the available networks will be shown (it is impossible to set custom DNS for mobile connection). +1. Tap *Wi-Fi* on the menu. The screen listing all of the available networks will be shown (it is impossible to set custom DNS for mobile connection). -1. Long press the network you're connected to and tap Modify Network. +1. Long press the network you’re connected to and tap *Modify Network.* -1. On some devices, you may need to check the box for Advanced to see further settings. To adjust your Android DNS settings, you will need to switch the IP settings from DHCP to Static. +1. On some devices, you may need to check the box for *Advanced* to see further settings. To adjust your Android DNS settings, you will need to switch the IP settings from *DHCP* to *Static.* 1. Change set DNS 1 and DNS 2 values to your AdGuard Home server addresses. ### iOS -1. From the home screen, tap Settings. +1. From the home screen, tap *Settings.* -1. Choose Wi-Fi in the left menu (it is impossible to configure DNS for mobile networks). +1. Choose *Wi-Fi* in the left menu (it is impossible to configure DNS for mobile networks). 1. Tap the name of the currently active network. -1. In the DNS field enter your AdGuard Home server addresses. +1. In the *DNS* field enter your AdGuard Home server addresses. ## Running without superuser (Linux only) {#running-without-superuser} @@ -216,7 +216,7 @@ You can run AdGuard Home without superuser privileges, but you need to either gr ### Granting the necessary capabilities -Using this method requires the `setcap` utility. You may need to install it using your Linux distribution's package manager. +Using this method requires the `setcap` utility. You may need to install it using your Linux distribution’s package manager. To allow AdGuard Home running on Linux to listen on port 53 without superuser privileges and bind its DNS servers to a particular interface run: @@ -240,11 +240,11 @@ You can change the port to anything above 1024 to avoid requiring superuser priv ## Limitations {#limitations} -Some file systems don't support the `mmap(2)` system call that the statistics system requires. See also [issue 1188]. +Some file systems don’t support the `mmap(2)` system call that the statistics system requires. See also [issue 1188]. You can resolve this issue: -- either by supplying the `--work-dir DIRECTORY` arguments to `AdGuardHome` binary. This option will tell AGH to use another directory for all its files instead of the default `./data` directory. +- either by supplying the `--work-dir DIRECTORY` arguments to the `AdGuardHome` binary. This option will tell AGH to use another directory for all its files instead of the default `./data` directory. - or by creating symbolic links pointing to another file system that supports `mmap(2)` (e.g. tmpfs): diff --git a/docs/adguard-home/overview.md b/docs/adguard-home/overview.md index 1d1fed752..8072b410c 100644 --- a/docs/adguard-home/overview.md +++ b/docs/adguard-home/overview.md @@ -5,6 +5,6 @@ sidebar_position: 1 ## What is AdGuard Home? -AdGuard Home is a network-wide software for blocking ads and tracking. Unlike AdGuard Public DNS and AdGuard Private DNS, AdGuard Home is intended to be run on users' own machines, which gives experienced users more control over their DNS traffic. +AdGuard Home is a network-wide software for blocking ads and tracking. Unlike AdGuard Public DNS and AdGuard Private DNS, AdGuard Home is intended to be run on users’ own machines, which gives experienced users more control over their DNS traffic. [This guide](getting-started.md) should help you get started. diff --git a/docs/adguard-home/running-securely.md b/docs/adguard-home/running-securely.md index b475efdeb..66491fe4b 100644 --- a/docs/adguard-home/running-securely.md +++ b/docs/adguard-home/running-securely.md @@ -9,17 +9,25 @@ This page contains a list of additional recommendations to help ensure the secur The first time you start AdGuard Home, you will be asked which interface it should use to serve plain DNS. The most secure and practical option depends on how you want to run AdGuard Home. You can change the address(es) later, by stopping your AdGuard Home, editing the `dns.bind_hosts` field in the configuration file, and restarting AdGuard Home. -(Note that the UI currently only allows you to select one interface, but you can actually select multiple addresses through the configuration file. We will be improving the UI in future releases.) +::: note + +The UI currently only allows you to select one interface, but you can actually select multiple addresses through the configuration file. We will be improving the UI in future releases. + +::: If you intend to run AdGuard Home on **your computer only,** select the loopback device (also known as “localhost”). It is usually named `localhost`, `lo`, or something similar and has the address `127.0.0.1`. -If you plan to run AdGuard Home on a **router within a small isolated network,** select the locally-served interface. The names can vary, but they usually contain the words `wlan` or `wlp` and have an address starting with `192.168.`. You should probably also add the loopback address as well, if you want software the router itself to use AdGuard Home too. +If you plan to run AdGuard Home on a **router within a small isolated network,** select the locally-served interface. The names can vary, but they usually contain the words `wlan` or `wlp` and have an address starting with `192.168.`. You should probably also add the loopback address as well, if you want software on the router itself to use AdGuard Home too. -If you intend to run AdGuard Home on a **publicly accessible server,** you'll probably want to select the *All interfaces* option. Note that this may expose your server to DDoS attacks, so please read the sections on access settings and rate limiting below. +If you intend to run AdGuard Home on a **publicly accessible server,** you’ll probably want to select the *All interfaces* option. Note that this may expose your server to DDoS attacks, so please read the sections on access settings and rate limiting below. ## Access settings -(If your AdGuard Home is not accessible from the outside, you can skip this section.) +::: note + +If your AdGuard Home is not accessible from the outside, you can skip this section. + +::: At the bottom of the *Settings → DNS settings* page you will find the *Access settings* section. These settings allow you to either ban clients that are known to abuse your AdGuard Home instance or to enable the Allowlist mode. The Allowlist mode is recommended for public instances where the number of clients is known and all of the clients are able to use secure DNS. @@ -29,9 +37,13 @@ To enable the Allowlist mode, enter [ClientIDs][cid] (recommended) or IP address ## Disabling plain DNS -(If your AdGuard Home is not accessible from the outside, you can skip this section.) +::: note -If all clients using your AdGuard Home are able to use encrypted protocols, it is a good idea to disable plain DNS or make it unavailable from the outside is a good idea. +If your AdGuard Home is not accessible from the outside, you can skip this section. + +::: + +If all clients using your AdGuard Home are able to use encrypted protocols, it is a good idea to disable plain DNS or make it unavailable from the outside. If you want to completely disable plain DNS serving, you can do so on the *Settings → Encryption settings* page. @@ -39,15 +51,19 @@ If you want to restrict plain DNS to internal use only, stop your AdGuard Home, ## Plain-DNS ratelimiting -(If your AdGuard Home is not accessible from the outside, you can skip this section.) +::: note + +If your AdGuard Home is not accessible from the outside, you can skip this section. + +::: The default plain-DNS ratelimit of 20 should generally be sufficient, but if you have a list of known clients, you can add them to the allowlist and set a stricter ratelimit for other clients. ## OS service concerns -In order to prevent privilege escalations through binary planting, it is important that the directory where AdGuard Home is installed has proper ownership and privileges set. +In order to prevent privilege escalations through binary planting, it is important that the directory where AdGuard Home is installed to has proper ownership and privileges set. -We thank Go Compile for assistance in this section. +We thank Go Compile for assistance in writing this section. ### Unix (FreeBSD, Linux, macOS, OpenBSD) From b5c6558a992f9e46fc79beb3ef77d865e91937f7 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Tue, 23 Jan 2024 20:02:33 +0300 Subject: [PATCH 3/5] Improve wording in AdGuard Home docs --- docs/adguard-home/faq.md | 94 +++++++++++++-------------- docs/adguard-home/getting-started.md | 50 +++++++------- docs/adguard-home/overview.md | 2 +- docs/adguard-home/running-securely.md | 12 ++-- 4 files changed, 79 insertions(+), 79 deletions(-) diff --git a/docs/adguard-home/faq.md b/docs/adguard-home/faq.md index cdf78b178..142d510dd 100644 --- a/docs/adguard-home/faq.md +++ b/docs/adguard-home/faq.md @@ -3,11 +3,11 @@ title: FAQ sidebar_position: 3 --- -## Why AdGuard Home doesn’t block ads or threats? {#doesntblock} +## Why doesn’t AdGuard Home block ads or threats? {#doesntblock} -Suppose that you want AdGuard Home to block `somebadsite.com` but for some reason it doesn’t. Let’s try to resolve this issue. +Suppose that you want AdGuard Home to block `somebadsite.com` but for some reason it doesn’t. Let’s try to solve this problem. -Most likely you didn’t configure your device to use AdGuard Home as its default DNS server. To check if you’re using AdGuard Home as the default DNS server: +Most likely, you haven’t configured your device to use AdGuard Home as the default DNS server. To check if you’re using AdGuard Home as your default DNS server: 1. On Windows, open a Terminal window (*Start* → *Run* → `cmd.exe`). On other systems, open your Terminal application. @@ -24,17 +24,17 @@ Most likely you didn’t configure your device to use AdGuard Home as its defaul Address: ``` -1. Check if the `Server` IP address is the one on which AdGuard Home is running. If not, you need to configure your device that way. See [below](#defaultdns) how to do it. +1. Check if the `Server` IP address is the one where AdGuard Home is running. If not, you need to configure your device accordingly. See [below](#defaultdns) how to do this. -1. Ensure that your request to `example.org` appears in the AdGuard Home UI on the *Query Log* page. If not, you need to configure AdGuard Home to listen on the specified network interface. The most straightforward way to do so is to reinstall AdGuard Home with default settings. +1. Ensure that your request to `example.org` appears in the AdGuard Home UI on the *Query Log* page. If not, you need to configure AdGuard Home to listen on the specified network interface. The easiest way to do this is to reinstall AdGuard Home with default settings. -If you are sure that your device uses AdGuard Home as its default DNS server, but the problem persists, it might have something to do with an AdGuard Home misconfiguration. Please check and ensure that: +If you are sure that your device is using AdGuard Home as its default DNS server, but the problem persists, it may be due to a misconfiguration of AdGuard Home. Please check and make sure that: -1. You have the *Block domains using filters and hosts files* setting enabled on the *Settings → General settings* page. +1. You have enabled the *Block domains using filters and hosts files* setting on the *Settings → General settings* page. -1. You have the appropriate safety mechanisms, such as Parental Control, enabled on the *Settings → General settings* page. +1. You have enabled the appropriate security mechanisms, such as Parental Control, on the *Settings → General settings* page. -1. You have the appropriate filters enabled on the *Filters → DNS blocklists* page. +1. You have enabled the appropriate filters on the *Filters → DNS blocklists* page. 1. You don’t have any exception rule lists that may allow the requests enabled on the *Filters → DNS allowlists* page. @@ -42,7 +42,7 @@ If you are sure that your device uses AdGuard Home as its default DNS server, bu 1. You don’t have any custom filtering rules that may interfere on the *Filters → Custom filtering rules* page. -## Where can I inspect the logs? {#logs} +## Where can I view the logs? {#logs} The default location of the plain-text logs (not to be confused with the query logs) depends on the operating system and installation mode: @@ -60,11 +60,11 @@ The default location of the plain-text logs (not to be confused with the query l - **OpenBSD:** `/var/log/daemon`. -- On **Windows:** the [Windows Event Log][wlog] is used. +- **Windows:** the [Windows Event Log][wlog] is used. [wlog]: https://docs.microsoft.com/en-us/windows/win32/wes/windows-event-log -## How to configure AdGuard Home to write verbose-level logs? {#verboselog} +## How do I configure AdGuard Home to write verbose-level logs? {#verboselog} To troubleshoot a complicated issue, the verbose-level logging is sometimes required. Here’s how to enable it: @@ -90,13 +90,13 @@ To troubleshoot a complicated issue, the verbose-level logging is sometimes requ 1. Once you’re done with the debugging, set `log.verbose` back to `false`. -## How to show a custom block page? {#customblock} +## How do I show a custom block page? {#customblock} -:::note A note about HTTPS +:::note -Before doing any of this, please note that modern browsers are set up to use HTTPS, so they validate the authenticity of the web server certificate. That means that using any of these will result in warning screens. +Before doing any of this, please note that modern browsers are set up to use HTTPS, so they validate the authenticity of the web server certificate. This means that using any of these will result in warning screens. -There are a couple of proposed extensions that, when they become reasonably well supported by clients, would allow for a better user experience, including the [RFC 8914 Extended DNS Error codes][rfc8914] and the [DNS Access Denied Error Page RFC draft][rfcaccess]. We’ll implement them when browsers actually start to support them. +There is a number of proposed extensions that, if reasonably well supported by clients, would provide a better user experience, including the [RFC 8914 Extended DNS Error codes][rfc8914] and the [DNS Access Denied Error Page RFC draft][rfcaccess]. We’ll implement them when browsers actually start to support them. [rfc8914]: https://datatracker.ietf.org/doc/html/rfc8914 [rfcaccess]: https://datatracker.ietf.org/doc/html/draft-reddy-dnsop-error-page-08 @@ -105,7 +105,7 @@ There are a couple of proposed extensions that, when they become reasonably well ### Prerequisites -To use any of these ways to show a custom block page, you’ll need an HTTP server running on some IP address and serving the page in question on all routes. Something like [`pixelserv-tls`][pxsrv]. +To use any of these methods to display a custom block page, you’ll need an HTTP server running on some IP address and serving the page in question on all routes. Something like [`pixelserv-tls`][pxsrv]. [pxsrv]: https://github.com/kvic-z/pixelserv-tls @@ -149,7 +149,7 @@ There is currently no way to set these parameters from the UI, so you’ll need 1. Click *Save.* -## How to change dashboard interface’s address? {#webaddr} +## How do I change dashboard interface’s address? {#webaddr} 1. Stop AdGuard Home: @@ -171,7 +171,7 @@ There is currently no way to set these parameters from the UI, so you’ll need ./AdGuardHome -s start ``` -## How to set up AdGuard Home as default DNS server? {#defaultdns} +## How do I set up AdGuard Home as default DNS server? {#defaultdns} See the [*Configuring Devices* section](getting-started.md#configure-devices) on the *Getting Started* page. @@ -183,17 +183,17 @@ Here are some examples of what cannot be blocked by a DNS-level blocker: - Facebook, Twitter, Instagram sponsored posts. -Essentially, any advertising that shares a domain with content cannot be blocked by a DNS-level blocker. +Basically, any ad that shares a domain with content cannot be blocked by a DNS-level blocker. -### Is there a chance to handle this in the future? +### Any possibility of dealing with this in the future? -DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the [standalone AdGuard applications][adguard]. We’re going to bring this feature support to AdGuard Home in the future. Unfortunately, even in this case, there still will be cases when this won’t be enough or would require quite complicated configuration. +DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the [standalone AdGuard applications][adguard]. We’ll be adding support for this feature to AdGuard Home in the future. Unfortunately, even then there will still be cases there it won’t be enough or it will require quite complicated configuration. [adguard]: https://adguard.com/ -## Why am I getting `bind: address already in use` error when trying to install on Ubuntu? {#bindinuse} +## Why do I get `bind: address already in use` error when trying to install on Ubuntu? {#bindinuse} -This happens because the port 53 on `localhost`, which is used for DNS, is already taken by another program. Ubuntu comes with a local DNS called `systemd-resolved`, which uses the address `127.0.0.53:53` and thus prevents AdGuard Home from binding to `127.0.0.1:53`. You can see that by running: +This happens because the port 53 on `localhost`, which is used for DNS, is already taken by another program. Ubuntu comes with a local DNS called `systemd-resolved`, which uses the address `127.0.0.53:53`, thus preventing AdGuard Home from binding to `127.0.0.1:53`. You can see this by running: ```sh sudo lsof -i :53 @@ -207,11 +207,11 @@ systemd-r 14542 systemd-resolve 13u IPv4 86178 0t0 UDP 127.0.0.53:domain systemd-r 14542 systemd-resolve 14u IPv4 86179 0t0 TCP 127.0.0.53:domain ``` -To fix this, you need to either disable the `systemd-resolved` daemon or choose a different network interface and bind to an accessible IP address on it, for instance, the IP address of your router inside your network. But if you do need to listen on `localhost`, there are several solutions. +To fix this, you must either disable the `systemd-resolved` daemon or choose a different network interface and bind to an accessible IP address on it, such as the IP address of your router inside your network. But if you do need to listen on `localhost`, there are several solutions. -Firstly, AdGuard Home can detect such configurations and disable `systemd-resolved` for you if you press the *Fix* button, which is shown near the `address already in use` message on the installation screen. +Firstly, AdGuard Home can detect such configurations and disable `systemd-resolved` for you if you press the *Fix* button located next to the `address already in use` message on the installation screen. -Secondly, if that doesn’t work, follow the guide below. Note that if you’re using AdGuard Home with docker or snap, you’ll have to do it yourself. +Secondly, if that doesn’t work, follow the instructions below. Note that if you’re using AdGuard Home with docker or snap, you’ll have to do this yourself. 1. Create the `/etc/systemd/resolved.conf.d` directory, if necessary: @@ -227,7 +227,7 @@ Secondly, if that doesn’t work, follow the guide below. Note that if you’re DNSStubListener=no ``` - Specifying `127.0.0.1` as DNS server address **is necessary** because otherwise the nameserver will be `127.0.0.53` which doesn’t work without `DNSStubListener`. + Specifying `127.0.0.1` as the DNS server address is **necessary.** Otherwise the nameserver will be `127.0.0.53` which won’t work without `DNSStubListener`. 1. Activate another `resolv.conf` file: @@ -244,7 +244,7 @@ Secondly, if that doesn’t work, follow the guide below. Note that if you’re After that, `systemd-resolved` shouldn’t be shown in the output of `lsof`, and AdGuard Home should be able to bind to `127.0.0.1:53`. -## How to configure a reverse proxy server for AdGuard Home? {#reverseproxy} +## How do I configure a reverse proxy server for AdGuard Home? {#reverseproxy} If you’re already running a web server and want to access the AdGuard Home dashboard UI from a URL like `http://YOUR_SERVER/aghome/`, you can use this configuration for your web server: @@ -270,7 +270,7 @@ location /aghome/ { } ``` -Or, if you just want to serve AdGuard Home with automatic TLS, use a configuration similar to the example shown below: +Or, if you only want to serve AdGuard Home with automatic TLS, use a configuration similar to the example shown below: ```none DOMAIN { @@ -282,16 +282,16 @@ DOMAIN { ### Disable DoH encryption on AdGuard Home -When you use TLS on your reverse proxy server, there’s no need to use TLS on AdGuard Home. Set `allow_unencrypted_doh: true` in `AdGuardHome.yaml` to allow AdGuard Home respond to DoH requests without TLS encryption. +If you’re using TLS on your reverse proxy server, you don’t need to use TLS on AdGuard Home. Set `allow_unencrypted_doh: true` in `AdGuardHome.yaml` to allow AdGuard Home to respond to DoH requests without TLS encryption. ### Real IP addresses of clients -You can set the parameter `trusted_proxies` to the IP address(es) of your HTTP proxy to make AdGuard Home take the headers containing the real client IP address into account. See the [configuration][conf] and [encryption][encr] pages for more information. +You can set the parameter `trusted_proxies` to the IP address(es) of your HTTP proxy to make AdGuard Home consider the headers containing the real client IP address. See the [configuration][conf] and [encryption][encr] pages for more information. [encr]: https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption#reverse-proxy [conf]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration -## How to fix `permission denied` errors on Fedora? {#fedora} +## How do I fix `permission denied` errors on Fedora? {#fedora} 1. Move the `AdGuardHome` binary to `/usr/local/bin`. @@ -312,7 +312,7 @@ You can set the parameter `trusted_proxies` to the IP address(es) of your HTTP p firewall-cmd --reload ``` -If you are still getting `code=exited status=203/EXEC` or similar errors from `systemctl`, try uninstalling AdGuard Home and installing *directly* into `/usr/local/bin` by using the `-o` option of the install script: +If you are still getting `code=exited status=203/EXEC` or similar errors from `systemctl`, try uninstalling AdGuard Home and installing it *directly* into `/usr/local/bin` by using the `-o` option of the install script: ```sh curl -s -S -L 'https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh' | sh -s -- -o '/usr/local/bin' -v @@ -323,17 +323,17 @@ See [issue 765] and [issue 3281]. [issue 3281]: https://github.com/AdguardTeam/AdGuardHome/issues/3281 [issue 765]: https://github.com/AdguardTeam/AdGuardHome/issues/765#issuecomment-752262353 -## How to fix `incompatible file system` errors? {#incompatfs} +## How do I fix `incompatible file system` errors? {#incompatfs} You should move your AdGuard Home installation or working directory to another location. See the [limitations section](getting-started.md#limitations) on the *Getting Started* page. -## How to update AdGuard Home manually? {#manual-update} +## How do I update AdGuard Home manually? {#manual-update} -In case the button isn’t shown or an automatic update has failed, you can update manually. In the examples below, we’ll use AdGuard Home releases for Linux and Windows for AMD64 CPUs. +If the button isn’t displayed or an automatic update has failed, you can update manually. In the examples below, we’ll use AdGuard Home versions for Linux and Windows for AMD64 CPUs. ### Unix (Linux, macOS, BSD) {#manual-update-unix} -1. Download the new AdGuard Home package from the [releases page][releases]. If you want to perform this step from the command line: +1. Download the new AdGuard Home package from the [releases page][releases]. If you want to perform this step from the command line, type: ```sh curl -L -S -o '/tmp/AdGuardHome_linux_amd64.tar.gz' -s\ @@ -357,7 +357,7 @@ In case the button isn’t shown or an automatic update has failed, you can upda :::note OpenBSD - On OpenBSD you probably want to use `doas` instead of `sudo`. + On OpenBSD, you will probably want to use `doas` instead of `sudo`. ::: @@ -368,19 +368,19 @@ In case the button isn’t shown or an automatic update has failed, you can upda cp -r ./AdGuardHome.yaml ./data ~/my-agh-backup/ ``` -1. Unpack the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your `~/Downloads` directory and want to unpack it to `/tmp/`: +1. Extract the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your `~/Downloads` directory and want to extract it to `/tmp/`: ```sh tar -C /tmp/ -f ~/Downloads/AdGuardHome_linux_amd64.tar.gz -x -v -z ``` - On macOS, something like: + On macOS, type something like: ```sh unzip -d /tmp/ ~/Downloads/AdGuardHome_darwin_amd64.zip ``` -1. Replace the old AdGuard Home executable file with the new one. On most Unix systems the command would look something like: +1. Replace the old AdGuard Home executable file with the new one. On most Unix systems the command would look something like this: ```sh sudo cp /tmp/AdGuardHome/AdGuardHome /opt/AdGuardHome/AdGuardHome @@ -432,7 +432,7 @@ In all examples below, the PowerShell must be run as Administrator. Copy-Item -Path .\AdGuardHome.yaml, .\data -Destination $newDir -Recurse ``` -1. Unpack the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your `Downloads` directory and want to unpack it to a temporary directory: +1. Extract the AdGuard Home archive to a temporary directory. For example, if you downloaded the archive to your `Downloads` directory and want to extract it to a temporary directory: ```ps1 $outFile = Join-Path -Path $Env:USERPROFILE -ChildPath 'Downloads\AdGuardHome_windows_amd64.zip' @@ -456,19 +456,19 @@ In all examples below, the PowerShell must be run as Administrator. .\AdGuardHome.exe -s start ``` -## How to uninstall AdGuard Home? {#uninstall} +## How do I uninstall AdGuard Home? {#uninstall} -The way to uninstall AdGuard Home depends on how you installed it. +Depending on how you installed AdGuard Home, there are different ways to uninstall it. ::: caution -After uninstalling AdGuard Home, don’t forget to change your devices configuration and point them to a different DNS server. +After uninstalling AdGuard Home, don’t forget to change the configuration of your devices and point them to a different DNS server. ::: ### Regular installation -In this case you need to do the following: +In this case, do the following: - Unregister AdGuard Home service: `./AdGuardHome -s uninstall`. diff --git a/docs/adguard-home/getting-started.md b/docs/adguard-home/getting-started.md index dab990cd4..f50ae97b8 100644 --- a/docs/adguard-home/getting-started.md +++ b/docs/adguard-home/getting-started.md @@ -9,7 +9,7 @@ sidebar_position: 2 Download the archive with the binary file for your operating system from the [latest stable release page][releases]. The full list of supported platforms as well as links to beta and edge (unstable) releases can be found on [our platforms page][platforms]. -To install AdGuard Home as a service, unpack the archive, enter the `AdGuardHome` directory, and run: +To install AdGuard Home as a service, extract the archive, enter the `AdGuardHome` directory, and run: ```sh ./AdGuardHome -s install @@ -17,7 +17,7 @@ To install AdGuard Home as a service, unpack the archive, enter the `AdGuardHome #### Notes -- Users of **Fedora Linux** and its derivatives: install AdGuard Home into the `/usr/local/bin` directory. Otherwise, it may cause issues with SELinux and permissions. See [issue 765] and [issue 3281]. +- Users of **Fedora Linux** and its derivatives: install AdGuard Home in the `/usr/local/bin` directory. Failure to do so may cause issues with SELinux and permissions. See [issue 765] and [issue 3281]. - Users of **macOS 10.15 Catalina** and newer should place the AdGuard Home working directory inside the `/Applications` directory. @@ -29,13 +29,13 @@ We also provide an [official AdGuard Home docker image][docker] and an [official Some other unofficial options include: -- (Maintained by [@frenck](https://github.com/frenck)) [Home Assistant add-on][has]. +- [Home Assistant add-on][has] maintained by [@frenck](https://github.com/frenck). -- (Maintained by [@kongfl888](https://github.com/kongfl888)) [OpenWrt LUCI app][luci]. +- [OpenWrt LUCI app][luci] maintained by [@kongfl888](https://github.com/kongfl888). -- (Maintained by [@graysky2](https://github.com/graysky2)) [Arch Linux][arch], [Arch Linux ARM][archarm], and other Arch-based OSs, may build via the [`adguardhome` package][aghaur] in the [AUR][aur]. +- [Arch Linux][arch], [Arch Linux ARM][archarm], and other Arch-based OSs, may build via the [`adguardhome` package][aghaur] in the [AUR][aur] maintained by [@graysky2](https://github.com/graysky2). -- (Maintained by [@gramakri](https://github.com/gramakri)) [Cloudron app][cloudron]. +- [Cloudron app][cloudron] maintained by [@gramakri](https://github.com/gramakri). [aghaur]: https://aur.archlinux.org/packages/adguardhome/ [arch]: https://www.archlinux.org/ @@ -59,9 +59,9 @@ First of all, check your firewall settings. To install and use AdGuard Home, the - 80/TCP for the web interface; - 53/UDP for the DNS server. -You may need to open additional ports for protocols other than plain DNS, for example DNS-over-HTTPS. +You may need to open additional ports for protocols other than plain DNS, such as DNS-over-HTTPS. -DNS servers bind to port 53, which requires superuser privileges most of the time, [see below](#running-without-superuser). Therefore, on unix systems you need to run it with `sudo` or `doas` in terminal: +DNS servers bind to port 53, which requires superuser privileges most of the time, [see below](#running-without-superuser). Therefore, on Unix systems, you will need to run it with `sudo` or `doas` in terminal: ```sh sudo ./AdGuardHome @@ -110,7 +110,7 @@ By default, the logs are written to `stderr` when you run AdGuard Home in a term - On macOS, the log is written to `/var/log/AdGuardHome.*.log` files. -- On other unixes, the log is written to `syslog` or `journald`. +- On other Unixes, the log is written to `syslog` or `journald`. - On Windows, the log is written to the Windows event log. @@ -130,7 +130,7 @@ In case the button isn’t shown or an automatic update has failed, you can upda 1. Download the new AdGuard Home package. -1. Unpack it to a temporary directory. +1. Extract it to a temporary directory. 1. Replace the old AdGuard Home executable file with the new one. @@ -158,23 +158,23 @@ This setup will automatically cover all devices connected to your home router, a 1. Open the preferences for your router. Usually, you can access it from your browser via a URL, such as or . You may be prompted to enter a password. If you don’t remember it, you can often reset the password by pressing a button on the router itself, but be aware that if this procedure is chosen, you will probably lose the entire router configuration. If your router requires an app to set it up, please install the app on your phone or PC and use it to access the router’s settings. -1. Find the DHCP/DNS settings. Look for the DNS letters next to a field which allows two or three sets of numbers, each broken into four groups of one to three digits. +1. Find the DHCP/DNS settings. Look for the DNS letters next to a field that allows two or three sets of numbers, each divided into four groups of one to three digits. 1. Enter your AdGuard Home server addresses there. -1. On some router types, a custom DNS server cannot be set up. In that case, setting up AdGuard Home as a DHCP server may help. Otherwise, you should check the router manual on how to customize DNS servers on your specific router model. +1. On some router types, a custom DNS server cannot be set up. In that case, setting up AdGuard Home as a DHCP server may help. Otherwise, you should consult your router manual to learn how to customize DNS servers on your specific router model. ### Windows -1. Open *Control Panel* through Start menu or Windows search. +1. Open *Control Panel* from the Start menu or Windows search. -1. Go to *Network and Internet* category and then to *Network and Sharing Center.* +1. Go to *Network and Internet* and then to *Network and Sharing Center.* -1. On the left side of the screen find the *Change adapter settings* button and click it. +1. On the left side of the screen, find the *Change adapter settings* button and click it. 1. Select your active connection, right-click it and choose *Properties.* -1. Find *Internet Protocol Version 4 (TCP/IPv4)* (or, for IPv6, *Internet Protocol Version 6 (TCP/IPv6)*) in the list, select it and then click Properties again. +1. Find *Internet Protocol Version 4 (TCP/IPv4)* (or, for IPv6, *Internet Protocol Version 6 (TCP/IPv6)*) in the list, select it, and then click Properties again. 1. Choose *Use the following DNS server addresses* and enter your AdGuard Home server addresses. @@ -190,13 +190,13 @@ This setup will automatically cover all devices connected to your home router, a ### Android -1. From the Android Menu home screen, tap *Settings.* +1. From the Android menu home screen, tap *Settings.* -1. Tap *Wi-Fi* on the menu. The screen listing all of the available networks will be shown (it is impossible to set custom DNS for mobile connection). +1. Tap *Wi-Fi* on the menu. The screen with all of the available networks will be displayed (it is impossible to set custom DNS for mobile connection). 1. Long press the network you’re connected to and tap *Modify Network.* -1. On some devices, you may need to check the box for *Advanced* to see further settings. To adjust your Android DNS settings, you will need to switch the IP settings from *DHCP* to *Static.* +1. On some devices, you may need to check the box for *Advanced* to see more settings. To adjust your Android DNS settings, you will need to change the IP settings from *DHCP* to *Static.* 1. Change set DNS 1 and DNS 2 values to your AdGuard Home server addresses. @@ -204,21 +204,21 @@ This setup will automatically cover all devices connected to your home router, a 1. From the home screen, tap *Settings.* -1. Choose *Wi-Fi* in the left menu (it is impossible to configure DNS for mobile networks). +1. Select *Wi-Fi* from the left menu (it is impossible to configure DNS for mobile networks). 1. Tap the name of the currently active network. -1. In the *DNS* field enter your AdGuard Home server addresses. +1. In the *DNS* field, enter your AdGuard Home server addresses. ## Running without superuser (Linux only) {#running-without-superuser} -You can run AdGuard Home without superuser privileges, but you need to either grant the binary a capability (on Linux) or instruct it to use a different port (all platforms). +You can run AdGuard Home without superuser privileges, but you must either grant the binary a capability (on Linux) or instruct it to use a different port (all platforms). ### Granting the necessary capabilities Using this method requires the `setcap` utility. You may need to install it using your Linux distribution’s package manager. -To allow AdGuard Home running on Linux to listen on port 53 without superuser privileges and bind its DNS servers to a particular interface run: +To allow AdGuard Home running on Linux to listen on port 53 without superuser privileges and bind its DNS servers to a particular interface, run: ```sh sudo setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' ./AdGuardHome @@ -236,11 +236,11 @@ dns: port: 53 ``` -You can change the port 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. +You can change the port 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. ## Limitations {#limitations} -Some file systems don’t support the `mmap(2)` system call that the statistics system requires. See also [issue 1188]. +Some file systems don’t support the `mmap(2)` system call required by the statistics system. See also [issue 1188]. You can resolve this issue: diff --git a/docs/adguard-home/overview.md b/docs/adguard-home/overview.md index 8072b410c..98c3bc365 100644 --- a/docs/adguard-home/overview.md +++ b/docs/adguard-home/overview.md @@ -5,6 +5,6 @@ sidebar_position: 1 ## What is AdGuard Home? -AdGuard Home is a network-wide software for blocking ads and tracking. Unlike AdGuard Public DNS and AdGuard Private DNS, AdGuard Home is intended to be run on users’ own machines, which gives experienced users more control over their DNS traffic. +AdGuard Home is a network-wide software for blocking ads and tracking. Unlike AdGuard Public DNS and AdGuard Private DNS, AdGuard Home is designed to run on users’ own machines, which gives experienced users more control over their DNS traffic. [This guide](getting-started.md) should help you get started. diff --git a/docs/adguard-home/running-securely.md b/docs/adguard-home/running-securely.md index 66491fe4b..d5868edc4 100644 --- a/docs/adguard-home/running-securely.md +++ b/docs/adguard-home/running-securely.md @@ -7,7 +7,7 @@ This page contains a list of additional recommendations to help ensure the secur ## Choosing server addresses -The first time you start AdGuard Home, you will be asked which interface it should use to serve plain DNS. The most secure and practical option depends on how you want to run AdGuard Home. You can change the address(es) later, by stopping your AdGuard Home, editing the `dns.bind_hosts` field in the configuration file, and restarting AdGuard Home. +The first time you start AdGuard Home, you will be asked which interface it should use to serve plain DNS. The most secure and convenient option depends on how you want to run AdGuard Home. You can change the address(es) later, by stopping your AdGuard Home, editing the `dns.bind_hosts` field in the configuration file, and restarting AdGuard Home. ::: note @@ -15,7 +15,7 @@ The UI currently only allows you to select one interface, but you can actually s ::: -If you intend to run AdGuard Home on **your computer only,** select the loopback device (also known as “localhost”). It is usually named `localhost`, `lo`, or something similar and has the address `127.0.0.1`. +If you intend to run AdGuard Home on **your computer only,** select the loopback device (also known as “localhost”). It is usually called `localhost`, `lo`, or something similar and has the address `127.0.0.1`. If you plan to run AdGuard Home on a **router within a small isolated network,** select the locally-served interface. The names can vary, but they usually contain the words `wlan` or `wlp` and have an address starting with `192.168.`. You should probably also add the loopback address as well, if you want software on the router itself to use AdGuard Home too. @@ -43,7 +43,7 @@ If your AdGuard Home is not accessible from the outside, you can skip this secti ::: -If all clients using your AdGuard Home are able to use encrypted protocols, it is a good idea to disable plain DNS or make it unavailable from the outside. +If all clients using your AdGuard Home are able to use encrypted protocols, it is a good idea to disable plain DNS or make it inaccessible from the outside. If you want to completely disable plain DNS serving, you can do so on the *Settings → Encryption settings* page. @@ -61,13 +61,13 @@ The default plain-DNS ratelimit of 20 should generally be sufficient, but if you ## OS service concerns -In order to prevent privilege escalations through binary planting, it is important that the directory where AdGuard Home is installed to has proper ownership and privileges set. +In order to prevent privilege escalations through binary planting, it is important that the directory where AdGuard Home is installed to has proper ownership and permissions set. We thank Go Compile for assistance in writing this section. ### Unix (FreeBSD, Linux, macOS, OpenBSD) -AdGuard Home working directory, which is by default `/Applications/AdGuardHome` on macOS and `/opt/AdGuardHome` on other Unix systems, as well as the binary itself should generally have `root:root` ownership and not be writeable by anyone but `root`. You can check it with the following command, replacing `/opt/AdGuardHome` with your directory and `/opt/AdGuardHome/AdGuardHome` with your binary: +AdGuard Home working directory, which is by default `/Applications/AdGuardHome` on macOS and `/opt/AdGuardHome` on other Unix systems, as well as the binary itself should generally have `root:root` ownership and not be writeable by anyone but `root`. You can check this with the following command, replacing `/opt/AdGuardHome` with your directory and `/opt/AdGuardHome/AdGuardHome` with your binary: ```sh ls -d -l /opt/AdGuardHome @@ -81,7 +81,7 @@ drwxr-xr-x 4 root root 4096 Jan 1 12:00 /opt/AdGuardHome/ -rwxr-xr-x 1 root root 29409280 Jan 1 12:00 /opt/AdGuardHome/AdGuardHome ``` -Note the lack of write permission for anyone but `root` as well as owned by `root`. If any of these are not correct, run the following commands under `root`: +Note the lack of write permission for anyone but `root` as well as `root` ownership. If the permissions and/or ownership are not correct, run the following commands under `root`: ```sh chmod 755 /opt/AdGuardHome/ /opt/AdGuardHome/AdGuardHome From 1b5c3da9a23704122beb188376db20aa9bf68ed5 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Thu, 1 Feb 2024 19:40:35 +0300 Subject: [PATCH 4/5] Improve wording and formatting in AdGuard Home docs --- docs/adguard-home/faq.md | 28 +++++++++++++-------------- docs/adguard-home/getting-started.md | 21 +++++++++++++------- docs/adguard-home/running-securely.md | 12 ++++++------ 3 files changed, 34 insertions(+), 27 deletions(-) diff --git a/docs/adguard-home/faq.md b/docs/adguard-home/faq.md index 142d510dd..4fb86265e 100644 --- a/docs/adguard-home/faq.md +++ b/docs/adguard-home/faq.md @@ -30,17 +30,17 @@ Most likely, you haven’t configured your device to use AdGuard Home as the def If you are sure that your device is using AdGuard Home as its default DNS server, but the problem persists, it may be due to a misconfiguration of AdGuard Home. Please check and make sure that: -1. You have enabled the *Block domains using filters and hosts files* setting on the *Settings → General settings* page. +1. You have enabled the *Block domains using filters and hosts files* setting on the *Settings* → *General settings* page. -1. You have enabled the appropriate security mechanisms, such as Parental Control, on the *Settings → General settings* page. +1. You have enabled the appropriate security mechanisms, such as Parental Control, on the same page. -1. You have enabled the appropriate filters on the *Filters → DNS blocklists* page. +1. You have enabled the appropriate filters on the *Filters* → *DNS blocklists* page. -1. You don’t have any exception rule lists that may allow the requests enabled on the *Filters → DNS allowlists* page. +1. You don’t have any exception rule lists that may allow the requests enabled on the *Filters* → *DNS allowlists* page. -1. You don’t have any DNS rewrites that may interfere on the *Filters → DNS rewrites* page. +1. You don’t have any DNS rewrites that may interfere on the *Filters* → *DNS rewrites* page. -1. You don’t have any custom filtering rules that may interfere on the *Filters → Custom filtering rules* page. +1. You don’t have any custom filtering rules that may interfere on the *Filters* → *Custom filtering rules* page. ## Where can I view the logs? {#logs} @@ -143,7 +143,7 @@ There is currently no way to set these parameters from the UI, so you’ll need 1. Open the web UI. -1. Open the *Settings → DNS settings* page. +1. Navigate to *Settings* → *DNS settings.* 1. In the *DNS server configuration* section, select the *Custom IP* radio button in the *Blocking mode* selector and enter the IPv4 and IPv6 addresses of the server. @@ -181,13 +181,13 @@ Here are some examples of what cannot be blocked by a DNS-level blocker: - YouTube, Twitch ads. -- Facebook, Twitter, Instagram sponsored posts. +- Facebook, X (formerly Twitter), Instagram sponsored posts. -Basically, any ad that shares a domain with content cannot be blocked by a DNS-level blocker. +Basically, any ad that shares a domain with content cannot be blocked by a DNS-level blocker, unless you are ready to block the content as well. ### Any possibility of dealing with this in the future? -DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the [standalone AdGuard applications][adguard]. We’ll be adding support for this feature to AdGuard Home in the future. Unfortunately, even then there will still be cases there it won’t be enough or it will require quite complicated configuration. +DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the [standalone AdGuard applications][adguard]. We’ll be adding support for this feature to AdGuard Home in the future. Unfortunately, even then there will still be cases where it won’t be enough or it will require quite complicated configuration. [adguard]: https://adguard.com/ @@ -207,7 +207,7 @@ systemd-r 14542 systemd-resolve 13u IPv4 86178 0t0 UDP 127.0.0.53:domain systemd-r 14542 systemd-resolve 14u IPv4 86179 0t0 TCP 127.0.0.53:domain ``` -To fix this, you must either disable the `systemd-resolved` daemon or choose a different network interface and bind to an accessible IP address on it, such as the IP address of your router inside your network. But if you do need to listen on `localhost`, there are several solutions. +To fix this, you must either disable the `systemd-resolved` daemon or choose a different network interface and bind your AdGuard Home to an accessible IP address on it, such as the IP address of your router inside your network. But if you do need to listen on `localhost`, there are several solutions. Firstly, AdGuard Home can detect such configurations and disable `systemd-resolved` for you if you press the *Fix* button located next to the `address already in use` message on the installation screen. @@ -312,7 +312,7 @@ You can set the parameter `trusted_proxies` to the IP address(es) of your HTTP p firewall-cmd --reload ``` -If you are still getting `code=exited status=203/EXEC` or similar errors from `systemctl`, try uninstalling AdGuard Home and installing it *directly* into `/usr/local/bin` by using the `-o` option of the install script: +If you are still getting `code=exited status=203/EXEC` or similar errors from `systemctl`, try uninstalling AdGuard Home and installing it **directly** into `/usr/local/bin` by using the `-o` option of the install script: ```sh curl -s -S -L 'https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh' | sh -s -- -o '/usr/local/bin' -v @@ -460,9 +460,9 @@ In all examples below, the PowerShell must be run as Administrator. Depending on how you installed AdGuard Home, there are different ways to uninstall it. -::: caution +:::caution -After uninstalling AdGuard Home, don’t forget to change the configuration of your devices and point them to a different DNS server. +Before uninstalling AdGuard Home, don’t forget to change the configuration of your devices and point them to a different DNS server. ::: diff --git a/docs/adguard-home/getting-started.md b/docs/adguard-home/getting-started.md index f50ae97b8..0c8b90b31 100644 --- a/docs/adguard-home/getting-started.md +++ b/docs/adguard-home/getting-started.md @@ -80,9 +80,9 @@ go to http://[::1]:3000 There you will go through the initial configuration wizard. -![AdGuard Home network interface selection screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install2.jpg) +![AdGuard Home network interface selection screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install2.png) -![AdGuard Home user creation screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install3.jpg) +![AdGuard Home user creation screen](https://cdn.adtidy.org/content/kb/dns/adguard-home/install3.png) See [our article on running AdGuard Home securely](running-securely.md) for guidance on how to select the initial configuration that fits you best. @@ -120,7 +120,7 @@ You can change this behavior in the AdGuard Home [configuration file][conf]. ## Updating {#update} -![An example of an update notification](https://cdn.adtidy.org/content/kb/dns/adguard-home/updatenotification.jpg) +![An example of an update notification](https://cdn.adtidy.org/content/kb/dns/adguard-home/updatenotification.png) When a new version is released, AdGuard Home’s UI shows a notification message and the *Update now* button. Click this button, and AdGuard Home will be automatically updated to the latest version. Your current AdGuard Home executable file is saved inside the `backup` directory along with the current configuration file, so you can revert the changes, if necessary. @@ -174,7 +174,7 @@ This setup will automatically cover all devices connected to your home router, a 1. Select your active connection, right-click it and choose *Properties.* -1. Find *Internet Protocol Version 4 (TCP/IPv4)* (or, for IPv6, *Internet Protocol Version 6 (TCP/IPv6)*) in the list, select it, and then click Properties again. +1. Find *Internet Protocol Version 4 (TCP/IPv4)* (or, for IPv6, *Internet Protocol Version 6 (TCP/IPv6)*) in the list, select it, and then click *Properties* again. 1. Choose *Use the following DNS server addresses* and enter your AdGuard Home server addresses. @@ -190,6 +190,13 @@ This setup will automatically cover all devices connected to your home router, a ### Android +:::note + +Instructions for Android devices may differ depending on the OS version and the +manufacturer. + +::: + 1. From the Android menu home screen, tap *Settings.* 1. Tap *Wi-Fi* on the menu. The screen with all of the available networks will be displayed (it is impossible to set custom DNS for mobile connection). @@ -210,11 +217,11 @@ This setup will automatically cover all devices connected to your home router, a 1. In the *DNS* field, enter your AdGuard Home server addresses. -## Running without superuser (Linux only) {#running-without-superuser} +## Running without superuser {#running-without-superuser} You can run AdGuard Home without superuser privileges, but you must either grant the binary a capability (on Linux) or instruct it to use a different port (all platforms). -### Granting the necessary capabilities +### Granting the necessary capabilities (Linux only) Using this method requires the `setcap` utility. You may need to install it using your Linux distribution’s package manager. @@ -236,7 +243,7 @@ dns: port: 53 ``` -You can change the port 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. +You can change the port to anything above 1024 to avoid requiring superuser privileges. ## Limitations {#limitations} diff --git a/docs/adguard-home/running-securely.md b/docs/adguard-home/running-securely.md index d5868edc4..f827e3904 100644 --- a/docs/adguard-home/running-securely.md +++ b/docs/adguard-home/running-securely.md @@ -9,7 +9,7 @@ This page contains a list of additional recommendations to help ensure the secur The first time you start AdGuard Home, you will be asked which interface it should use to serve plain DNS. The most secure and convenient option depends on how you want to run AdGuard Home. You can change the address(es) later, by stopping your AdGuard Home, editing the `dns.bind_hosts` field in the configuration file, and restarting AdGuard Home. -::: note +:::note The UI currently only allows you to select one interface, but you can actually select multiple addresses through the configuration file. We will be improving the UI in future releases. @@ -23,13 +23,13 @@ If you intend to run AdGuard Home on a **publicly accessible server,** you’ll ## Access settings -::: note +:::note If your AdGuard Home is not accessible from the outside, you can skip this section. ::: -At the bottom of the *Settings → DNS settings* page you will find the *Access settings* section. These settings allow you to either ban clients that are known to abuse your AdGuard Home instance or to enable the Allowlist mode. The Allowlist mode is recommended for public instances where the number of clients is known and all of the clients are able to use secure DNS. +At the bottom of the *Settings* → *DNS settings* page you will find the *Access settings* section. These settings allow you to either ban clients that are known to abuse your AdGuard Home instance or to enable the Allowlist mode. The Allowlist mode is recommended for public instances where the number of clients is known and all of the clients are able to use secure DNS. To enable the Allowlist mode, enter [ClientIDs][cid] (recommended) or IP addresses for allowed clients in the *Allowed clients* field. @@ -37,7 +37,7 @@ To enable the Allowlist mode, enter [ClientIDs][cid] (recommended) or IP address ## Disabling plain DNS -::: note +:::note If your AdGuard Home is not accessible from the outside, you can skip this section. @@ -45,13 +45,13 @@ If your AdGuard Home is not accessible from the outside, you can skip this secti If all clients using your AdGuard Home are able to use encrypted protocols, it is a good idea to disable plain DNS or make it inaccessible from the outside. -If you want to completely disable plain DNS serving, you can do so on the *Settings → Encryption settings* page. +If you want to completely disable plain DNS serving, you can do so on the *Settings* → *Encryption settings* page. If you want to restrict plain DNS to internal use only, stop your AdGuard Home, edit the `dns.bind_hosts` field in the configuration file to contain only the loopback address(es), and restart AdGuard Home. ## Plain-DNS ratelimiting -::: note +:::note If your AdGuard Home is not accessible from the outside, you can skip this section. From d14a685d08ade0f04461b48771745a57c8c619d7 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Fri, 2 Feb 2024 15:55:17 +0300 Subject: [PATCH 5/5] Improve formatting in AdGuard Home docs --- docs/adguard-home/getting-started.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/adguard-home/getting-started.md b/docs/adguard-home/getting-started.md index 0c8b90b31..244c0b2ba 100644 --- a/docs/adguard-home/getting-started.md +++ b/docs/adguard-home/getting-started.md @@ -192,8 +192,7 @@ This setup will automatically cover all devices connected to your home router, a :::note -Instructions for Android devices may differ depending on the OS version and the -manufacturer. +Instructions for Android devices may differ depending on the OS version and the manufacturer. :::