AdGuard или программа, которую НЕ СЛЕДУЕТ устанавливать!
Я хочу поделиться с Вами своим опытом по установке одной программы, а именно — AdGuard.
Итак! Во-первых, начнём с того, что это за программа такая — AdGuard. AdGuard- это программа, которая ЯКОБЫ служит прекрасной защитой-блокиратором от всплывающих порно-баннеров. Во-вторых, при любой мысли о скачивании любого софта пользуйтесь умной поговоркой: «Не зная броду — не суйся в воду!» Ну, а теперь — конкретно о тех проблемах, с которыми столкнулся я при установке данной программы. К сожалению у меня на тот момент не хватило мозгов(почему — и сам не пойму!) зайти на форум, посвящённый этой программе и почитать отзывы. Короче говоря, я просто скачал программу и установил её.
Проблемы начались сразу же после запуска программы — моментально «зависла» система! Почесав свою не бритую «репу», я пожал плечами и перезагрузил компьютер. Система «висла» постоянно как только я запускал программу AdGuard. Вначале я думал, что виной всему несовместимость программного оборудования, вследствие чего и происходит конфликт систем. Однако, проанализировав все установленные программы, я пришёл к выводу, что причин для возникновения конфликта просто нет! А раз так, то «висяки» — это либо «косяк» разработчиков, либо наличие «трояна».
Проверив своё «железо» на предмет «трояна» я ничего не нашел. Это было тем более странно, потому что. Ну, об этой странности — чуть ниже. Перезапустив компьютер раз десять, я понял, что ловить с этой программой нечего — ещё чего доброго угроблю свой компьютер! Удалив эту странную (мягко говоря) программу, я решил, что надо бы проверить реестр. И проверил. А теперь — о странности. Обычный CCleaner обнаружил множество битых «цепей»: от DLL до шрифтов, файлов и всего прочего!
Проковырявшись пару часов с реестром и мысленно «благодаря» разработчиков чрезвычайно «нужной» программы AdGuard, я убедился в том, что прав был тот, кто сказал «Не зная броду- не суйся в воду!» В общем так, друзья! Качать или не качать, устанавливать или не устанавливать эту программу — дело сугубо Ваше! Моё же дело — Вас предупредить! Ведь не даром умные стратеги говорили: «Предупреждён — значит, вооружен!» Всего Вам доброго берегите себя и свой компьютер!
- Глобальный сбой системы или как сдвинуть компьютер с «мёртвой» точки
- Как повысить скорость работы компьютера
AdGuard Home
AdGuard Home (AGH) is a free and open source network-wide advertising and trackers blocking DNS server. It operates as a DNS server that re-routes tracking domains to a “black hole”, thus preventing your devices from connecting to those servers. It is based on software used with public AdGuard DNS servers.
In addition, AdGuard Home also offers DNS encryption features such as DNS over TLS ( DoT ) and DNS over HTTPS ( DoH ) built-in without any additional packages needed.
Prerequisites
Routers with low RAM, flash/storage space or slower processors will potentially not be suitable to run AdGuard Home. You may want to run AdGuard Home on another client instead if you have any of the mentioned system resource limitations with your router. The following requirements below are provided as general guidance.
Minimum of 50MB free RAM.
Minimum of 100MB free disk/flash space (see flash/storage requirements).
Higher performance routers i.e. dual-core with higher processor clock speeds are recommended.
The amount of RAM required will also be relative to the filter lists you use.
Routers with less than 128MB of RAM or only having a single core processor will tend to perform poorly. The homehub_v5a was used for testing the 0.107.0 edge and release builds.
An alternative option could be to use a Raspberry Pi Zero plugged into your routers USB port to run AGH. Using a Pi Zero for AGH.
DNS latency/performance
For the best performance and lowest latency on DNS requests, AGH should be your primary DNS resolver in your DNS chain. If you currently have dnsmasq or unbound installed, you should move these services to an alternative port and have AGH use DNS port 53 with upstream DNS resolvers of your choice configured. This wiki recommends keeping dnsmasq/unbound as your local/PTR resolver for Reverse DNS .
The rationale for this is due to resolvers like dnsmasq forking each DNS request when AGH is set as an upstream, this will have an impact on DNS latency which is can be viewed in the AGH dashboard. You will also not benefit from being able to see the DNS requests made by each client if AGH is not your primary DNS resolver as all traffic will appear from your router.
The install script in the setup section will move dnsmasq to port 54 and set it for AGH to use as local PTR / reverse DNS lookups.
Flash/storage space requirements
The compiled AdGuardHome binary has grown since the 0.107.0 release. For many routers this will be quite a significant amount of storage taken up in the overlay filesystem. In addition, features like statistics and query logging will also require further storage space when being written to the working directory. For routers with less flash space, it is highly recommended to use USB or an external storage path to avoid filling up your overlay filesystem. If you have low flash space, you may want to use the custom installation method and have all of the AdGuard Home installation stored outside of your flash storage. Alternatively you can also perform an exroot configuration.
Currently (May 2022 edge build 108) a full install to the /opt folder you really require about 100mb of space.
(70mb) 35mb x2 for the AGH binary and again for when it backups and upgrades. (that’s in the agh-backup folder)
20mb for my filters. (Again you can raise or lower this depending on what lists you use)
2mb — 90 days of statistics.
53mb — 7 days of query logs.
You can tweak your logging to keep things smaller if required.
Query/statistics logging
One of the main benefits of AGH is the detailed query and statistics data provided, however for many routers having long retention periods for this data can cause issues (see flash/storage space requirements). If you are using the default tmpfs storage, you should set a relatively short retention period or disable logging altogether. If you want to have longer retention periods for query/statistics data, consider moving the storage directory to outside your routers flash space.
Installation
Since 21.02, there is a official AdGuard Home package which can be installed through opkg.
The opkg package for 21.02 has also been confirmed to work on 19.07, but will require transferring the correct ipk through SSH or SCP and installing with opkg manually due to not being present in the 19.07 packages repository.
Required dependencies (ca-bundle) are automatically resolved and installed when using the official package.
opkg update opkg install adguardhome
The official OpenWrt package uses the following paths and directories by default:
The AdGuardHome application will be installed to /usr/bin/AdGuardHome .
The main adguardhome.yaml configuration file is stored at /etc/adguardhome.yaml .
The default working directory is /var/adguardhome (By default /var is a symlink to /tmp ).
The working directory can be configured in /etc/config/adguardhome
An init.d script is provided at /etc/init.d/adguardhome .
The default configured working directory will mean query logs and statistics will be lost on a reboot. To avoid this you should configure a persistent storage path such as /opt or /mnt with external storage and update the working directory accordingly.
To have AdGuard Home automatically start on boot and to start the service:
service adguardhome enable service adguardhome start
Setup
After installing the opkg package, run the following commands through SSH to prepare for making AGH the primary DNS resolver. These instructions assume you are using dnsmasq. This will demote dnsmasq to an internal DNS resolver only.
The ports chosen are either well known alternate ports or reasonable compromises. You are free to edit the scripts to use your own ports but you should check with https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers for reserved ports.
# Get the first IPv4 and IPv6 Address of router and store them in following variables for use during the script. NET_ADDR=$(/sbin/ip -o -4 addr list br-lan | awk 'NR==1< split($4, ip_addr, "/"); print ip_addr[1] >') NET_ADDR6=$(/sbin/ip -o -6 addr list br-lan scope global | awk 'NR==1< split($4, ip_addr, "/"); print ip_addr[1] >') echo "Router IPv4 : ""$ " echo "Router IPv6 : ""$ " # 1. Enable dnsmasq to do PTR requests. # 2. Reduce dnsmasq cache size as it will only provide PTR/rDNS info. # 3. Disable rebind protection. Filtered DNS service responses from blocked domains are 0.0.0.0 which causes dnsmasq to fill the system log with possible DNS-rebind attack detected messages. # 4. Move dnsmasq to port 54. # 5. Set Ipv4 DNS advertised by option 6 DHCP # 6. Set Ipv6 DNS advertised by DHCP uci set dhcp.@dnsmasq[0].noresolv="0" uci set dhcp.@dnsmasq[0].cachesize="1000" uci set dhcp.@dnsmasq[0].rebind_protection='0' uci set dhcp.@dnsmasq[0].port="54" uci -q delete dhcp.@dnsmasq[0].server uci add_list dhcp.@dnsmasq[0].server="$ " #Delete existing config ready to install new options. uci -q delete dhcp.lan.dhcp_option uci -q delete dhcp.lan.dns # DHCP option 6: which DNS (Domain Name Server) to include in the IP configuration for name resolution uci add_list dhcp.lan.dhcp_option='6,'"$ " #DHCP option 3: default router or last resort gateway for this interface uci add_list dhcp.lan.dhcp_option='3,'"$ " #Set IPv6 Announced DNS for OUTPUT in $(ip -o -6 addr list br-lan scope global | awk '< split($4, ip_addr, "/"); print ip_addr[1] >') do echo "Adding $OUTPUT to IPV6 DNS" uci add_list dhcp.lan.dns=$OUTPUT done uci commit dhcp /etc/init.d/dnsmasq restart
Setup AGH through the web interface
On first time setup the default web interface port is TCP 3000.
Go to http://192.168.1.1:3000/ (If your router IP is not 192.168.1.1, change this accordingly)
Setup the Admin Web Interface to listen on 192.168.1.1 at port 8080 . (Changing the web interface port is optional)
Set DNS server to listen on 192.168.1.1 at port 53 .
Create an user and choose a strong password.
Login AGH
http://192.168.1.1:8080/ (or whatever listening port you set)
Feel free to change upstream DNS servers to whatever you like (Adguard Home supports DoH , DoT and DoQ out of the box), add the blacklists of your preference and enjoy ad-free browsing on all of your devices.
Manual installation
For older builds, a custom installation or running the latest edge builds you can follow several well written guides by members of the community:
Configuration
Recommendations and best configuration practices for using AGH on OpenWrt.
Web interface
AdGuard Home has it’s own web interface for configuration and management and is not managed through LuCI. There is no official LuCI application for managing AdGuard Home. By default the web setup interface will be on port TCP 3000. To access the web interface, use the IP of your router: http://192.168.1.1:3000. If this is the first time you have installed AdGuard Home you will go through the setup process.
By default LuCI will be configured to use standard ports TCP 80/443, so AdGuard Home will need to use an alternative port for the web interface. You can use the default setup port TCP 3000 or change it to an alternative (8080 is the usual port 80 replacememt).
Once AGH is active then follow the official AdGuard Home wiki instructions to configure upstreams and filters. A list of known DNS providers and settings is here : Known DNS Providers
Note: Some settings may not be editable via the web interface and instead will need to be changed by editing the adguardhome.yaml configuration file.
Nginx Reverse proxy through LuCI
If you already use Nginx with LuCI rather than uHTTPd you can reverse proxy the AdGuard Home interface. This can simplify accessing the AdGuard Home interface and not having to worry about URLs with non standard HTTP ports. Using a reverse proxy also means you don’t have to specifically configure HTTPS access through AdGuard Home and can instead utilise the HTTPS configuration of LuCI instead.
The following example will allow accessing the AdGuard Home interface as a sub directory path /adguard-home. If your router IP or AdGuard Home http_port value is different, change it accordingly.
location /adguard-home/ < proxy_pass http://192.168.1.1:8080/; proxy_redirect / /adguard-home/; proxy_cookie_path / /adguard-home/; >
You can read more reverse proxy configurations from the Nginx docs.
Disable DoH encryption on AdGuard Home
If you have configured TLS on LuCI, there’s no need to use TLS on AdGuard Home. Set allow_unencrypted_doh to false in adguardhome.yaml to allow AdGuard Home respond to DoH requests without TLS encryption.
Reverse DNS (rDNS)
To enable rDNS so AGH picks up your DHCP assignments from OpenWrt.
From the AdGuard Home web interface Settings → DNS settings
Scroll to “Private reverse DNS servers”
Add 192.168.1.1:54
Tick both “Use private reverse DNS resolvers” and “Enable reverse resolving of clients’ IP addresses” boxes and click apply.
LAN domain interception
Adding the following to the Upstream DNS Server configuration will intercept any LAN domain request or requests without a FQDN and pass those requests to the appropriate resolver, which is mostly like your OpenWrt router but it doesn’t have to be.
The default LAN domain configured by OpenWrt is “lan”, but if you have configured you own domain, you can use this in the example code below:
(127.0.0.1) local loopback is used here to enable statistics tracking but you may also use your router ip (192.168.1.1) here too.
Settings → DNS Settings > Upstream Servers
[/lan/]127.0.0.1:54 [//]127.0.0.1:54
Creating ipset policies
For users using ipset policies for purposes such as VPN split tunnelling, AGH provides ipset functionality similar to dnsmasq. The configuration/syntax is slightly different and you will need to migrate any existing dnsmasq ipset policies to the AGH format and apply these to AGH instead.
An ipset policy is defined in the adguardhome.yaml file, there is currently no web interface available to add these policies, therefore you must add these to the yaml config manually.
If ipset is not already installed, install it:
opkg update opkg install ipset
Example dnsmasq syntax
Using the following example ipset rules in dnsmasq as a reference, the AGH equivalent is demonstrated.
ipset=/domain.com/ipset_name ipset=/domain1.com/domain2.com/ipset_name,ipset_name2
Example AGH syntax
dns: ipset: - domain.com/ipset_name - domain1.com,domain2.com/ipset_name,ipset_name2 .
The main syntax differences is each domain is separated using a comma ( , ) not a forward slash ( / ). A forward slash denotes the end of a domain rule with AGH. When specifying the ipset chain, a comma is used in both examples to denote multiple chains if required.
Like dnsmasq, an ipset policy in AGH can have one or more domains as well as be assigned to multiple ipset chains. Further information on ipset functionality can be found on the official AdGuard Home wiki under “other settings”.
Note: The ipset chains must exist before being used or referenced as AGH does not initialise them. It is possible to potentially encounter a race condition on startup if the ipset chains are not created in time when AGH attempts to start. An alternative is creating a custom init script that runs the ipset create command earlier than the START value of AGH.
AGH as a NextDNS client
AGH is recommended to be used with filtering disabled as a NextDNS client. Using AGH as a NextDNS Client
DNS Interception
Some devices will bypass DHCP provided DNS servers e.g. Google Chromecast.
In order to make sure all DNS traffic goes through your primary DNS resolver, you can enforce this through firewall rules.
Please note this ONLY enforces plain DNS enquiries from your LAN to be redirected through your DNS . To block DOH or other encrypted DNS requires further rules.
IPTables (firewall3)
Copy and paste these iptables rules in Network → Firewall → Custom Rules Tab or directly to /etc/firewall.user .
iptables -t nat -A PREROUTING -i br-lan -p tcp --dport 53 -j DNAT --to 192.168.1.1:53 iptables -t nat -A PREROUTING -i br-lan -p udp --dport 53 -j DNAT --to 192.168.1.1:53
You can also implement this via a fw3 rule within /etc/config/firewall :
config redirect 'adguardhome_dns_53' option src 'lan' option proto 'tcp udp' option src_dport '53' option target 'DNAT' option name 'Adguard Home' option dest 'lan' option dest_port '53'
These examples are for IPv4 DNS traffic only as they use DNAT.
NFT Tables (firewall4)
nft add rule nat pre udp dport 53 ip saddr 192.168.1.0/24 dnat 192.168.1.1:53
This will redirect all DNS traffic from 192.168.1.0/24 to the 192.168.1.1 server.
Bypassing encrypted DNS for NTP
In order for SSL to work the correct date/time MUST be set on the device. Not all routers have a Real Time Clock and thus must use NTP to update to the correct date/time on boot. As SSL will NOT work without the correct date/time you MUST bypass encrypted DNS to enable NTP updates to work.
Your router does NOT need encrypted DNS . Only your clients behind the router require filtering and encryption. Setting your router to use AGH as its DNS WILL result in failed NTP lookups unless you bypass encrypted lookups for NTP . This is NOT a recommended setup. Your router should have its own unencrypted upstream for NTP lookups.
When using a upstream DNS setup that utilises DNS encryption e.g. DoT or DoH , you may come across a race condition on startup where communication to such DNS resolvers is not possible because of the NTP service not being able to establish a connection to a network time source and the set the correct time on your router. Given encrypted DNS relies on TLS /certificates, having accurate time is more important. To prevent this, you can allow NTP DNS requests to use plain DNS , regardless of the upstream DNS resolvers set.
From the AdGuard Home web interface: Settings → DNS Settings → Upstream DNS Servers
Add the following to ensure any DNS request for NTP uses plain DNS . In this example, Cloudflare resolvers have been used. You can use any resolvers you like however.
[/pool.ntp.org/]1.1.1.1 [/pool.ntp.org/]1.0.0.1 [/pool.ntp.org/]2606:4700:4700::1111 [/pool.ntp.org/]2606:4700:4700::1001
Click apply to enable these specific DNS rules.
Debugging
If AdGuard Home won’t start, you will want to view error logs to understand why.
If using the opkg package you can view syslog for errors using logread .
logread -e AdGuardHome
You can also run AdGuardHome from command line and see the output directly.
AdGuardHome -v -c /etc/adguardhome.yaml -w /var/adguardhome --no-check-update
This example uses the defaults set in the init script with the extra addition of the verbose flag.
-v —verbose — Enables verbose output (useful for debugging).
-c —config — Path to the AdGuard Home YAML config.
-w —work-dir — Path to the set working directory where data such as logs and statistics are stored.
—no-check-update — Disables the built in update checker.
The most common reason for AdGuard Home not starting is due to syntax errors in the adguardhome.yaml config.
Uninstalling
This script uninstalls AGH and resets your router DNS to Google DNS . This is a known good default and should always work.
Note: If your router is not at 192.168.1.1 then replace the router IP address used in the commands below accordingly.
#!/bin/sh opkg update service adguardhome stop service adguardhome disable opkg remove adguardhome # 1. Reverts AdGuard Home configuration and resets settings to default. # 2. Enable rebind protection. # 3. Remove DHCP options for IPv4 and IPv6 uci -q delete dhcp.@dnsmasq[0].noresolv uci -q delete dhcp.@dnsmasq[0].cachesize uci set dhcp.@dnsmasq[0].rebind_protection='1' uci -q delete dhcp.@dnsmasq[0].server uci -q delete dhcp.@dnsmasq[0].port uci -q delete dhcp.lan.dhcp_option uci -q delete dhcp.lan.dns # Network Configuration # Disable peer/ISP DNS uci set network.wan.peerdns="0" uci set network.wan6.peerdns="0" # Configure DNS provider to Google DNS uci -q delete network.wan.dns uci add_list network.wan.dns="8.8.8.8" uci add_list network.wan.dns="8.8.4.4" # Configure IPv6 DNS provider to Google DNS uci -q delete network.wan6.dns uci add_list network.wan6.dns="2001:4860:4860::8888" uci add_list network.wan6.dns="2001:4860:4860::8844" # Save and apply uci commit dhcp uci commit network /etc/init.d/network restart /etc/init.d/dnsmasq restart /etc/init.d/odhcpd restart
Reconnect your clients to apply the changes.
Data Files
The AdGuardHome/data folder contains the following.
root@OpenWrt:/opt/AdGuardHome/data# ll -h drwxr-xr-x 3 root root 512 Oct 29 09:42 ./ drwxrwxrwx 4 root root 736 Oct 30 09:06 ../ drwxr-xr-x 2 root root 800 Nov 2 09:52 filters/ -rw-r--r-- 1 root root 45.4M Nov 2 20:42 querylog.json -rw-r--r-- 1 root root 8.9M Oct 29 09:00 querylog.json.1 -rw-r--r-- 1 root root 32.0K Oct 30 05:28 sessions.db -rw-r--r-- 1 root root 4.0M Nov 2 21:00 stats.db
querylog.json : These are your DNS queries. Can be removed.
sessions.db : active logins to AGH currently. This can be deleted but you will need to relog back in.
stats.db : Your statistics database. can purge but you will lose your statistics data.
The filters folder contains all your filter downloads. Purge if it is full but AGH will re-download your filters.
If your filters are too large for your diskspace you will have to disable large filters and restrict their usage.
The AdGuardHome/agh-backup folder contains the previous version of AGH. This also can be removed if space is at a premium.
References
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website. OK More information about cookies
- Last modified: 2022/07/01 13:56
- by mercygroundabyss
Self-registration in the wiki has been disabled.
If you want to contribute to the OpenWrt wiki, please post HERE in the forum or ask on IRC for access.
Except where otherwise noted, content on this wiki is licensed under the following license:
CC Attribution-Share Alike 4.0 International
Saved searches
Use saved searches to filter your results more quickly
Cancel Create saved search
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
Getting Started
Ainar Garipov edited this page Nov 16, 2022 · 32 revisions
Guides
- Getting Started
- FAQ
- How to write hosts blocklists
- Comparing AdGuard Home to other solutions
- Supported platforms
- Docker
- How to install and run AdGuard Home on a Raspberry Pi
- How to install and run AdGuard Home on a virtual private server
- Configuring AdGuard Home clients
- AdGuard Home as a DoH, DoT, or DoQ server
- AdGuard Home as a DNSCrypt server
- AdGuard Home as a DHCP server
Clone this wiki locally
AdGuard Home — Getting Started
- Installation
- First start
- Running as a service
- Updating
- Manual update
Installation
Official releases
Download the archive with the binary file for your operating system from the latest stable release page. The full list of supported platforms as well as links to beta and edge (unstable) releases can be found on our “Platforms” page.
To install AdGuard Home as a service, unpack the archive, enter the AdGuardHome directory, and run:
./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
Other
Some other unofficial options include:
- (Maintained by @frenck) Home Assistant add-on.
- (Maintained by @kongfl888) OpenWrt LUCI app.
- (Maintained by @graysky2) Arch Linux, Arch Linux ARM, and other Arch-based OSs, may build via the adguardhome package in the AUR.
- (Maintained by @gramakri) Cloudron app.
First start
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. Therefore, on unix systems you need to run it with sudo or doas in terminal:
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:
AdGuard Home is available on the following addresses: Go to http://127.0.0.1:3000 Go to http://X.X.X.X:3000There 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 (aka daemon). To install AdGuard Home as a service, run:
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.
Updating
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
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, but in short:
- 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, 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:
./AdGuardHome --update
Configuring 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.
- Open the preferences for your router. Usually, you can access it from your browser via a URL, such as http://192.168.0.1/ or http://192.168.1.1/. 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.
- 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.
- 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
- 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 the “Change adapter settings” button and click it.
- Select your active connection, right-click it and choose Properties.
- 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.
- Choose “Use the following DNS server addresses” and enter your AdGuard Home server addresses.
macOS
- Click the Apple icon and go to System Preferences.
- Click Network.
- Select the first connection in your list and click Advanced.
- Select the DNS tab and enter your AdGuard Home server addresses.
Android
- From the Android Menu home screen, tap Settings.
- 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).
- 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 set DNS 1 and DNS 2 values to your AdGuard Home server addresses.
iOS
- From the home screen, tap Settings.
- Choose Wi-Fi in the left menu (it is impossible to configure DNS for mobile networks).
- Tap the name of the currently active network.
- In the DNS field enter your AdGuard Home server addresses.
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 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:
sudo setcap 'CAP_NET_BIND_SERVICE=+eip CAP_NET_RAW=+eip' ./AdGuardHomeThen 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:
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
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):
ln -s $ /data/stats.db /tmp/stats.db ln -s $ /data/sessions.db /tmp/sessions.db
Saved searches
Use saved searches to filter your results more quickly
Cancel Create saved search
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
Network-wide ads & trackers blocking DNS server
License
AdguardTeam/AdGuardHome
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Switch branches/tags
Branches Tags
Could not load branches
Nothing to show
Could not load tags
Nothing to showName already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Cancel Create
- Local
- Codespaces
HTTPS GitHub CLI
Use Git or checkout with SVN using the web URL.
Work fast with our official CLI. Learn more about the CLI.Sign In Required
Please sign in to use Codespaces.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching Xcode
If nothing happens, download Xcode and try again.
Launching Visual Studio Code
Your codespace will open once ready.
There was a problem preparing your codespace, please try again.
Latest commit
62ec0d5 Oct 27, 2023
Updates #4977. Squashed commit of the following: commit da28c1b Author: Stanislav Chzhen Date: Fri Oct 27 17:24:38 2023 +0300 all: fix typo commit d6bca6b Author: Stanislav Chzhen Date: Fri Oct 27 14:44:20 2023 +0300 all: add todo commit 3087551 Author: Stanislav Chzhen Date: Wed Oct 25 20:00:17 2023 +0300 all: imp docs commit 04003c3 Author: Stanislav Chzhen Date: Wed Oct 25 16:59:14 2023 +0300 all: multiple domain specific upstreams
Git stats
Files
Failed to load latest commit information.
Latest commit message
Commit time
October 11, 2023 17:14
October 11, 2023 17:14
May 21, 2021 14:55
October 27, 2023 20:18
August 24, 2022 13:43
July 12, 2023 17:52
October 27, 2023 20:18
October 5, 2023 13:54
October 11, 2023 17:14
June 29, 2023 15:29
November 20, 2020 18:06
December 30, 2020 18:26
February 11, 2022 16:30
July 7, 2023 18:27
August 10, 2022 21:03
August 23, 2023 20:10
October 27, 2023 20:18
July 28, 2021 14:17
August 30, 2018 17:25
October 9, 2023 13:24
October 5, 2023 17:52
September 29, 2022 19:04
May 21, 2021 16:15
October 27, 2023 20:18
October 27, 2023 20:18
February 21, 2023 17:07
June 13, 2023 13:41
June 19, 2023 12:21README.md
Privacy protection center for you and your devices
Free and open source, powerful network-wide ads & trackers blocking DNS server.
AdGuard Home is a network-wide software for blocking ads and tracking. After you set it up, it’ll cover ALL your home devices, and you don’t need any client-side software for that.
It operates as a DNS server that re-routes tracking domains to a “black hole”, thus preventing your devices from connecting to those servers. It’s based on software we use for our public AdGuard DNS servers, and both share a lot of code.
- Getting Started
- Automated install (Linux/Unix/MacOS/FreeBSD/OpenBSD)
- Alternative methods
- Guides
- API
- How is this different from public AdGuard DNS servers?
- How does AdGuard Home compare to Pi-Hole
- How does AdGuard Home compare to traditional ad blockers
- Known limitations
- Prerequisites
- Building
- Test unstable versions
- Reporting issues
- Help with translations
- Other
Getting Started
Automated install (Linux/Unix/MacOS/FreeBSD/OpenBSD)
To install with curl run the following command:
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -vTo install with wget run the following command:
wget --no-verbose -O - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -vTo install with fetch run the following command:
fetch -o - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -vThe script also accepts some options:
- -c to use specified channel;
- -r to reinstall AdGuard Home;
- -u to uninstall AdGuard Home;
- -v for verbose output.
Note that options -r and -u are mutually exclusive.
Alternative methods
Manual installation
Please read the Getting Started article on our Wiki to learn how to install AdGuard Home manually, and how to configure your devices to use it.
Docker
You can use our official Docker image on Docker Hub.
Snap Store
If you’re running Linux, there’s a secure and easy way to install AdGuard Home: get it from the Snap Store.
Guides
API
If you want to integrate with AdGuard Home, you can use our REST API. Alternatively, you can use this python client, which is used to build the AdGuard Home Hass.io Add-on.
Comparing AdGuard Home to other solutions
How is this different from public AdGuard DNS servers?
Running your own AdGuard Home server allows you to do much more than using a public DNS server. It’s a completely different level. See for yourself:
- Choose what exactly the server blocks and permits.
- Monitor your network activity.
- Add your own custom filtering rules.
- Most importantly, it’s your own server, and you are the only one who’s in control.
How does AdGuard Home compare to Pi-Hole
At this point, AdGuard Home has a lot in common with Pi-Hole. Both block ads and trackers using the so-called “DNS sinkholing” method and both allow customizing what’s blocked.
We’re not going to stop here. DNS sinkholing is not a bad starting point, but this is just the beginning.
AdGuard Home provides a lot of features out-of-the-box with no need to install and configure additional software. We want it to be simple to the point when even casual users can set it up with minimal effort.
Disclaimer: some of the listed features can be added to Pi-Hole by installing additional software or by manually using SSH terminal and reconfiguring one of the utilities Pi-Hole consists of. However, in our opinion, this cannot be legitimately counted as a Pi-Hole’s feature.
Feature AdGuard Home Pi-Hole Blocking ads and trackers ✅ ✅ Customizing blocklists ✅ ✅ Built-in DHCP server ✅ ✅ HTTPS for the Admin interface ✅ Kind of, but you’ll need to manually configure lighttpd Encrypted DNS upstream servers (DNS-over-HTTPS, DNS-over-TLS, DNSCrypt) ✅ ❌ (requires additional software) Cross-platform ✅ ❌ (not natively, only via Docker) Running as a DNS-over-HTTPS or DNS-over-TLS server ✅ ❌ (requires additional software) Blocking phishing and malware domains ✅ ❌ (requires non-default blocklists) Parental control (blocking adult domains) ✅ ❌ Force Safe search on search engines ✅ ❌ Per-client (device) configuration ✅ ✅ Access settings (choose who can use AGH DNS) ✅ ❌ Running without root privileges ✅ ❌ How does AdGuard Home compare to traditional ad blockers
DNS sinkholing is capable of blocking a big percentage of ads, but it lacks the flexibility and the power of traditional ad blockers. You can get a good impression about the difference between these methods by reading this article, which compares AdGuard for Android (a traditional ad blocker) to hosts-level ad blockers (which are almost identical to DNS-based blockers in their capabilities). This level of protection is enough for some users.
Additionally, using a DNS-based blocker can help to block ads, tracking and analytics requests on other types of devices, such as SmartTVs, smart speakers or other kinds of IoT devices (on which you can’t install traditional ad blockers).
Known 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. Our 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 a complicated configuration.
How to build from source
Prerequisites
Run make init to prepare the development environment.
You will need this to build AdGuard Home:
- Go v1.20 or later;
- Node.js v16 or later;
- npm v8 or later;
- yarn v1.22.5 or later.
Building
Open your terminal and execute these commands:
git clone https://github.com/AdguardTeam/AdGuardHome cd AdGuardHome makeNOTE: The non-standard -j flag is currently not supported, so building with make -j 4 or setting your MAKEFLAGS to include, for example, -j 4 is likely to break the build. If you do have your MAKEFLAGS set to that, and you don’t want to change it, you can override it by running make -j 1 .
Check the Makefile to learn about other commands.
Building for a different platform
You can build AdGuard Home for any OS/ARCH that Go supports. In order to do this, specify GOOS and GOARCH environment variables as macros when running make .
env GOOS='linux' GOARCH='arm64' make
make GOOS='linux' GOARCH='arm64'
Preparing releases
You’ll need snapcraft to prepare a release build. Once installed, run the following command:
make build-release CHANNEL='. ' VERSION='. '
Docker image
Run make build-docker to build the Docker image locally (the one that we publish to DockerHub). Please note, that we’re using Docker Buildx to build our official image.
You may need to prepare before using these builds:
-
(Linux-only) Install Qemu:
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes --credential yes
docker buildx create --name buildx-builder --driver docker-container --use
Debugging the frontend
When you need to debug the frontend without recompiling the production version every time, for example to check how your labels would look on a form, you can run the frontend build a development environment.
-
In a separate terminal, run:
( cd ./client/ && env NODE_ENV='development' npm run watch )
Contributing
You are welcome to fork this repository, make your changes and submit a pull request. Please make sure you follow our code guidelines though.
Please note that we don’t expect people to contribute to both UI and backend parts of the program simultaneously. Ideally, the backend part is implemented first, i.e. configuration, API, and the functionality itself. The UI part can be implemented later in a different pull request by a different person.
Test unstable versions
There are two update channels that you can use:
- beta : beta versions of AdGuard Home. More or less stable versions, usually released every two weeks or more often.
- edge : the newest version of AdGuard Home from the development branch. New updates are pushed to this channel daily.
There are three options how you can install an unstable version:
- Snap Store: look for the beta and edge channels.
- Docker Hub: look for the beta and edge tags.
- Standalone builds. Use the automated installation script or look for the available builds on the Wiki. Script to install a beta version:
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c betaScript to install an edge version:
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c edgeReport issues
If you run into any problem or have a suggestion, head to this page and click on the “New issue” button. Please follow the instructions in the issue form carefully and don’t forget to start by searching for duplicates.
Help with translations
If you want to help with AdGuard Home translations, please learn more about translating AdGuard products in our Knowledge Base. You can contribute to the AdGuardHome project on CrowdIn.
Other
Another way you can contribute is by looking for issues marked as help wanted , asking if the issue is up for grabs, and sending a PR fixing the bug or implementing the feature.
Projects that use AdGuard Home
- AdGuard Home Remote: iOS app by Joost.
- Python library by @frenck.
- Home Assistant add-on by @frenck.
- OpenWrt LUCI app by @kongfl888 (originally by @rufengsuixing).
- Prometheus exporter for AdGuard Home by @ebrianne.
- Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance by @Lissy93
- AdGuard Home on GLInet routers by Gl-Inet.
- Cloudron app by @gramakri.
- Asuswrt-Merlin-AdGuardHome-Installer by @jumpsmm7 aka @SomeWhereOverTheRainBow.
- Node.js library by @Andrea055.
Acknowledgments
This software wouldn’t have been possible without:
- Go and its libraries:
- gcache
- miekg’s dns
- go-yaml
- service
- dnsproxy
- urlfilter
- And many more Node.js packages.
- React.js
- Tabler
You might have seen that CoreDNS was mentioned here before, but we’ve stopped using it in AdGuard Home.
For the full list of all Node.js packages in use, please take a look at client/package.json file.
Privacy
Our main idea is that you are the one, who should be in control of your data. So it is only natural, that AdGuard Home does not collect any usage statistics, and does not use any web services unless you configure it to do so. See also the full privacy policy with every bit that could in theory be sent by AdGuard Home is available.
About
Network-wide ads & trackers blocking DNS server