AdGuard Home - Getting Started
In order to start using AdGuard Home, you need to do a few things:
- Running for the first time
- Running as a service
- How to update
- Configure your devices
- Running without superuser (linux only)
Download the archive with the binary file for your operating system from the latest stable release.
We currently officially support the following operating systems:
- Rapsberry Pi (32-bit ARM)
- Windows 64-bit
- Windows 32-bit
- Linux 64-bit
- Linux 32-bit
- FreeBSD 64-bit
- 64-bit ARM
AdGuard Home can work on other operating systems as well (for instance, it can work on devices with MIPS CPU), but we need your help with testing it.
Running for the first time
DNS works on port 53, which requires superuser privileges. Therefore, you need to run it with
sudo in terminal:
On Windows, you will need to run
cmd.exewith admin privileges and run
When you run AdGuard Home for the first time, it will start listening to
0.0.0.0:3000 and prompt you to open it in your browser:
AdGuard Home is available on the following addresses: Go to http://127.0.0.1:3000 Go to http://X.X.X.X:3000
There you will go through the initial configuration wizard.
Running as a service
The next step would be to register AdGuard Home as a system service on Windows, Linux/(systemd | Upstart | SysV), or OSX/Launchd.
sudo ./AdGuardHome -s install to install AdGuard Home as a system service.
On Windows run
cmd.exewith admin privileges and run
AdGuardHome.exe -s installto register a windows service.
Here are the other commands you might need to control the service.
AdGuardHome -s uninstall- uninstalls the AdGuard Home service.
AdGuardHome -s start- starts the service.
AdGuardHome -s stop- stops the service.
AdGuardHome -s restart- restarts the service.
AdGuardHome -s status- shows the current service status.
By default, the log is written to stderr when you run AdGuard Home as a console application.
If you run it as a service/daemon, the log output depends on the platform:
- Linux: the log is written to syslog.
- MacOS: the log is written to /var/log/AdGuardHome.*.log files.
- Windows: the log is written to the Windows event log.
You can redefine this behavior in the AdGuard Home configuration file.
How to update
When a new version is released, AdGuard Home's UI shows a notification message and 'Update Now' button. Simply click on this button and AdGuard Home will be automatically upgraded to the latest version. Your current AdGuard Home executable file is saved inside '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:
- Download the new AdGuard Home package.
- Unpack it to a temporary directory.
- Replace the old AdGuard Home executable file with the new one.
- Restart AdGuard Home.
Docker and Hass.io updates
Auto-updates for Docker and Hass.io are disabled.
How to configure your devices
This setup will automatically cover all the devices connected to your home router, and you will not need to configure each of them manually.
- Open the preferences for your router. Usually, you can access it from your browser via a URL (like http://192.168.0.1/ or http://192.168.1.1/). You may be asked to enter the password. If you don’t remember it, you can often reset the password by pressing a button on the router itself. Some routers require a specific application, which in that case should be already installed on your computer/phone.
- 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.
- Enter your AdGuard Home server addresses there.
- From the Android Menu home screen, tap ’Settings’
- Tap Wi-Fi on the menu. This will show a list of all of the available networks (it is impossible to set custom DNS for mobile connection)
- Long press the network you’re connected to, and tap ’Modify Network’
- 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.’
- Change ’DNS 1′ and ’DNS 2′ values to your AdGuard Home address.
- From the home screen, tap ’Settings’
- Choose ’Wi-Fi’ in the left menu (it is impossible to configure DNS for mobile networks)
- Tap on the name of the currently active network
- In the ’DNS’ field enter your AdGuard Home address
- Click on Apple icon and go to ’System Preferences.’
- Click on ’Network’
- Select the first connection in your list and click ’Advanced.’
- Select the ’DNS’ tab and add the address of your AdGuard Home.
- Open Control Panel through ’Start’ menu or Windows search.
- Go to ’Network and Internet’ category and then to ’Network and Sharing Center.’
- On the left side of the screen find ’Change adapter settings’ and click on it.
- Select your active connection, right-click on it and choose ’Properties.’
- Find ’Internet Protocol Version 4 (TCP/IP)’ in the list, select it and then click on ’Properties’ again.
- Choose ’Use the following DNS server addresses’ and enter your AdGuard Home address there.
Running without superuser (linux only)
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 CAP_NET_BIND_SERVICE capability (on Linux)
Note: 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, run:
sudo setcap CAP_NET_BIND_SERVICE=+eip ./AdGuardHome
./AdGuardHome as a unprivileged user.
Changing the DNS listen port
To configure AdGuard Home to listen on a port that does not require superuser privileges, edit
AdGuardHome.yaml and find these two lines:
dns: port: 53
You can change port 53 to anything above 1024 to avoid requiring superuser privileges.
If the file does not exist, create it in the same folder, type these two lines down and save.