From 0dc75c4ceb83d79afc1186797983fd64ebafa1f9 Mon Sep 17 00:00:00 2001
From: Ainar Garipov <a.garipov@adguard.com>
Date: Mon, 31 Jan 2022 18:15:43 +0300
Subject: [PATCH] Pull request: FAQ, Getting-Started: add manual upd, imp
Updates AdguardTeam/AdGuardHome#4208.
Squashed commit of the following:
commit c3051c927dfbefa957460fe76bcb9974176cde6a
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date: Mon Jan 31 16:46:42 2022 +0300
FAQ, Getting-Started: imp
commit 84848bbca306dc62220701d0297d582a4fd7d193
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date: Fri Jan 28 20:58:20 2022 +0300
FAQ, Getting-Started: add manual upd, imp
---
FAQ.md | 152 +++++++++++++++++++++++++++++++++++++++++++++
Getting-Started.md | 85 +++++++++++++------------
2 files changed, 198 insertions(+), 39 deletions(-)
diff --git a/FAQ.md b/FAQ.md
index c872f75..50804ac 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -11,6 +11,7 @@
* [How to configure a reverse proxy server for AdGuard Home?](#reverseproxy)
* [How to fix `permission denied` errors on Fedora?](#fedora)
* [How to fix `incompatible file system` errors?](#incompatfs)
+ * [How to update AdGuard Home manually?](#manual-update)
* [How to uninstall AdGuard Home?](#uninstall)
@@ -422,6 +423,157 @@ location. See the [limitations section](Getting-Started#limitations) on the
+## <a href="#manual-update" id="manual-update" name="manual-update">How to update AdGuard Home manually?</a>
+
+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.
+
+
+
+ ### <a href="#manual-update-unix" id="manual-update-unix" name="manual-update-unix">Unix (Linux, macOS, BSD)</a>
+
+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`.)
+
+
+
+ ### <a href="#manual-update-win" id="manual-update-win" name="manual-update-win">Windows (Using PowerShell)</a>
+
+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
+ ```
+
+
+
## <a href="#uninstall" id="uninstall" name="uninstall">How to uninstall AdGuard Home?</a>
The way to uninstall AdGuard Home depends on how you installed it.
diff --git a/Getting-Started.md b/Getting-Started.md
index e9accbd..181d134 100644
--- a/Getting-Started.md
+++ b/Getting-Started.md
@@ -1,12 +1,13 @@
# AdGuard Home - Getting Started
-1. [Installation](#installation)
-1. [First Start](#first-time)
-1. [Running As A Service](#service)
-1. [Updating](#update)
-1. [Configuring Devices](#configure-devices)
-1. [Running Without Superuser (Linux Only)](#running-without-superuser)
-1. [Limitations](#limitations)
+ * [Installation](#installation)
+ * [First Start](#first-time)
+ * [Running As A Service](#service)
+ * [Updating](#update)
+ * [Manual Update](#manual-update)
+ * [Configuring Devices](#configure-devices)
+ * [Running Without Superuser (Linux Only)](#running-without-superuser)
+ * [Limitations](#limitations)
@@ -20,7 +21,7 @@ We currently **officially** support the following operating systems:
* Linux:
**Fedora** and its derivatives: install AdGuard Home into the
- `/usr/local/bin` directory. Otherwise it may cause issues with SELinux and
+ `/usr/local/bin` directory. Otherwise, it may cause issues with SELinux and
permissions. See [issue 765] and [issue 3281].
* [AMD64](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz);
@@ -40,9 +41,9 @@ We currently **officially** support the following operating systems:
* [AMD64](https://static.adguard.com/adguardhome/release/AdGuardHome_windows_amd64.zip);
* [x86](https://static.adguard.com/adguardhome/release/AdGuardHome_windows_386.zip).
- * MacOS:
+ * macOS:
- **MacOS 10.15 Catalina** or newer: please note, that on MacOS Catalina it is
+ **macOS 10.15 Catalina** or newer: please note that on macOS Catalina it is
recommended to place AdGuard Home directory to the `/Applications`
directory.
@@ -67,8 +68,8 @@ Other official options:
* [AdGuard Home docker image][docker].
- * You can get AdGuard Home from the [Snap Store][snap] (an app store for
- Ubuntu and relates OSes).
+ * You can get AdGuard Home from the [Snap Store][snap], an app store for
+ Ubuntu and related OSes.
Other unofficial options:
@@ -107,18 +108,18 @@ the following ports and protocols must be available:
* 53/UDP for the DNS server.
You may need to open additional ports for protocols other than plain DNS, for
-example DNS-over-HTTP.
+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
+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` with admin privileges and run `AdGuardHome.exe` from
-there.
+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:
@@ -159,11 +160,10 @@ Here are the other commands you might need to control the service:
### Logs
-By default, the log is written to stderr when you run AdGuard Home as a console
-application. 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.
+ * On macOS, the log is written to `/var/log/AdGuardHome.*.log` files.
* On other unixes, the log is written to `syslog` or `journald`.
@@ -179,27 +179,34 @@ file](Configuration).
When a new version is released, AdGuard Home's UI shows a notification message
-and the “Update Now” button. Just click on this button, and AdGuard Home will
-be automatically upgraded to the latest version. Your current AdGuard Home
+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.
-In case the button isn't shown or an automatic update has failed, you can
-upgrade manually:
-1. Download the new AdGuard Home package.
-1. Unpack it to a temporary directory.
+ ### <a href="#manual-update" id="manual-update" name="manual-update">Manual Update</a>
-1. Replace the old AdGuard Home executable file with the new one.
+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. Restart AdGuard Home.
+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 And Hass.io Updates
+ ### Docker, Home Assistant, And Snapcraft Updates
-Auto-updates for Docker and Hass.io installations are disabled.
+Auto-updates for Docker, Hass.io / Home Assistant, and Snapcraft installations
+are disabled. Update the image instead.
@@ -238,13 +245,13 @@ and you won't need to configure each of them manually.
1. Go to Network and Internet category and then to Network and Sharing Center.
-1. On the left side of the screen find “Change adapter settings” and click on
- 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 on 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 on
+ 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
@@ -254,9 +261,9 @@ and you won't need to configure each of them manually.
### macOS
-1. Click on Apple icon and go to System Preferences.
+1. Click the Apple icon and go to System Preferences.
-1. Click on Network.
+1. Click Network.
1. Select the first connection in your list and click Advanced.
@@ -288,7 +295,7 @@ and you won't need to configure each of them manually.
1. Choose Wi-Fi in the left menu (it is impossible to configure DNS for mobile
networks).
-1. Tap on the name of the currently active network.
+1. Tap the name of the currently active network.
1. In the DNS field enter your AdGuard Home server addresses.
@@ -306,13 +313,13 @@ 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, as well as bind to a particular interface run:
+privileges and bind its DNS servers to a particular interface run:
```bash
sudo setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' ./AdGuardHome
```
-Then run `./AdGuardHome` as a unprivileged user.
+Then run `./AdGuardHome` as an unprivileged user.