Asuswrt-Merlin AdGuardHome Installer
The official installer for running AdGuardHome on ARM-based ASUS routers with Asuswrt-Merlin firmware and Entware.
This project installs, updates, reconfigures, backs up, and removes AdGuardHome on supported Asuswrt-Merlin routers while keeping the router-side service scripts in place.
For a task-oriented operator guide, see the Github Wiki Pages.
The opt-in development candidate targets v2.7.0-rc.1; follow the candidate operator guide, release plan and shared .tasks/ ledger. The candidate checklist records current software qualification separately from physical acceptance and soak. No RC tag or release publication is implied.
Table of contents
Requirements
-
ARM-based ASUS router running Asuswrt-Merlin firmware.
-
Minimum supported firmware version: 384.11.
-
Entware installed on a separate USB drive. The same drive should be used for AdGuardHome storage.
-
Entware fully updated before installing. opkg is an Entware command, so run this only after Entware is mounted and available:
opkg update && opkg upgrade
-
JFFS custom scripts/configs enabled.
-
A swap file is strongly recommended. A minimum of 2 GB is recommended; AMTM can create up to 10 GB.
-
A router stronger than the RT-AC68U is recommended. AdGuardHome can run on an RT-AC68U, but capacity may be limited.
Command and path environment
The documentation separates commands and paths by when they are safe to use on an Asuswrt-Merlin router. Do not treat /opt as available during bootstrap; it belongs to Entware and only exists after Entware is mounted.
Stock-router bootstrap commands before Entware is available
Use BusyBox applets and router-stock binaries from /bin, /sbin, /usr/bin, and /usr/sbin. Install bootstrap examples in this README therefore use router-stock /usr/sbin/curl, router-stock /usr/sbin/wget, or PATH-safe curl/wget forms with the router stock PATH first. They intentionally avoid /opt/... paths.
For installation bootstrap commands, prefer this router-stock PATH ordering so stock firmware commands take priority over Entware commands:
export LC_ALL=C
export PATH="/sbin:/bin:/usr/sbin:/usr/bin:${PATH:-}"
Entware-required installer/runtime paths under /opt
Every documented command or path using /opt/... requires both of the following:
- Entware is installed, mounted, and available.
- AdGuardHome has already been installed or at least partially staged by this installer.
When Entware is mounted, /opt is the Entware root on the attached storage. Installer/runtime examples may then use Entware command directories such as /opt/sbin, /opt/bin, /opt/usr/sbin, and /opt/usr/bin, plus installer-managed configuration, service, state, and cache paths such as /opt/etc, /opt/etc/init.d, /opt/etc/AdGuardHome, /opt/var, /opt/var/run, and /opt/tmp. Keep router-stock paths first in PATH even after Entware is mounted so firmware tools from /bin, /sbin, /usr/bin, and /usr/sbin continue to win unless an Entware command is intentionally required.
These examples are for installed or partially installed systems only. They are not valid pre-Entware bootstrap commands.
Optional Entware dependencies
Optional features may require additional Entware packages. For example, the unused blocklist analyzer uses Entware python3, and SHA-256 verification fallback can use Entware coreutils-sha256sum when stock firmware does not provide a usable sha256sum. Install optional packages with opkg install ... only after Entware is available.
Known limitations
- Some double-NAT or dual-WAN environments may not be compatible because AdGuardHome takes over DNS service placement on port
53.
- The installer moves DNSMASQ to port
553 when AdGuardHome owns port 53.
- Managed takeover removes dnsmasq rebind/DNSSEC options and all runtime DNSSEC keys/anchors, including static included configuration. Persistent firmware preferences and custom sources remain available for native recovery. See dnsmasq takeover behavior and include limitations.
- v2.6.0 uses safer runtime defaults for new installs while preserving existing
.config values during upgrades.
- New installs and upgrades without a saved policy refuse to terminate unknown non-AdGuardHome owners of port
53 by default. Existing installs that keep ADGUARDHOME_REFUSE_UNKNOWN_DNS_PORT_KILL=0 retain legacy cleanup until migrated.
- New installs save
ADGUARD_NETCHECK_MODE=wan when router/local-cache DNS is selected, or ADGUARD_NETCHECK_MODE=lan for LAN-only service management. Existing installs keep their saved mode.
- New installs and legacy-compatible defaults use the full
aggressive runtime proc/sysctl profile. Users may explicitly select a reduced profile, accepting the router-specific functionality risk. If the runtime script is launched without an installer-managed .config, its fallback profile is also aggressive when optimization is explicitly enabled.
Features
- Installs AdGuardHome from official AdGuardHome binary packages.
- Supports ARM-based Asuswrt-Merlin routers.
- Can redirect LAN DNS queries to AdGuardHome when the Merlin DNS Filter option is selected.
- Supports updating AdGuardHome without reinstalling or reconfiguring from scratch.
- Includes installer, update, backup, reconfiguration, and uninstall flows.
- Provides service integration through Entware init scripts and Asuswrt-Merlin service events.
- Provides v2.6.0 diagnostics with
sh installer status and sh installer doctor.
- Provides v2.6.0 non-interactive commands for repeatable install, update, backup, restore, doctor, IPSET refresh, performance profile, and uninstall tasks.
- Uses safer netcheck, DNS port-owner cleanup, and runtime optimization defaults for new installs while retaining saved legacy values on upgrades.
- Can run an unused blocklist analyzer using menu option 9,
sh installer blocklists, or sh installer unusedblocklists to identify filter lists with zero query-log rule hits in the analyzed window.
Run the installer from an SSH shell on the router and follow the prompts. These bootstrap examples use router-stock download tools and do not use /opt/... paths.
Using router-stock curl:
/usr/sbin/curl -L -s -O https://raw.githubusercontent.com/jumpsmm7/Asuswrt-Merlin-AdGuardHome-Installer/master/installer && sh installer; rm installer
Using router-stock wget:
/usr/sbin/wget -O installer https://raw.githubusercontent.com/jumpsmm7/Asuswrt-Merlin-AdGuardHome-Installer/master/installer && sh installer; rm installer
PATH-safe form, if the router stock PATH is already first:
curl -L -s -O https://raw.githubusercontent.com/jumpsmm7/Asuswrt-Merlin-AdGuardHome-Installer/master/installer && sh installer; rm installer
The same installer entry point is used for initial installation, updates, reconfiguration, and uninstall actions.
Non-interactive commands
v2.6.0 adds command-line entry points for users who want repeatable actions without the interactive menu. Existing one-argument menu actions such as sh installer update, sh installer install, and sh installer backup still use the interactive compatibility path. Destructive non-interactive actions require --yes; install and uninstall actions that may rewrite DNS/NVRAM also require --allow-dns-nvram.
Flagged non-interactive install requires an existing configured AdGuardHome environment. --yes does not supply the timezone, credentials or DNS settings needed for fresh setup. For a fresh install, run sh installer or the interactive compatibility command sh installer install. A successful preflight does not mean unattended fresh setup is supported. Previously interrupted transaction recovery can still run before an unsupported request is rejected.
Examples. Commands that reference /opt/... require Entware and an installed AdGuardHome environment; the other sh installer ... commands can be run from the downloaded installer entry point on the router.
sh installer install --installer-branch master --adguardhome-branch release --yes --allow-dns-nvram
sh installer update --installer-branch master --adguardhome-branch release --yes
sh installer update --dry-run
sh installer backup --yes
sh installer restore --file /opt/etc/backup_AdGuardHome.tar.gz --yes
sh installer restore --file /opt/etc/backup_AdGuardHome.tar.gz --dry-run
sh installer preflight
sh installer preflight reconfigure
sh installer preflight status
sh installer doctor
sh installer doctor --fix
sh installer status
sh installer ipset status
sh installer ipset doctor
sh installer ipset refresh
sh installer ipset refresh --yes
sh installer ipset refresh --dry-run
sh installer netcheck --mode wan --hosts "google.com github.com snbforums.com" --dns 127.0.0.1 --require-http NO --timeout 300
sh installer dns-port-policy --policy refuse-unknown
sh installer performance --profile fast
sh installer migrate-runtime-defaults
sh installer migrate-runtime-defaults --dry-run
sh installer migrate-runtime-defaults --yes
sh installer uninstall --yes --allow-dns-nvram
sh installer uninstall --dry-run
--installer-branch selects the installer repository branch or tag used to fetch installer-managed artifacts. Source precedence is an explicit CLI or positional ref, the saved INSTALLER_BRANCH, then the reported default master. Argument-free menu launches retain the saved source. An unsafe or unavailable selected ref fails rather than silently switching to another source. A failed read of an existing configuration also stops source selection; an explicit ref does not require reading the saved source. Installer source selection is independent of the AdGuardHome binary channel.
--adguardhome-branch selects the AdGuardHome binary channel. Supported AdGuardHome branches are release, beta, and edge. The older --branch option is retained as an alias for --adguardhome-branch; use --installer-branch when you need to change the installer branch.
Use the global prefix sh installer --no-auto-update [installer-ref] [menu-action] to suppress automatic installer-component checks for one invocation. For example, sh installer --no-auto-update opens the menu with the installed bundle, and sh installer --no-auto-update status reports status. Non-interactive actions also accept --no-auto-update as a flag. It takes precedence over an explicit update request and survives menu relaunch/re-exec within that invocation; it is not saved as an update preference.
With this opt-out, install, update, restore and channel-switch flows that replace the installer/service/helper bundle refuse before beginning that operation, including their dry-run forms. Compatibility for an AdGuardHome-binary-only update with the existing bundle is not yet established. Other supported menu/configuration actions remain available with their normal safeguards and effects. The flag does not bypass artifact verification or change the AdGuardHome channel. Previously required transaction recovery remains separate.
The dry-run paths print what would be done and avoid changing the live install.
The preflight command checks router-stock command availability and action-specific prerequisites. Run sh installer preflight before a new install, or pass the flow you plan to run: install, reconfigure, update, restore, uninstall, or status. Its output uses preflight.name=value lines, includes preflight.safe_to_paste=yes, and is intended for issue reports. Preflight does not enable JFFS or install packages; existing interrupted-transaction recovery may precede it. JFFS output reports format state, scripts, effective enable key/value and a failure reason when applicable. Failed or invalid NVRAM reads cannot report readiness as OK; already-ready settings avoid an enablement transaction. A JFFS transaction failure identifies the lock, prior-recovery or snapshot stage instead of attributing it to a missing package.
The install/reconfigure/update/restore/uninstall flows check stock /bin/sh, /bin/nvram, a stock downloader (/usr/sbin/curl or /usr/sbin/wget), /sbin/service, and /usr/sbin/cru. Checks for /usr/sbin/iptables and /usr/sbin/ip6tables apply only when the action requires WAN firewall management; LAN-mode runs report those checks as SKIP. Install, reconfigure, update, and restore also require a jq executable that can successfully parse JSON. At the relevant action boundary the installer prefers the stock-first PATH result and otherwise installs the Entware fallback with opkg install jq-full --force-depends --force-overwrite --force-reinstall. Entware mount and Entware package/tool probes are reported only for flows that need Entware, while preflight status skips Entware-dependent checks. Password hashing can repair the Entware python3 and python3-bcrypt packages when Python hashing is unavailable, before trying its fallback provider; timezone selection can repair column. These are dependencies of their respective actions, rather than packages installed unconditionally at startup. Their absence does not establish the cause of a JFFS failure.
The ipset refresh command checks whether IPSET integration is enabled. Without --yes, it does not restart AdGuardHome; with --yes, it restarts AdGuardHome so refreshed mappings can take effect.
The migrate-runtime-defaults helper inspects /opt/etc/AdGuardHome/.config (requires Entware and an installed AdGuardHome environment), reports legacy v2.6.0 runtime values, and only writes safer defaults when --yes is provided. Use --dry-run to report the same planned changes without writing them.
The netcheck, dns-port-policy, performance, and migrate-runtime-defaults helpers only update installer configuration values. Restart AdGuardHome when you want the changed runtime behaviour to be loaded by the service scripts.
Service commands
Use the Entware init script directly. This /opt/... command requires Entware and an installed AdGuardHome environment:
/opt/etc/init.d/S99AdGuardHome {start|stop|restart|check|kill|reload}
Recommended Asuswrt-Merlin service commands:
service {start|stop|restart|kill|reload}_AdGuardHome
Status and doctor diagnostics
Use status for a short service summary:
sh installer status
The status output includes the AdGuardHome service state, monitor state, PID count, port 53 ownership, AdGuardHome version, installer version, selected branch, WebUI address and port, dnsmasq handoff state, the last startup result found in logs, and the last rollback result marker written by installer-managed install, update, restore, setup, or blocklist YAML replacement recovery paths.
Use doctor for a broader health check:
sh installer doctor
The doctor command prints simple status lines such as:
[OK] Entware /opt is mounted
[WARN] backup archive missing
[FAIL] DNS port 53 is not listening
Doctor checks include Entware mount state, AdGuardHome directories and symlinks, managed Asuswrt-Merlin hook scripts, Entware init scripts, AdGuardHome.yaml, .config, DNS port 53, dnsmasq handoff markers and locks, monitor and daemon process counts, WebUI port ownership, installer and AdGuardHome versions, backup archive safety, IPSET files, the last rollback result marker, and DNS-related NVRAM values.
Rollback result markers are stored under the installer-managed runtime/state path and are intentionally concise. A marker such as rollback complete, rollback partial, rollback failed, or rollback unavailable helps status, doctor, and failure messages explain whether the installer restored the previous state, could only partially restore it, or failed before a rollback target existed. After you have reviewed and corrected the reported condition, rerun sh installer status or sh installer doctor; if no further action is needed, the marker file can be removed from the installed router state path.
Safe repairs can be requested with:
sh installer doctor --fix
The --fix mode is intentionally limited. It can repair permissions, recreate the expected /opt/sbin/AdGuardHome symlink (requires Entware and an installed AdGuardHome environment), and remove stale handoff markers, stale pid files, and stale temporary files when they are not owned by an active process. It does not rewrite DNS, firewall, or NVRAM settings.
Runtime behavior settings
v2.6.0 exposes several runtime behaviours through environment or .config settings. New installs save safer defaults; upgrades preserve existing .config values. A missing DNS port-owner policy defaults to refuse-unknown; explicitly saved legacy policies remain available. Environment variables take precedence for the current invocation. Persistent settings can be placed in /opt/etc/AdGuardHome/.config (requires Entware and an installed AdGuardHome environment) using the same NAME="value" style already used by the installer.
To inspect an upgraded install for legacy runtime defaults without changing .config, run:
sh installer migrate-runtime-defaults
sh installer migrate-runtime-defaults --dry-run
To write the current DNS/netcheck defaults and fill a missing proc profile with the compatible aggressive default, run:
sh installer migrate-runtime-defaults --yes
The migration helper updates only legacy or missing runtime defaults. It does not downgrade an aggressive proc profile and preserves custom runtime choices such as ADGUARD_NETCHECK_MODE="lan", ADGUARD_PROC_OPTIMIZE="NO", or an explicitly selected balanced/safe process profile.
Netcheck modes
New installs save wan or lan mode based on the install-time local-cache/router-DNS choice. Upgrades keep the saved value; when no value exists, the installer pins legacy mode for compatibility:
ADGUARD_NETCHECK_MODE="legacy"
Legacy mode keeps the previous public-host checks against google.com, github.com, and snbforums.com, uses 127.0.0.1 for DNS lookups, waits up to 300 seconds for system time, and preserves the old DNS, ping, and HTTP probing flow.
Users can set the values directly in .config or use the non-interactive helper:
sh installer netcheck --mode wan --hosts "google.com github.com snbforums.com" --dns 127.0.0.1 --require-http NO --timeout 300
This writes values equivalent to:
ADGUARD_NETCHECK_MODE="wan"
ADGUARD_NETCHECK_HOSTS="google.com github.com snbforums.com"
ADGUARD_NETCHECK_DNS="127.0.0.1"
ADGUARD_NETCHECK_REQUIRE_HTTP="NO"
ADGUARD_NETCHECK_TIMEOUT="300"
In wan mode, netcheck succeeds when system time is ready and at least one configured host resolves or pings. HTTP probing is required only when ADGUARD_NETCHECK_REQUIRE_HTTP="YES".
For isolated LAN deployments or sites where public Internet reachability should not block local service management, run:
sh installer netcheck --mode lan
This writes:
ADGUARD_NETCHECK_MODE="lan"
LAN mode skips public WAN probes. The monitor still checks local AdGuardHome DNS responsiveness after the process is expected to be serving DNS.
LAN listener scope
LAN mode listens on 127.0.0.1, the current IPv4 address of the primary LAN
bridge (lan_ifname), and one stable global IPv6 address on that bridge when
present. It also binds IPv4 addresses only when they are both assigned to the
secondary br* interface and use an RFC 1918 prefix, because dnsmasq
advertises each private guest/SDN bridge’s own
address as its DNS server. VPN bridges qualify only when their assigned address
is RFC 1918; public and shared ranges such as 100.64.0.0/10 are not
selected automatically; this avoids exposing a resolver without an explicit
operator configuration. Discovery logs every selected secondary
interface/address pair.
Temporary, tentative, deprecated, duplicate, loopback, link-local, multicast,
and broadcast addresses are excluded from discovery. A stable global IPv6
address carrying mngtmpaddr remains eligible: that flag marks the template
used by the kernel to manage temporary privacy addresses and does not itself
make the template address temporary. IPv4 and IPv6 are selected independently, so IPv6 absence does not
change the IPv4 listener. AP, media bridge, and repeater installs follow the same
rule, and startup/monitor refreshes replace a renumbered primary address without
retaining the old address.
IPv6 discovery for secondary bridges is not needed because dnsmasq advertises
their IPv4 address. Listener binding and firewall policy remain independent.
LAN/AP/Bridge mode does not install firewall/IPTABLES rules; changing a bind address does
not imply that traffic is allowed or blocked on an interface. When a LAN, AP, or bridge install
still has active WAN-interface SNAT/MASQUERADE state, as in a double-NAT
topology, the installer retains its firewall-start lifecycle hook; otherwise
that hook is removed. This qualifying WAN NAT state is also the only LAN, AP, or
bridge topology in which IPSET integration can be enabled; without it, the
installer disables IPSET. Validate reachability and
firewall behavior separately for each router topology.
DNS port-owner cleanup policy
During startup, dnsmasq is stopped normally so AdGuardHome can own port 53. New installs and upgrades without a saved policy default to conservative handling:
ADGUARDHOME_REFUSE_UNKNOWN_DNS_PORT_KILL="1"
With refusal enabled, unknown non-dnsmasq owners of port 53 cause startup to abort instead of being terminated. The log message includes the PID, netstat owner, process name, and command when available.
Upgrades keep the saved value; when no value exists, the installer writes the refusal value 1. Explicitly saved legacy values remain available. To migrate an existing install, run:
sh installer dns-port-policy --policy refuse-unknown
This writes:
ADGUARDHOME_REFUSE_UNKNOWN_DNS_PORT_KILL="1"
If refusal is enabled and you still need to force termination for a specific startup, set:
ADGUARDHOME_FORCE_DNS_PORT_KILL="1"
ADGUARDHOME_FORCE_DNS_PORT_KILL=1 overrides the refusal setting for that invocation.
Managed main and SDN dnsmasq survivors are identified by their stock executable and configuration paths, including independent SDN PIDs. The firmware service commands cover all SDNs; installer escalation rechecks each managed PID before signaling it. After startup, every previously managed configuration must have a dnsmasq process exposing TCP and UDP DNS on port 553; DHCP script helpers are not treated as DNS listeners. Failure recovery verifies restored listeners on port 53. Unknown or unavailable identity remains subject to the selected refusal policy.
To restore the legacy cleanup policy, run:
sh installer dns-port-policy --policy legacy
This writes ADGUARDHOME_REFUSE_UNKNOWN_DNS_PORT_KILL="0".
AdGuardHome Local Cache
Menu option 6 saves whether AdGuardHome should serve the router’s own DNS requests (ADGUARD_LOCAL="YES" or "NO"). Enabling it no longer switches the resolver inside a dnsmasq configuration hook. The switch follows AdGuardHome DNS ownership, a successful loopback query, and main/enabled SDN dnsmasq readiness on port 553. During a handoff, failed startup, or shutdown, native resolver routing is restored.
The monitor retries deferred activation after dnsmasq restarts. The saved preference is read on each cache synchronization; menu changes also request an immediate readiness-checked application. Resolver changes are serialized, and activation waits until any manager start/stop operation completes. Native routing is restored before AdGuardHome receives stop or restart signals. A resolver bind failure keeps AdGuardHome running with native router DNS and logs the deferred cache state. Firmware whose resolver is already ROM-backed retains firmware-managed routing.
Runtime optimization profile
New installs and the legacy-compatible runtime fallback use the full aggressive proc/sysctl profile by default to preserve functionality across supported Asuswrt-Merlin routers:
ADGUARD_PROC_OPTIMIZE="YES"
ADGUARD_PROC_PROFILE="aggressive"
Upgrades keep an explicitly saved profile; when no value exists, the installer pins aggressive for compatibility. When no installer-managed .config is available, proc optimization remains disabled unless it is explicitly enabled, but the selected fallback profile is aggressive.
The supported profiles are:
| Profile |
Behaviour |
off |
Restore installer-owned proc values and do not apply tuning. |
safe |
Set rmem_max=4194304, wmem_max=1048576, and pid_max=4194304. The socket ceilings support bursty DNS traffic; the larger PID space reduces collisions with concurrent NVRAM and user scripts. |
balanced |
Apply safe and set nf_conntrack_tcp_timeout_max_retrans=240 so stalled TCP DNS connection state is released sooner. |
aggressive |
Apply balanced, the ICMP and neighbour-cache settings listed below, and the memory settings only while active swap is reported by /proc/swaps. |
The aggressive profile applies these additional values:
| Setting |
Value |
Condition and purpose |
vm.overcommit_memory |
2 |
Active swap only; keeps strict virtual-memory commitment. |
vm.swappiness |
60 |
Active swap only; enables normal swap reclaim under memory pressure. |
vm.overcommit_ratio |
50 |
Active swap only; retains a system-wide memory commitment reserve. |
net.ipv4.icmp_ratelimit |
0 |
Keeps IPv4 path and error feedback available during heavy upstream DNS traffic. |
net.ipv4.neigh.default.gc_thresh1/2/3 |
256/1024/2048 |
Avoids premature IPv4 neighbour-cache reclamation during large client bursts. |
net.ipv6.icmp.ratelimit |
0 |
Applied only when nvram get ipv6_service is non-empty; keeps IPv6 control feedback available. |
net.ipv6.neigh.default.gc_thresh1/2/3 |
256/1024/2048 |
Applied only when IPv6 is configured; avoids premature IPv6 neighbour-cache reclamation. |
Each target is allowlisted and its requested value is range-checked before writing. The installer saves the value it found before its first successful change and does not rewrite or log a setting that already has the requested value. Disable, profile changes, service stop, and uninstall restore a saved value only when the current proc value still matches the installer-applied value. A later administrator value that differs from the installer-applied value is therefore preserved; rewriting the same value cannot be detected. If swap or IPv6 becomes unavailable, settings that depend on it are restored using the same ownership check.
To disable runtime optimization completely, set:
ADGUARD_PROC_OPTIMIZE="NO"
Reducing the profile can omit PID, connection-state, memory-pressure, or network-cache protections needed by an individual router. Users choosing that risk can select a lower profile, for example:
ADGUARD_PROC_OPTIMIZE="YES"
ADGUARD_PROC_PROFILE="balanced"
The non-interactive performance helper maps user-facing profiles to runtime profiles:
sh installer performance --profile balanced
sh installer performance --profile low-memory
sh installer performance --profile fast
balanced writes ADGUARD_PROC_PROFILE="balanced", low-memory writes ADGUARD_PROC_PROFILE="safe", and fast writes ADGUARD_PROC_PROFILE="aggressive". Apply-time proc changes and successful restorations are logged once per actual change with old and new values. Missing, unreadable, or unwritable targets are logged as failures during application; startup does not fail only because a proc/sysctl operation fails.
Verify AdGuardHome is running
Check for the AdGuardHome process:
pidof AdGuardHome
If AdGuardHome is running, the command returns one or more process IDs.
You can also use the service check command. This /opt/... command requires Entware and an installed AdGuardHome environment:
/opt/etc/init.d/S99AdGuardHome check
Expected output when AdGuardHome is alive:
Checking AdGuardHome... alive.
AdGuardHome DNS examples
AdGuardHome supports many upstream DNS formats, including plain DNS, DNS-over-TLS, DNS-over-HTTPS, DNS-over-QUIC, DNSCrypt, and split DNS rules.
Examples:
94.140.14.140 - plain DNS over UDP.tls://dns-unfiltered.adguard.com - encrypted DNS-over-TLS.https://cloudflare-dns.com/dns-query - encrypted DNS-over-HTTPS.quic://dns-unfiltered.adguard.com:784 - experimental DNS-over-QUIC.tcp://1.1.1.1 - plain DNS over TCP.sdns://... - DNS stamp for DNSCrypt or DNS-over-HTTPS resolvers.[/example.local/]1.1.1.1 - route a specific domain suffix to a specific upstream.
More DNS provider references:
Unused blocklist analyzer
Run the analyzer from installer menu option 9, or call it directly with sh installer blocklists or sh installer unusedblocklists. The installer can download and run a fork of blocklilst_analyzer.py maintained by @jumpsmm7. The AdGuard Home Blocklist Usage Analyzer was originally written by @graysky2, whose original gist remains credited here. The analyzer inspects AdGuardHome data under ${TARG_DIR}/data, the filter cache under ${TARG_DIR}/data/filters, and the AdGuardHome query log to report which filter lists had matching blocking-rule hits during the analyzed log window.
In this report, unused means the blocklist had zero Result.Rules[].FilterListID hits in the query log entries that were analyzed. It does not mean the list is globally useless, redundant for every network, or safe to remove in all future traffic patterns. Review the printed list carefully before confirming any removal because removing filter lists can change blocking behavior.
When removal is confirmed, the installer backs up ${TARG_DIR}/AdGuardHome.yaml, removes matching unused filter entries by id:, validates the resulting YAML with AdGuardHome’s configuration checker, and restores the backup if validation fails. This restore path is intended to keep AdGuardHome from being left with an invalid configuration after an interrupted or failed cleanup.
Removal can be handled in two ways after the unused list report is printed. The ALL option removes every listed unused filter in one pass after a single confirmation, which is faster but should be used only after reviewing the full printed list. The one by one option prompts for each unused filter individually so you can keep specific lists even if they were unused during the analyzed window. Both paths remove filters by their AdGuardHome id: entries and use the same backup, validation, and restore safety checks before the changed configuration is kept.
Python 3 is required to run the analyzer. On Entware-based installs, install it before using the analyzer if the installer has not already installed it for you:
opkg install python3 coreutils-sha256sum --force-depends --force-overwrite --force-reinstall
For SHA-256 verification support on firmware builds that do not include stock sha256sum, install the optional Entware package:
opkg install coreutils-sha256sum --force-depends --force-overwrite --force-reinstall
python3 and coreutils-sha256sum are optional Entware dependencies, not stock Asuswrt-Merlin router commands. The analyzer itself is optional; users who do not want Entware Python 3 installed can skip this feature and manage filter lists manually from the AdGuardHome web interface.
IPSET integration
The installer can integrate AdGuardHome with IPSET-based routing and firewall add-ons by configuring AdGuardHome’s dns.ipset_file setting. When AdGuardHome resolves a matching domain, it adds returned IPv4 or IPv6 addresses to the named IPSET so the add-on that owns that set can apply its routing or firewall policy. The integration can be enabled or disabled from installer menu option 8; existing installations without an ADGUARD_IPSET setting remain enabled for backward compatibility.
Requirements and ownership
- IPSET integration is optional. If installer-managed mappings cannot be prepared, the installer removes the managed
dns.ipset_file reference before allowing AdGuardHome to start without IPSET integration. Startup is aborted only when that reference cannot be safely removed, preventing stale routing or firewall mappings from remaining active.
- IPSET integration is available only on Linux. AdGuardHome added
dns.ipset_file in v0.107.13; this integration requires v0.107.48 or later because the generated file contains supported comment lines.
- The routing or firewall add-on remains responsible for creating, restoring, flushing, and deleting its IPSETs and for installing any rules that use them. The AdGuardHome installer only supplies domain-to-IPSET mappings and does not create IPSETs or policy-routing/firewall rules.
- A target set must already exist when AdGuardHome tries to add an address. IPv4 answers require a set with the
ipv4 family, and IPv6 answers require a set with the ipv6 family.
- Domain VPN Routing, x3mRouting, WireGuard Manager, Skynet/IPSet_ASUS, or another add-on should be installed and configured according to that project’s instructions before its set names are referenced here.
See the upstream AdGuardHome configuration documentation for the authoritative dns.ipset and dns.ipset_file behavior.
Managed files and YAML
The integration uses the following files. Every /opt/... path in this table requires Entware and an installed AdGuardHome environment:
| Path |
Owner |
Purpose |
/opt/etc/AdGuardHome/AdGuardHome.yaml |
AdGuardHome and this installer |
The installer sets dns.ipset: [] and points dns.ipset_file to the generated file. |
/opt/etc/AdGuardHome/ipset.conf |
This installer |
Generated AdGuardHome rule file. It is rebuilt atomically and must not be edited manually. |
/opt/etc/AdGuardHome/ipset.user |
User |
Persistent custom and migrated rules. Add manual rules here. |
/opt/var/run/AdGuardHome-ipset/flock |
Locking code |
Runtime lock file used when file-descriptor flock is supported. |
/opt/var/run/AdGuardHome-ipset/mkdir/ |
Locking code |
Runtime legacy lock directory used when flock is unavailable. |
The resulting YAML contains entries equivalent to the following. The /opt/... value requires Entware and an installed AdGuardHome environment:
dns:
ipset: []
ipset_file: /opt/etc/AdGuardHome/ipset.conf
AdGuardHome ignores inline dns.ipset rules when dns.ipset_file is configured, so migrated custom rules are kept in ipset.user and merged into ipset.conf. The generated file may be replaced during startup, dnsmasq configuration, or firewall events; manual changes to ipset.conf will be lost. If a refresh finds no user or dnsmasq mappings, the installer removes the empty generated file and the managed dns.ipset_file setting instead of preventing AdGuardHome from starting. If setup fails, the installer removes the managed dns.ipset_file reference and allows AdGuardHome to start without IPSET integration. If the reference cannot be safely removed, startup is aborted rather than retaining stale mappings. Refresh failures are logged and leave the existing running configuration unchanged until a later successful refresh.
Both IPSET files are inside /opt/etc/AdGuardHome, which requires Entware and an installed AdGuardHome environment, so the installer’s normal backup and restore flow includes them. Uninstalling the installer removes them with the rest of that directory.
Rule syntax and examples
Write one AdGuardHome IPSET rule per line in ipset.user using this format. The ipset.user file lives under /opt/etc/AdGuardHome and requires Entware and an installed AdGuardHome environment:
DOMAIN[,DOMAIN,...]/IPSET_NAME[,IPSET_NAME,...]
Examples:
example.com/ROUTE_VPN
example.net,example.org/ROUTE_WG
streaming.example/ROUTE_VPN,TRACK_STREAMING
The first example adds answers for example.com to ROUTE_VPN. The second associates multiple domains with one set. The third associates one domain with multiple sets.
Rules in ipset.user are already in AdGuardHome format: do not add the dnsmasq ipset= prefix or surround domains with leading and trailing slashes. Empty lines are discarded. Exact duplicate lines are written only once. Lines beginning with # may be used for comments. AdGuardHome supports comments in ipset_file starting with v0.107.48.
A compatible dnsmasq directive such as:
ipset=/example.com/example.net/ROUTE_VPN
is converted to:
example.com,example.net/ROUTE_VPN
Imported compatibility sources
Each refresh scans active, non-commented dnsmasq ipset= directives from the configuration passed by the current dnsmasq hook and from these locations when they exist:
/etc/dnsmasq.conf
/etc/dnsmasq-<index>.conf
/jffs/configs/dnsmasq.conf.add
/jffs/configs/dnsmasq.d/*.conf
/jffs/addons/x3mRouting/*.conf
/jffs/configs/domain_vpn_routing/*.conf
/jffs/addons/wireguard/*.conf
Guest Network Pro/SDN post-configuration also passes the matching /etc/dnsmasq-<index>.conf file to the refresh. Every refresh scans all existing numeric-index SDN dnsmasq configurations as well, so overlapping post-configuration callbacks retain mappings from the other active SDNs. These sources cover dnsmasq directives produced by the supported routing integrations; any compatible directive present in the scanned files is imported regardless of which add-on wrote it.
The installer-managed /jffs/scripts/dnsmasq-sdn.postconf hook is a supported part of this SDN integration when rc_support advertises mtlancfg. That capability gates adding or retaining the managed hook entry. The installer removes its stale managed entry even when mtlancfg is no longer advertised, while preserving unrelated commands in the shared script.
The collector imports mappings only. It does not execute another add-on, copy its firewall rules, infer missing set names, or create the target IPSET. Files outside the listed locations are not scanned automatically; copy persistent custom mappings into ipset.user instead.
Migration and refresh behavior
On each setup run, the installer checks whether it already owns the YAML IPSET configuration:
- If
dns.ipset_file is empty or points to /opt/etc/AdGuardHome/ipset.conf (requires Entware and an installed AdGuardHome environment), supported inline dns.ipset entries are merged into ipset.user, exact duplicates and empty lines are removed, and the YAML is normalized to the managed settings shown above. Existing ipset.user rules are preserved.
- If
dns.ipset_file points anywhere else, the installer leaves the YAML and external file untouched, skips its managed IPSET migration and refresh for that run, and allows AdGuardHome to use the existing configuration. To opt in to managed integration, copy persistent mappings from the external file into ipset.user, clear dns.ipset_file while AdGuardHome is stopped, and restart AdGuardHome.
- If no mappings are available after migration and collection, the installer removes its managed
dns.ipset_file setting and starts AdGuardHome normally. The setting is restored automatically when integration is enabled and a later refresh discovers mappings.
- If IPSET integration is disabled from installer menu option 8, startup removes only the installer-managed
dns.ipset_file setting. ipset.user is retained so custom mappings are available if the feature is re-enabled.
The installer never reads or imports a YAML-selected external file with elevated privileges. Once managed integration is active, it generates ipset.conf from ipset.user plus all detected compatible dnsmasq directives.
Refreshes occur at these points:
- before AdGuardHome starts or restarts;
- after the standard dnsmasq post-configuration hook runs;
- after a Guest Network Pro/SDN dnsmasq post-configuration hook runs;
- when Asuswrt-Merlin invokes
/jffs/scripts/firewall-start.
To apply changes after editing ipset.user, restart AdGuardHome so the generated file is refreshed before AdGuardHome reloads its configuration:
service restart_AdGuardHome
To regenerate ipset.conf manually, run:
/jffs/addons/AdGuardHome.d/AdGuardHome.sh firewall
A refresh writes a temporary file, removes empty and exact duplicate lines, and replaces ipset.conf only when its content changed. If AdGuardHome is running and the generated file changes, the command restarts AdGuardHome so the updated IPSET rules take effect; unchanged output does not trigger a restart.
Locking and recovery
Concurrent setup and refresh events are serialized to prevent multiple writers from replacing the YAML or generated rule file at the same time:
- Firmware with working file-descriptor locking waits on
flock for /opt/var/run/AdGuardHome-ipset/flock (requires Entware and an installed AdGuardHome environment), so a concurrent invocation runs after the active writer finishes.
- Older firmware falls back to
/opt/var/run/AdGuardHome-ipset/mkdir/ (requires Entware and an installed AdGuardHome environment), records the owner PID, waits up to 30 seconds, and removes a stale lock when its owner no longer exists.
- Both lock paths save the caller’s current traps, install temporary cleanup traps for
EXIT, HUP, INT, QUIT, ABRT, TERM, and TSTP, and restore the previous trap environment before returning. This prevents IPSET cleanup from replacing the manager’s monitor or exit handlers.
Do not remove an active lock. If a legacy lock remains after an abnormal termination and its recorded process is no longer running, the next refresh removes it automatically.
Verify and troubleshoot IPSET integration
For a read-only summary, run either of these equivalent diagnostics from the downloaded installer entry point:
sh installer ipset status
sh installer ipset doctor
The IPSET status/doctor report does not create, flush, or delete IPSETs. It reports whether installer-managed IPSET integration is enabled, whether AdGuardHome.yaml points dns.ipset_file at the managed ipset.conf, whether ipset.user and generated ipset.conf exist, and whether each referenced set name currently exists according to the router-stock ipset command. For existing sets, it reports IPv4 and IPv6 family checks separately: inet sets are suitable for IPv4 answers but are likely to reject IPv6 answers, and inet6 sets are suitable for IPv6 answers but are likely to reject IPv4 answers. Unknown families are reported without guessing. The set probe uses the router-stock ipset tool; if that command is unavailable, the diagnostic skips set existence and family checks without modifying router state.
Confirm that the YAML points to the managed file. This /opt/... command requires Entware and an installed AdGuardHome environment:
grep -A 2 '^ ipset:' /opt/etc/AdGuardHome/AdGuardHome.yaml
Review persistent and generated rules. These /opt/... commands require Entware and an installed AdGuardHome environment:
cat /opt/etc/AdGuardHome/ipset.user
cat /opt/etc/AdGuardHome/ipset.conf
Confirm that the target sets exist before testing DNS answers:
ipset list -n
ipset list ROUTE_VPN
After querying a mapped domain through AdGuardHome, inspect the owning set again. If no address appears:
-
Confirm that the domain mapping is present in ipset.conf and uses AdGuardHome syntax.
-
Confirm that the target set exists and has the correct IPv4 or IPv6 family.
-
Restart AdGuardHome after changing ipset.user or the YAML.
-
Confirm that the query was answered by this AdGuardHome instance and was not served exclusively by another resolver.
-
Check system logging for refresh or lock errors:
logread | grep -iE 'AdGuardHome|IPSET'
-
Run AdGuardHome’s configuration validation. This /opt/... command requires Entware and an installed AdGuardHome environment:
/opt/sbin/AdGuardHome --check-config -c /opt/etc/AdGuardHome/AdGuardHome.yaml --no-check-update -l /dev/null
When reporting a problem, include AdGuardHome.yaml, ipset.user, ipset.conf, the relevant dnsmasq/add-on configuration, ipset list output for the referenced sets, and the installer diagnostic archive described below. Remove private domains or addresses before publishing logs or configuration files.
Reverse DNS notes
The installer configures reverse DNS integration automatically. The notes below are included for users who want to understand or review the router-side configuration.
In the Asuswrt-Merlin LAN DHCP page, define a local domain such as lan or another local-only domain.
Then review the matching rules in AdGuardHome under Private Reverse DNS Servers.
Troubleshooting and issue reports
For AdGuardHome application issues that are not installer-specific, use the upstream AdGuardHome issue tracker:
For installer issues, include the following information:
- DNS server selected during installation.
- Router model.
- Asuswrt-Merlin firmware version.
- A tar archive containing the relevant installer, service, and configuration paths listed below.
Relevant paths. The /opt/... entries require Entware and an installed AdGuardHome environment; the /jffs/... entries are router JFFS paths:
/opt/etc/AdGuardHome
/opt/sbin/AdGuardHome
/opt/etc/init.d/S99AdGuardHome
/opt/etc/init.d/rc.func.AdGuardHome
/jffs/addons/AdGuardHome.d
/jffs/scripts/init-start
/jffs/scripts/dnsmasq.postconf
/jffs/scripts/firewall-start
/jffs/scripts/services-stop
/jffs/scripts/service-event-end
Create the diagnostic archive from the router SSH shell. This command includes /opt/... paths and therefore requires Entware and an installed AdGuardHome environment:
echo .config > exclude-files; tar -cvf AdGuardHome.tar -X exclude-files /opt/etc/AdGuardHome /opt/sbin/AdGuardHome /opt/etc/init.d/S99AdGuardHome /opt/etc/init.d/rc.func.AdGuardHome /jffs/addons/AdGuardHome.d /jffs/scripts/init-start /jffs/scripts/dnsmasq.postconf /jffs/scripts/firewall-start /jffs/scripts/services-stop /jffs/scripts/service-event-end; rm exclude-files
Attach AdGuardHome.tar to the issue report.
Static AdGuardHome archive cache
This repository includes a scheduled GitHub Actions workflow that refreshes local static copies of upstream AdGuardHome archives four times per day: 00:00, 06:00, 12:00, and 18:00 UTC.
The workflow downloads stable, beta, and edge archives from https://static.adtidy.org/adguardhome/<channel>/AdGuardHome_<platform>_<architecture>.tar.gz and saves them by router architecture folder:
armv8/ stores linux_arm64 archives.armv7/ stores linux_armv7 archives.armv5/ stores linux_armv5 archives.
These are archive-routing names, not a claim about the router CPU generation. The armv5 compatibility archive is the package target used for older ARMv7 routers such as the ASUS RT-AC68U; its virtual validation guest is a Cortex-A9 with software float and VFP/NEON disabled. The separate armv7 target represents a newer Cortex-A15 hard-float environment.
Archives are written with channel-based local filenames, such as AdGuardHome_stable_linux_arm64.tar.gz, and checksum.txt is published after the archives and checksum sidecars are ready. Installers use checksum.txt to select the current archive, which avoids exposing a newly referenced archive before its SHA-256 sidecar is available.
Each architecture folder also gets generated metadata:
VERSION.txt lists each archive, local channel name, upstream channel name, and AdGuardHome version from upstream version.json. The legacy upstream version.txt can contain an older Edge version and is not used by the cache downloader.checksum.txt lists each archive with its channel, version, MD5 checksum, and SHA-256 checksum.*.tar.gz.sha256sum sidecar files contain the preferred SHA-256 integrity checksum for the matching compressed archive.*.tar.gz.md5sum sidecar files are retained as compatibility metadata for older installer flows and mirrors that do not have SHA-256 sidecars yet.
The local stable filenames use stable, while the upstream static AdGuardHome channel path remains release to match the installer branch naming.
The cache downloader requires jq to validate upstream JSON metadata. The workflow stages archives, checksum sidecars, and metadata together before checking for changes, including files recreated after removal from Git.
Download integrity compatibility policy
Installer-managed HTTPS downloads always retain certificate verification. Certificate failures are reported by the selected downloader and cause the bounded download attempt to fail; the installer never retries with curl --insecure/-k or wget --no-check-certificate.
Checksum verification remains mandatory before a staged installer-managed artifact replaces the working copy. The installer prefers a matching SHA-256 digest and permits a matching MD5 digest only through the legacy compatibility policy below; missing, malformed, or mismatching applicable checksum data prevents the artifact from being accepted. In particular, MD5 is retained for legacy compatibility and is not a cryptographic substitute for certificate validation or SHA-256.
The installer prefers SHA-256 for download integrity verification. An MD5 fallback remains intentional compatibility behavior for supported legacy environments, but it is allowed only when SHA-256 metadata is unavailable or SHA-256 calculation support is unavailable. Invalid, empty, or mismatching SHA-256 metadata causes the download to fail or retry and never permits a downgrade to MD5 verification.
The legacy-compatible MD5 path requires valid MD5 metadata and a matching calculated digest. A download fails when neither the SHA-256 path nor the MD5 compatibility path verifies the artifact. Checksum integrity verification and TLS certificate verification are separate safeguards: a valid checksum does not replace certificate validation, and certificate validation does not replace checksum verification.
MD5 checksum sidecars remain part of the v2.6.5 release format for this compatibility policy; they are not the preferred verification path.
Development checks
Architecture-native virtual feature tests run in disposable ARM package targets. The armv5 package target is exercised on an older ARMv7 Cortex-A9 software-float guest representing the ASUS RT-AC68U (VFP/NEON disabled); it is not an ARMv5 CPU generation. The separate armv7 target uses a newer Cortex-A15 hard-float guest, and armv8 uses AArch64. The virtual testing guide lists covered contracts, environment dependencies and evidence rules. A complete passing matrix unblocks only its explicitly tested feature/change checks; untested behavior receives no coverage credit.
After building the environments as described in the guide, run the hook, lock, lifecycle and native DNS contracts on the validation host:
sh tools/test-virtual-arm.sh --features hooks,locks,lifecycle,native_dns --output ../work/virtual-arm-results
The v2.7.0 candidate must complete its acceptance checklist; unexecuted mandatory hardware rows block whole-release approval while passing covered virtual contracts remain independently accepted. The v2.6.7 and v2.6.5 checklists remain historical validation.
Repository shell scripts are written for POSIX/BusyBox ash compatibility. Avoid Bash-only syntax such as arrays, process substitution, [[ ... ]], and non-portable pipefail.
Run the repository quality helper before opening a pull request:
tools/code-quality.sh
The helper validates installer artifact checksum files, runs ShellCheck on detected shell scripts, and checks formatting with shfmt. SHA-256 metadata is preferred for release integrity checks; .md5sum files remain compatibility metadata and are used only when SHA-256 metadata is unavailable.
To apply shfmt formatting locally, run:
tools/code-quality.sh --fix
If CI reports shfmt formatting differences, you can also run the Create shfmt formatting PR workflow against the affected branch to open an automated formatting pull request.
The repository provides a Codex review prompt for separately configured review automation. Committing the prompt does not install a reviewer or guarantee that an external review runs; inspect the current PR checks for provider status.
Shared agent integrations
The agent integration guide catalogs the existing reviewers, task records and shared repository skills for planning, implementation, verification, review completion, workflow auditing, security triage and handoffs. Codex, Amazon Q, CodeRabbit, Qodo, Claude, Cursor and GitHub Copilot entry points follow the canonical AGENTS.md policy. Skills run when an assistant invokes them; external service activation and authentication remain provider-specific.
The existing code-quality runner validates the catalog, skill discovery, agent policy pointers and the Amazon Q mirror. Run focused host checks with:
python3 tools/check-agent-integrations.py
python3 tests/agent-integrations.py
Validation hosts and GitHub Actions runners are separate from the Asuswrt-Merlin router runtime. The repository explicitly permits the following host-only tools for CI, code-quality, parser, scanner, and regression checks:
- Python 3 for validation helpers such as
.github/scripts/fix-sonar-shell-parse.py.
- GNU coreutils, including GNU
timeout at the explicit /usr/bin/timeout path, for bounded validation commands.
- The CI runner’s package manager. The supported GitHub Actions jobs use Ubuntu and may run
sudo apt-get update and sudo apt-get install to provision their declared validation packages.
bzip2, XZ Utils (xz-utils), and Zstandard (zstd) for tzdata package-conversion tests.
On a Debian or Ubuntu validation host, install and verify these prerequisites with:
sudo apt-get update
sudo apt-get install -y python3 coreutils bzip2 xz-utils zstd
python3 --version
/usr/bin/timeout --version
bzip2 --help >/dev/null
/usr/bin/xz --version
zstd --version
This permission is limited to development workstations and CI/validation runners. It does not make Python, GNU coreutils, apt-get, or the compression utilities router-runtime dependencies, does not make them available in the router stock PATH, and does not relax the POSIX /bin/sh and BusyBox ash requirements for installer and service scripts. AI reviewers and code scanners must distinguish explicitly host-only validation paths from router-runtime paths when checking dependencies.
Release validation
v2.7.0-rc.1 is the intended opt-in development candidate, not a published release. Use the candidate operator guide to pin and verify the assembled source, then record exact inputs and software qualification in the v2.7.0 checklist. Physical acceptance and 48-hour ARMv7/AArch64 soak are NOT RUN. An installer candidate version does not select the AdGuardHome release, beta or edge channel.
This candidate adds an opt-in sanitized support report, verified service-file prefetch before update/restore changes, and retention of the dnsmasq backup needed for a pending IPSet restoration. Native virtual coverage exercises each committed stable, beta and edge binary through its service/DNS lifecycle and tests actual full/read-only filesystems. See the checklist for observed results and the distinct physical release gates.
v2.6.7 is the published repair release for managed hook migration/diagnostics, service-lock path safety and serialization, and verified monitor shutdown. Its historical acceptance checklist records software evidence and completed physical acceptance: both ARMv7 and AArch64 routers passed the full checklist and 48-hour testing, confirmed by the maintainer/operator on October 10, 2026 America/New_York. This covers the checklist’s hook/upgrade, firmware DNS restart, DHCP/client/isolation and recovery requirements for the tested configurations. The full-checklist/48-hour configurations were RT-AC5300 / 386.14_2 and GT-BE98PRO / 3006.102.9, respectively, with additional physical testing reported on RT-AC68U / 386.14_2. Its individual duration/checklist detail and exact deployed build/event logs remain unreported. These historical results do not certify the new candidate.
Release validation is a focused pre-tag pass from the repository root. The required commands in this subsection use POSIX sh, BusyBox-compatible syntax checks, and repository test scripts; this portable subset does not itself require Python, Perl, GNU coreutils, systemd, apt-get, or Entware. The broader CI and code-quality jobs may use the explicitly permitted host-only validation toolchain above.
The release validation pass performs these actions:
- Syntax-checks the primary installer and service scripts with POSIX
sh.
- Checks repository shell scripts for POSIX/BusyBox portability.
- Verifies SHA-256 metadata for installer-managed artifacts.
- Runs selected router-sensitive regressions for DNS handoff, IPSET setup/status/locking, rollback and doctor rollback behavior, CLI runtime configuration, and interruption restart handling.
- Requires root privileges or passwordless
sudo for tests/optional-database-links.sh; non-privileged maintainers must have passwordless sudo available before running the complete pass.
- Optionally runs ShellCheck static analysis against the primary scripts when ShellCheck is installed on a development workstation outside the router.
Run the required release validation commands from the repository root:
for script in installer AdGuardHome.sh S99AdGuardHome rc.func.AdGuardHome; do
sh -n "${script}" || exit 1
done
sh tools/check-shell-portability.sh
sh tools/check-sha256.sh
Run the selected regression tests that cover the router-sensitive release paths:
sh tests/dns-startup-handoff.sh
sh tests/s99-netstat-readiness.sh
sh tests/dnsmasq-lan-mode.sh
sh tests/adguardhome-dns-env-lan-mode.sh
sh tests/ipset-version-gate.sh
sh tests/ipset-lan-mode.sh
sh tests/ipset-lock-security.sh
sh tests/ipset-setup-rollback.sh
sh tests/ipset-status.sh
sh tests/installer-end-op-rollback.sh
sh tests/installer-doctor-rollback-result.sh
sh tests/installer-cli-runtime-config.sh
sh tests/installer-cli-lan-mode.sh
sh tests/installer-lan-ipset-yaml-cleanup.sh
sh tests/installer-event-script-modes.sh
sh tests/installer-interruption-restart.sh
sh tests/start-adguardhome-lifecycle.sh
sh tests/rc-process-signaling.sh
if [ "$(id -u)" -eq 0 ]; then
sh tests/optional-database-links.sh
elif which sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then
sudo -n sh tests/optional-database-links.sh
else
printf '%s\n' 'The optional database link regression requires root privileges or passwordless sudo.' >&2
false
fi
Optionally run ShellCheck on a development workstation when ShellCheck is installed outside the router:
if which shellcheck >/dev/null 2>&1; then
shellcheck -s sh installer AdGuardHome.sh S99AdGuardHome rc.func.AdGuardHome
fi
ShellCheck is not a router dependency; it is an optional workstation check only. The required release validation commands above use POSIX sh and repository scripts, and they do not require the broader host-only toolchain. CI may provision that toolchain for additional checks without changing router-runtime requirements. Router-sensitive tests that cannot run directly in a local environment belong in the same POSIX sh test environment used for CI.
Project notes
Donate
This script is open source and free to use under the GPL-3.0 license. If you want to support future development, you can donate through:
This project uses TaskPlanner for task planning.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论