mirrors/AdGuardHome
1
0
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2024-12-29 18:18:25 +03:00
Code Issues Projects Releases Packages Wiki Activity

Pull request 2326: more-md-lint

Browse source 
Merge in DNS/adguard-home from more-md-lint to master

Squashed commit of the following:

commit 39e7ea3b441ebf48c5b0d5c2b5b85620515bbea3
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Dec 19 17:03:36 2024 +0300

    all: imp docs more

commit 7aa08036b239d7eb19f674a6c4bfaf1325ff4bff
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Dec 19 16:08:13 2024 +0300

    all: add more docs to lint
This commit is contained in:
Ainar Garipov 2024-12-19 17:17:40 +03:00
parent 261c1599a5
commit 20e56b7171
8 changed files with 231 additions and 399 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
CHANGELOG.md
View file

@ -175,7 +175,7 @@ See also the [v0.107.52 GitHub milestone][ms-v0.107.52].
- Frontend rewritten in TypeScript. - Frontend rewritten in TypeScript.
- The `systemd`-based service now uses `journal` for logging by default. It also doesn't create the `/var/log/` directory anymore ([#7053]). - The `systemd`-based service now uses `journal` for logging by default. It also doesn’t create the `/var/log/` directory anymore ([#7053]).
**NOTE:** With an installed service for changes to take effect, you need to reinstall the service using `-r` flag of the [install script][install-script] or via the CLI (with root privileges): **NOTE:** With an installed service for changes to take effect, you need to reinstall the service using `-r` flag of the [install script][install-script] or via the CLI (with root privileges):
@ -184,7 +184,7 @@ See also the [v0.107.52 GitHub milestone][ms-v0.107.52].
./AdGuardHome -s install ./AdGuardHome -s install
``` ```
Don't forget to backup your configuration file and other important data before reinstalling the service. Don’t forget to backup your configuration file and other important data before reinstalling the service.
### Deprecated ### Deprecated
@ -216,7 +216,7 @@ See also the [v0.107.51 GitHub milestone][ms-v0.107.51].
### Changed ### Changed
- The HTTP server's write timeout has been increased from 1 minute to 5 minutes to match the one used by AdGuard Home's HTTP client to fetch filtering-list data ([#7041]). - The HTTP server’s write timeout has been increased from 1 minute to 5 minutes to match the one used by AdGuard Home’s HTTP client to fetch filtering-list data ([#7041]).
[#7041]: https://github.com/AdguardTeam/AdGuardHome/issues/7041 [#7041]: https://github.com/AdguardTeam/AdGuardHome/issues/7041
@ -277,7 +277,7 @@ See also the [v0.107.49 GitHub milestone][ms-v0.107.49].
- Subdomains of `in-addr.arpa` and `ip6.arpa` containing zero-length prefix incorrectly considered invalid when specified for private rDNS upstream servers ([#6854]). - Subdomains of `in-addr.arpa` and `ip6.arpa` containing zero-length prefix incorrectly considered invalid when specified for private rDNS upstream servers ([#6854]).
- Unspecified IP addresses aren't checked when using "Fastest IP address" mode ([#6875]). - Unspecified IP addresses aren’t checked when using "Fastest IP address" mode ([#6875]).
[#5345]: https://github.com/AdguardTeam/AdGuardHome/issues/5345 [#5345]: https://github.com/AdguardTeam/AdGuardHome/issues/5345
[#5812]: https://github.com/AdguardTeam/AdGuardHome/issues/5812 [#5812]: https://github.com/AdguardTeam/AdGuardHome/issues/5812
@ -366,7 +366,7 @@ See also the [v0.107.46 GitHub milestone][ms-v0.107.46].
- Missing "served from cache" label on long DNS server strings ([#6740]). - Missing "served from cache" label on long DNS server strings ([#6740]).
- Incorrect tracking of the system hosts file's changes ([#6711]). - Incorrect tracking of the system hosts file’s changes ([#6711]).
[#5992]: https://github.com/AdguardTeam/AdGuardHome/issues/5992 [#5992]: https://github.com/AdguardTeam/AdGuardHome/issues/5992
[#6610]: https://github.com/AdguardTeam/AdGuardHome/issues/6610 [#6610]: https://github.com/AdguardTeam/AdGuardHome/issues/6610
@ -391,7 +391,7 @@ See also the [v0.107.45 GitHub milestone][ms-v0.107.45].
### Changed ### Changed
- Starting with this release our scripts are using Go's [forward compatibility mechanism][go-toolchain] for updating the Go version. - Starting with this release our scripts are using Go’s [forward compatibility mechanism][go-toolchain] for updating the Go version.
**Important note for porters:** This change means that if your `go` version is 1.21+ but is different from the one required by AdGuard Home, the `go` tool will automatically download the required version. **Important note for porters:** This change means that if your `go` version is 1.21+ but is different from the one required by AdGuard Home, the `go` tool will automatically download the required version.
@ -533,7 +533,7 @@ See also the [v0.107.42 GitHub milestone][ms-v0.107.42].
### Added ### Added
- Ability to set client's custom DNS cache ([#6263]). - Ability to set client’s custom DNS cache ([#6263]).
- Ability to disable plain-DNS serving through configuration file if an encrypted protocol is already enabled ([#1660]). - Ability to disable plain-DNS serving through configuration file if an encrypted protocol is already enabled ([#1660]).
@ -547,7 +547,7 @@ See also the [v0.107.42 GitHub milestone][ms-v0.107.42].
- The property `dns.bogus_nxdomain` is now validated more strictly. - The property `dns.bogus_nxdomain` is now validated more strictly.
- Added new properties `clients.persistent.*.upstreams_cache_enabled` and `clients.persistent.*.upstreams_cache_size` that describe cache configuration for each client's custom upstream configuration. - Added new properties `clients.persistent.*.upstreams_cache_enabled` and `clients.persistent.*.upstreams_cache_size` that describe cache configuration for each client’s custom upstream configuration.
### Fixed ### Fixed
@ -730,7 +730,7 @@ See also the [v0.107.37 GitHub milestone][ms-v0.107.37].
- The ability to set fallback DNS servers in the configuration file and the UI ([#3701]). - The ability to set fallback DNS servers in the configuration file and the UI ([#3701]).
- While adding or updating blocklists, the title can now be parsed from `! Title:` definition of the blocklist's source ([#6020]). - While adding or updating blocklists, the title can now be parsed from `! Title:` definition of the blocklist’s source ([#6020]).
- The ability to filter DNS HTTPS records including IPv4 and IPv6 hints ([#6053]). - The ability to filter DNS HTTPS records including IPv4 and IPv6 hints ([#6053]).
@ -742,7 +742,7 @@ See also the [v0.107.37 GitHub milestone][ms-v0.107.37].
- `$dnsrewrite` rules containing IPv4-mapped IPv6 addresses are now working consistently with legacy DNS rewrites and match the `AAAA` requests. - `$dnsrewrite` rules containing IPv4-mapped IPv6 addresses are now working consistently with legacy DNS rewrites and match the `AAAA` requests.
- For non-A and non-AAAA requests, which has been filtered, the NODATA response is returned if the blocking mode isn't set to `Null IP`. In previous versions it returned NXDOMAIN response in such cases. - For non-A and non-AAAA requests, which has been filtered, the NODATA response is returned if the blocking mode isn’t set to `Null IP`. In previous versions it returned NXDOMAIN response in such cases.
#### Configuration changes #### Configuration changes
@ -1112,7 +1112,7 @@ In this release, the schema version has changed from 20 to 23.
- Queries with the question-section target `.`, for example `NS .`, are now counted in the statistics and correctly shown in the query log ([#5910]). - Queries with the question-section target `.`, for example `NS .`, are now counted in the statistics and correctly shown in the query log ([#5910]).
- Safe Search not working with `AAAA` queries for domains that don't have `AAAA` records ([#5913]). - Safe Search not working with `AAAA` queries for domains that don’t have `AAAA` records ([#5913]).
[#951]: https://github.com/AdguardTeam/AdGuardHome/issues/951 [#951]: https://github.com/AdguardTeam/AdGuardHome/issues/951
[#1577]: https://github.com/AdguardTeam/AdGuardHome/issues/1577 [#1577]: https://github.com/AdguardTeam/AdGuardHome/issues/1577
@ -1161,7 +1161,7 @@ See also the [v0.107.30 GitHub milestone][ms-v0.107.30].
- Unquoted IPv6 bind hosts with trailing colons erroneously considered unspecified addresses are now properly validated ([#5752]). - Unquoted IPv6 bind hosts with trailing colons erroneously considered unspecified addresses are now properly validated ([#5752]).
**NOTE:** the Docker healthcheck script now also doesn't interpret the `""` value as unspecified address. **NOTE:** the Docker healthcheck script now also doesn’t interpret the `""` value as unspecified address.
- Incorrect `Content-Type` header value in `POST /control/version.json` and `GET /control/dhcp/interfaces` HTTP APIs ([#5716]). - Incorrect `Content-Type` header value in `POST /control/version.json` and `GET /control/dhcp/interfaces` HTTP APIs ([#5716]).
@ -1178,7 +1178,7 @@ See also the [v0.107.29 GitHub milestone][ms-v0.107.29].
### Added ### Added
- The ability to exclude client activity from the query log or statistics by editing client's settings on the respective page in the UI ([#1717], [#4299]). - The ability to exclude client activity from the query log or statistics by editing client’s settings on the respective page in the UI ([#1717], [#4299]).
### Changed ### Changed
@ -1215,7 +1215,7 @@ See also the [v0.107.28 GitHub milestone][ms-v0.107.28].
- The ability to make bootstrap DNS lookups prefer IPv6 addresses to IPv4 ones using the new `dns.bootstrap_prefer_ipv6` configuration file property ([#4262]). - The ability to make bootstrap DNS lookups prefer IPv6 addresses to IPv4 ones using the new `dns.bootstrap_prefer_ipv6` configuration file property ([#4262]).
- Docker container's healthcheck ([#3290]). - Docker container’s healthcheck ([#3290]).
- The new HTTP API `POST /control/protection`, that updates protection state and adds an optional pause duration ([#1333]). The format of request body is described in `openapi/openapi.yaml`. The duration of this pause could also be set with the property `protection_disabled_until` in the `dns` object of the YAML configuration file. - The new HTTP API `POST /control/protection`, that updates protection state and adds an optional pause duration ([#1333]). The format of request body is described in `openapi/openapi.yaml`. The duration of this pause could also be set with the property `protection_disabled_until` in the `dns` object of the YAML configuration file.
@ -1272,7 +1272,7 @@ In this release, the schema version has changed from 17 to 20.
'youtube': true 'youtube': true
``` ```
To rollback this change, move the value of `dns.safe_search.enabled` into the `dns.safesearch_enabled`, then remove `dns.safe_search` property. Do the same client's specific `clients.persistent.safesearch` and then change the `schema_version` back to `17`. To rollback this change, move the value of `dns.safe_search.enabled` into the `dns.safesearch_enabled`, then remove `dns.safe_search` property. Do the same client’s specific `clients.persistent.safesearch` and then change the `schema_version` back to `17`.
### Deprecated ### Deprecated
@ -1302,7 +1302,7 @@ In this release, the schema version has changed from 17 to 20.
### Fixed ### Fixed
- Logging of the client's IP address after failed login attempts ([#5701]). - Logging of the client’s IP address after failed login attempts ([#5701]).
[#1163]: https://github.com/AdguardTeam/AdGuardHome/issues/1163 [#1163]: https://github.com/AdguardTeam/AdGuardHome/issues/1163
[#1333]: https://github.com/AdguardTeam/AdGuardHome/issues/1333 [#1333]: https://github.com/AdguardTeam/AdGuardHome/issues/1333
@ -1328,7 +1328,7 @@ See also the [v0.107.27 GitHub milestone][ms-v0.107.27].
- Query log not showing all filtered queries when the “Filtered” log filter is selected ([#5639]). - Query log not showing all filtered queries when the “Filtered” log filter is selected ([#5639]).
- Panic in empty hostname in the filter's URL ([#5631]). - Panic in empty hostname in the filter’s URL ([#5631]).
- Panic caused by empty top-level domain name label in `/etc/hosts` files ([#5584]). - Panic caused by empty top-level domain name label in `/etc/hosts` files ([#5584]).
@ -1535,7 +1535,7 @@ See also the [v0.107.22 GitHub milestone][ms-v0.107.22].
### Changed ### Changed
- The HTTP API `GET /control/profile` now returns enhanced object with current user's name, language, and UI theme. The format of response body is described in `openapi/openapi.yaml` and `openapi/CHANGELOG.md`. - The HTTP API `GET /control/profile` now returns enhanced object with current user’s name, language, and UI theme. The format of response body is described in `openapi/openapi.yaml` and `openapi/CHANGELOG.md`.
### Fixed ### Fixed
@ -1666,7 +1666,7 @@ See also the [v0.107.17 GitHub milestone][ms-v0.107.17].
### Changed ### Changed
- DNS-over-TLS resolvers aren't returned anymore when the configured TLS certificate contains no IP addresses ([#4927]). - DNS-over-TLS resolvers aren’t returned anymore when the configured TLS certificate contains no IP addresses ([#4927]).
- Responses with `SERVFAIL` code are now cached for at least 30 seconds. - Responses with `SERVFAIL` code are now cached for at least 30 seconds.
@ -1682,7 +1682,7 @@ See also the [v0.107.17 GitHub milestone][ms-v0.107.17].
- The default value of `dns.cache_size` accidentally set to 0 has now been reverted to 4 MiB ([#5010]). - The default value of `dns.cache_size` accidentally set to 0 has now been reverted to 4 MiB ([#5010]).
- Responses for which the DNSSEC validation had explicitly been omitted aren't cached now ([#4942]). - Responses for which the DNSSEC validation had explicitly been omitted aren’t cached now ([#4942]).
- Web UI not switching to HTTP/3 ([#4986], [#4993]). - Web UI not switching to HTTP/3 ([#4986], [#4993]).
@ -1803,7 +1803,7 @@ See also the [v0.107.13 GitHub milestone][ms-v0.107.13].
### Changed ### Changed
- The minimum DHCP message size is reassigned back to BOOTP's constraint of 300 bytes ([#4904]). - The minimum DHCP message size is reassigned back to BOOTP’s constraint of 300 bytes ([#4904]).
### Fixed ### Fixed
@ -1827,7 +1827,7 @@ See also the [v0.107.12 GitHub milestone][ms-v0.107.12].
- New `bool`, `dur`, `u8`, and `u16` DHCP options to provide more convenience on options control by setting values in a human-readable format ([#4705]). See also a [Wiki page][wiki-dhcp-opts]. - New `bool`, `dur`, `u8`, and `u16` DHCP options to provide more convenience on options control by setting values in a human-readable format ([#4705]). See also a [Wiki page][wiki-dhcp-opts].
- New `del` DHCP option which removes the corresponding option from server's response ([#4337]). See also a [Wiki page][wiki-dhcp-opts]. - New `del` DHCP option which removes the corresponding option from server’s response ([#4337]). See also a [Wiki page][wiki-dhcp-opts].
**NOTE:** This modifier affects all the parameters in the response and not only the requested ones. **NOTE:** This modifier affects all the parameters in the response and not only the requested ones.
@ -1851,7 +1851,7 @@ See also the [v0.107.12 GitHub milestone][ms-v0.107.12].
### Fixed ### Fixed
- The length of the DHCP server's response is now at least 576 bytes as per [RFC 2131][rfc-2131] recommendation ([#4337]). - The length of the DHCP server’s response is now at least 576 bytes as per [RFC 2131][rfc-2131] recommendation ([#4337]).
- Dynamic leases created with empty hostnames ([#4745]). - Dynamic leases created with empty hostnames ([#4745]).
@ -2021,7 +2021,7 @@ See also the [v0.107.7 GitHub milestone][ms-v0.107.7].
- The default DNS-over-QUIC port number is now `853` instead of `754` in accordance with [RFC 9250][rfc-9250] ([#4276]). - The default DNS-over-QUIC port number is now `853` instead of `754` in accordance with [RFC 9250][rfc-9250] ([#4276]).
- Reverse DNS now has a greater priority as the source of runtime clients' information than ARP neighborhood. - Reverse DNS now has a greater priority as the source of runtime clients’ information than ARP neighborhood.
- Improved detection of runtime clients through more resilient ARP processing ([#3597]). - Improved detection of runtime clients through more resilient ARP processing ([#3597]).
@ -2165,7 +2165,7 @@ See also the [v0.107.6 GitHub milestone][ms-v0.107.6].
### Removed ### Removed
- Go 1.16 support, since that branch of the Go compiler has reached end of life and doesn't receive security updates anymore. - Go 1.16 support, since that branch of the Go compiler has reached end of life and doesn’t receive security updates anymore.
[#3717]: https://github.com/AdguardTeam/AdGuardHome/issues/3717 [#3717]: https://github.com/AdguardTeam/AdGuardHome/issues/3717
[#4437]: https://github.com/AdguardTeam/AdGuardHome/issues/4437 [#4437]: https://github.com/AdguardTeam/AdGuardHome/issues/4437
@ -2199,7 +2199,7 @@ See also the [v0.107.4 GitHub milestone][ms-v0.107.4].
### Fixed ### Fixed
- Optimistic cache now responds with expired items even if those can't be resolved again ([#4254]). - Optimistic cache now responds with expired items even if those can’t be resolved again ([#4254]).
- Unnecessarily complex hosts-related logic leading to infinite recursion in some cases ([#4216]). - Unnecessarily complex hosts-related logic leading to infinite recursion in some cases ([#4216]).
@ -2227,7 +2227,7 @@ See also the [v0.107.3 GitHub milestone][ms-v0.107.3].
- Poor testing of domain-specific upstream servers ([#4074]). - Poor testing of domain-specific upstream servers ([#4074]).
- Omitted aliases of hosts specified by another line within the OS's hosts file ([#4079]). - Omitted aliases of hosts specified by another line within the OS’s hosts file ([#4079]).
[#4074]: https://github.com/AdguardTeam/AdGuardHome/issues/4074 [#4074]: https://github.com/AdguardTeam/AdGuardHome/issues/4074
[#4079]: https://github.com/AdguardTeam/AdGuardHome/issues/4079 [#4079]: https://github.com/AdguardTeam/AdGuardHome/issues/4079
@ -2271,7 +2271,7 @@ See also the [v0.107.1 GitHub milestone][ms-v0.107.1].
- Panic on port availability check during installation ([#3987]). - Panic on port availability check during installation ([#3987]).
- Incorrect application of rules from the OS's hosts files ([#3998]). - Incorrect application of rules from the OS’s hosts files ([#3998]).
[#3868]: https://github.com/AdguardTeam/AdGuardHome/issues/3868 [#3868]: https://github.com/AdguardTeam/AdGuardHome/issues/3868
[#3975]: https://github.com/AdguardTeam/AdGuardHome/issues/3975 [#3975]: https://github.com/AdguardTeam/AdGuardHome/issues/3975
@ -2289,7 +2289,7 @@ See also the [v0.107.0 GitHub milestone][ms-v0.107.0].
### Added ### Added
- Upstream server information for responses from cache ([#3772]). Note that old log entries concerning cached responses won't include that information. - Upstream server information for responses from cache ([#3772]). Note that old log entries concerning cached responses won’t include that information.
- Finnish and Ukrainian localizations. - Finnish and Ukrainian localizations.
@ -2317,7 +2317,7 @@ See also the [v0.107.0 GitHub milestone][ms-v0.107.0].
- Experimental OpenBSD support for AMD64 and 64-bit ARM CPUs ([#2439], [#3225], [#3226]). - Experimental OpenBSD support for AMD64 and 64-bit ARM CPUs ([#2439], [#3225], [#3226]).
- Support for custom port in DNS-over-HTTPS profiles for Apple's devices ([#3172]). - Support for custom port in DNS-over-HTTPS profiles for Apple’s devices ([#3172]).
- `darwin/arm64` support ([#2443]). - `darwin/arm64` support ([#2443]).
@ -2349,11 +2349,11 @@ See also the [v0.107.0 GitHub milestone][ms-v0.107.0].
- DHCP gateway address, subnet mask, IP address range, and leases validations ([#3529]). - DHCP gateway address, subnet mask, IP address range, and leases validations ([#3529]).
- The `systemd` service script will now create the `/var/log` directory when it doesn't exist ([#3579]). - The `systemd` service script will now create the `/var/log` directory when it doesn’t exist ([#3579]).
- Items in allowed clients, disallowed clients, and blocked hosts lists are now required to be unique ([#3419]). - Items in allowed clients, disallowed clients, and blocked hosts lists are now required to be unique ([#3419]).
- The TLS private key previously saved as a string isn't shown in API responses anymore ([#1898]). - The TLS private key previously saved as a string isn’t shown in API responses anymore ([#1898]).
- Better OpenWrt detection ([#3435]). - Better OpenWrt detection ([#3435]).
@ -2416,15 +2416,15 @@ In this release, the schema version has changed from 10 to 12.
- EDNS0 TCP keepalive option handling ([#3778]). - EDNS0 TCP keepalive option handling ([#3778]).
- Rules with the `denyallow` modifier applying to IP addresses when they shouldn't ([#3175]). - Rules with the `denyallow` modifier applying to IP addresses when they shouldn’t ([#3175]).
- The length of the EDNS0 client subnet option appearing too long for some upstream servers ([#3887]). - The length of the EDNS0 client subnet option appearing too long for some upstream servers ([#3887]).
- Invalid redirection to the HTTPS web interface after saving enabled encryption settings ([#3558]). - Invalid redirection to the HTTPS web interface after saving enabled encryption settings ([#3558]).
- Incomplete propagation of the client's IP anonymization setting to the statistics ([#3890]). - Incomplete propagation of the client’s IP anonymization setting to the statistics ([#3890]).
- Incorrect results with the `dnsrewrite` modifier for entries from the operating system's hosts file ([#3815]). - Incorrect results with the `dnsrewrite` modifier for entries from the operating system’s hosts file ([#3815]).
- Matching against rules with `|` at the end of the domain name ([#3371]). - Matching against rules with `|` at the end of the domain name ([#3371]).
@ -2456,7 +2456,7 @@ In this release, the schema version has changed from 10 to 12.
- Incomplete HTTP response for static IP address. - Incomplete HTTP response for static IP address.
- DNSCrypt queries weren't appearing in query log ([#3372]). - DNSCrypt queries weren’t appearing in query log ([#3372]).
- Wrong IP address for proxied DNS-over-HTTPS queries ([#2799]). - Wrong IP address for proxied DNS-over-HTTPS queries ([#2799]).
@ -2636,15 +2636,15 @@ See also the [v0.106.0 GitHub milestone][ms-v0.106.0].
- Hostname uniqueness validation in the DHCP server ([#2952]). - Hostname uniqueness validation in the DHCP server ([#2952]).
- Hostname generating for DHCP clients which don't provide their own ([#2723]). - Hostname generating for DHCP clients which don’t provide their own ([#2723]).
- New flag `--no-etc-hosts` to disable client domain name lookups in the operating system's `/etc/hosts` files ([#1947]). - New flag `--no-etc-hosts` to disable client domain name lookups in the operating system’s `/etc/hosts` files ([#1947]).
- The ability to set up custom upstreams to resolve PTR queries for local addresses and to disable the automatic resolving of clients' addresses ([#2704]). - The ability to set up custom upstreams to resolve PTR queries for local addresses and to disable the automatic resolving of clients’ addresses ([#2704]).
- Logging of the client's IP address after failed login attempts ([#2824]). - Logging of the client’s IP address after failed login attempts ([#2824]).
- Search by clients' names in the query log ([#1273]). - Search by clients’ names in the query log ([#1273]).
- Verbose version output with `-v --version` ([#2416]). - Verbose version output with `-v --version` ([#2416]).
@ -2686,7 +2686,7 @@ See also the [v0.106.0 GitHub milestone][ms-v0.106.0].
- Inconsistent resolving of DHCP clients when the DHCP server is disabled ([#2934]). - Inconsistent resolving of DHCP clients when the DHCP server is disabled ([#2934]).
- Comment handling in clients' custom upstreams ([#2947]). - Comment handling in clients’ custom upstreams ([#2947]).
- Overwriting of DHCPv4 options when using the HTTP API ([#2927]). - Overwriting of DHCPv4 options when using the HTTP API ([#2927]).
@ -2737,7 +2737,7 @@ See also the [v0.106.0 GitHub milestone][ms-v0.106.0].
### Security ### Security
- Session token doesn't contain user's information anymore ([#2470]). - Session token doesn’t contain user’s information anymore ([#2470]).
See also the [v0.105.2 GitHub milestone][ms-v0.105.2]. See also the [v0.105.2 GitHub milestone][ms-v0.105.2].
@ -2751,7 +2751,7 @@ See also the [v0.105.2 GitHub milestone][ms-v0.105.2].
- Incomplete OpenWrt detection ([#2757]). - Incomplete OpenWrt detection ([#2757]).
- DHCP lease's `expired` property incorrect time format ([#2692]). - DHCP lease’s `expired` property incorrect time format ([#2692]).
- Incomplete DNS upstreams validation ([#2674]). - Incomplete DNS upstreams validation ([#2674]).
@ -2784,7 +2784,7 @@ See also the [v0.105.1 GitHub milestone][ms-v0.105.1].
### Fixed ### Fixed
- Error when enabling the DHCP server when AdGuard Home couldn't determine if the machine has a static IP. - Error when enabling the DHCP server when AdGuard Home couldn’t determine if the machine has a static IP.
- Optical issue on custom rules ([#2641]). - Optical issue on custom rules ([#2641]).
@ -2792,7 +2792,7 @@ See also the [v0.105.1 GitHub milestone][ms-v0.105.1].
- The property `"range_start"` in the `GET /control/dhcp/status` HTTP API response is now correctly named again ([#2678]). - The property `"range_start"` in the `GET /control/dhcp/status` HTTP API response is now correctly named again ([#2678]).
- DHCPv6 server's `ra_slaac_only` and `ra_allow_slaac` properties aren't reset to `false` on update anymore ([#2653]). - DHCPv6 server’s `ra_slaac_only` and `ra_allow_slaac` properties aren’t reset to `false` on update anymore ([#2653]).
- The `Vary` header is now added along with `Access-Control-Allow-Origin` to prevent cache-related and other issues in browsers ([#2658]). - The `Vary` header is now added along with `Access-Control-Allow-Origin` to prevent cache-related and other issues in browsers ([#2658]).
@ -2800,7 +2800,7 @@ See also the [v0.105.1 GitHub milestone][ms-v0.105.1].
- Incorrect version tag in the Docker release ([#2663]). - Incorrect version tag in the Docker release ([#2663]).
- DNSCrypt queries weren't marked as such in logs ([#2662]). - DNSCrypt queries weren’t marked as such in logs ([#2662]).
[#2641]: https://github.com/AdguardTeam/AdGuardHome/issues/2641 [#2641]: https://github.com/AdguardTeam/AdGuardHome/issues/2641
[#2653]: https://github.com/AdguardTeam/AdGuardHome/issues/2653 [#2653]: https://github.com/AdguardTeam/AdGuardHome/issues/2653
@ -2837,7 +2837,7 @@ See also the [v0.105.0 GitHub milestone][ms-v0.105.0].
- DNSCrypt protocol support ([#1361]). - DNSCrypt protocol support ([#1361]).
- A 5 second wait period until a DHCP server's network interface gets an IP address ([#2304]). - A 5 second wait period until a DHCP server’s network interface gets an IP address ([#2304]).
- `dnstype` modifier for filters ([#2337]). - `dnstype` modifier for filters ([#2337]).

98
internal/dhcpd/README.md
View file

@ -1,61 +1,50 @@
# Testing DHCP Server # Testing DHCP Server
Contents: Contents:
* [Test setup with Virtual Box](#vbox)
* [Quick test with DHCPTest](#dhcptest)
## <a href="#vbox" id="vbox" name="vbox">Test setup with Virtual Box</a> - [Test setup with Virtual Box](#vbox)
- [Quick test with DHCPTest](#dhcptest)
### Prerequisites ## <a href="#vbox" id="vbox" name="vbox">Test setup with Virtual Box</a>
### Prerequisites
To set up a test environment for DHCP server you will need: To set up a test environment for DHCP server you will need:
* Linux AG Home host machine (Virtual). - Linux AG Home host machine (Virtual)
* Virtual Box. - Virtual Box
* Virtual machine (guest OS doesn't matter). - Virtual machine (guest OS doesn't matter)
### Configure Virtual Box ### Configure Virtual Box
1. Install Virtual Box and run the following command to create a Host-Only 1. Install Virtual Box and run the following command to create a Host-Only network:
network:
```sh ```sh
$ VBoxManage hostonlyif create VBoxManage hostonlyif create
``` ```
You can check its status by `ip a` command. You can check its status by `ip a` command.
You can also set up Host-Only network using Virtual Box menu: You can also set up Host-Only network using Virtual Box menu in *File → Host Network Manager.*
``` 2. Create your virtual machine and set up its network in *VM Settings → Network → Host-only Adapter.*
File -> Host Network Manager...
```
2. Create your virtual machine and set up its network: 3. Start your VM, install an OS. Configure your network interface to use DHCP and the OS should ask for a IP address from our DHCP server.
``` 4. To see the current IP addresses on client OS you can use `ip a` command on Linux or `ipconfig` on Windows.
VM Settings -> Network -> Host-only Adapter
```
3. Start your VM, install an OS. Configure your network interface to use 5. To force the client OS to request an IP from DHCP server again, you can use `dhclient` on Linux or `ipconfig /release` on Windows.
DHCP and the OS should ask for a IP address from our DHCP server.
4. To see the current IP addresses on client OS you can use `ip a` command on ### Configure server
Linux or `ipconfig` on Windows.
5. To force the client OS to request an IP from DHCP server again, you can 1. Edit server configuration file `AdGuardHome.yaml`, for example:
use `dhclient` on Linux or `ipconfig /release` on Windows.
### Configure server ```yaml
dhcp:
1. Edit server configuration file `AdGuardHome.yaml`, for example: enabled: true
interface_name: vboxnet0
```yaml local_domain_name: lan
dhcp: dhcpv4:
enabled: true
interface_name: vboxnet0
local_domain_name: lan
dhcpv4:
gateway_ip: 192.168.56.1 gateway_ip: 192.168.56.1
subnet_mask: 255.255.255.0 subnet_mask: 255.255.255.0
range_start: 192.168.56.2 range_start: 192.168.56.2
@ -63,34 +52,33 @@ To set up a test environment for DHCP server you will need:
lease_duration: 86400 lease_duration: 86400
icmp_timeout_msec: 1000 icmp_timeout_msec: 1000
options: [] options: []
dhcpv6: dhcpv6:
range_start: 2001::1 range_start: 2001::1
lease_duration: 86400 lease_duration: 86400
ra_slaac_only: false ra_slaac_only: false
ra_allow_slaac: false ra_allow_slaac: false
``` ```
2. Start the server 2. Start the server:
```sh ```sh
./AdGuardHome -v ./AdGuardHome -v
``` ```
There should be a message in log which shows that DHCP server is ready: There should be a message in log which shows that DHCP server is ready:
``` ```none
[info] DHCP: listening on 0.0.0.0:67 [info] dhcpv4: listening
``` ```
## <a href="#dhcptest" id="dhcptest" name="dhcptest">Quick test with DHCPTest utility</a> ## <a href="#dhcptest" id="dhcptest" name="dhcptest">Quick test with DHCPTest utility</a>
### Prerequisites ### Prerequisites
* [DHCP test utility][dhcptest-gh]. - [DHCP test utility][dhcptest-gh].
### Quick test ### Quick test
The DHCP server could be tested for DISCOVER-OFFER packets with in The DHCP server could be tested for DISCOVER-OFFER packets with in interactive mode.
interactive mode.
[dhcptest-gh]: https://github.com/CyberShadow/dhcptest [dhcptest-gh]: https://github.com/CyberShadow/dhcptest

70
internal/filtering/README.md
View file

@ -1,70 +0,0 @@
# AdGuard Home's DNS filtering go library
Example use:
```bash
[ -z "$GOPATH" ] && export GOPATH=$HOME/go
go get -d github.com/AdguardTeam/AdGuardHome/filtering
```
Create file filter.go
```filter.go
package main
import (
"github.com/AdguardTeam/AdGuardHome/filtering"
"log"
)
func main() {
filter := filtering.New()
filter.AddRule("||dou*ck.net^")
host := "www.doubleclick.net"
res, err := filter.CheckHost(host)
if err != nil {
// temporary failure
log.Fatalf("Failed to check host %q: %s", host, err)
}
if res.IsFiltered {
log.Printf("Host %s is filtered, reason - %q, matched rule: %q", host, res.Reason, res.Rule)
} else {
log.Printf("Host %s is not filtered, reason - %q", host, res.Reason)
}
}
```
And then run it:
```bash
go run filter.go
```
You will get:
```
2000/01/01 00:00:00 Host www.doubleclick.net is filtered, reason - 'FilteredBlackList', matched rule: '||dou*ck.net^'
```
You can also enable checking against AdGuard's SafeBrowsing:
```go
package main
import (
"github.com/AdguardTeam/AdGuardHome/filtering"
"log"
)
func main() {
filter := filtering.New()
filter.EnableSafeBrowsing()
host := "wmconvirus.narod.ru" // hostname for testing safebrowsing
res, err := filter.CheckHost(host)
if err != nil {
// temporary failure
log.Fatalf("Failed to check host %q: %s", host, err)
}
if res.IsFiltered {
log.Printf("Host %s is filtered, reason - %q, matched rule: %q", host, res.Reason, res.Rule)
} else {
log.Printf("Host %s is not filtered, reason - %q", host, res.Reason)
}
}
```

15
internal/next/changelog.md
View file

@ -1,15 +1,17 @@
# AdGuard Home v0.108.0 Changelog DRAFT # AdGuard Home v0.108.0 Changelog DRAFT
This changelog should be merged into the main one once the next API matures This changelog should be merged into the main one once the next API matures enough.
enough.
## [v0.108.0] - TODO ## [v0.108.0] - TODO
### Added ### Added
- The ability to change the port of the pprof debug API. - The ability to change the port of the pprof debug API.
- The ability to log to stderr using `--logFile=stderr`. - The ability to log to stderr using `--logFile=stderr`.
- The new `--web-addr` flag to set the Web UI address in a `host:port` form. - The new `--web-addr` flag to set the Web UI address in a `host:port` form.
- `SIGHUP` now reloads all configuration from the configuration file ([#5676]). - `SIGHUP` now reloads all configuration from the configuration file ([#5676]).
### Changed ### Changed
@ -20,20 +22,21 @@ enough.
#### Other changes #### Other changes
- `-h` is now an alias for `--help` instead of the removed `--host`, see below. - `-h` is now an alias for `--help` instead of the removed `--host`, see below. Use `--web-addr=host:port` to set an address on which to serve the Web UI.
Use `--web-addr=host:port` to set an address on which to serve the Web UI.
### Fixed ### Fixed
- `--check-config` breaking the configuration file ([#4067]). - `--check-config` breaking the configuration file ([#4067]).
- Inconsistent application of `--work-dir/-w` ([#2598], [#2902]). - Inconsistent application of `--work-dir/-w` ([#2598], [#2902]).
- The order of `-v/--verbose` and `--version` being significant ([#2893]). - The order of `-v/--verbose` and `--version` being significant ([#2893]).
### Removed ### Removed
- The deprecated `--no-mem-optimization` and `--no-etc-hosts` flags. - The deprecated `--no-mem-optimization` and `--no-etc-hosts` flags.
- `--host` and `-p/--port` flags. Use `--web-addr=host:port` to set an address
on which to serve the Web UI. `-h` is now an alias for `--help`, see above. - `--host` and `-p/--port` flags. Use `--web-addr=host:port` to set an address on which to serve the Web UI. `-h` is now an alias for `--help`, see above.
[#2598]: https://github.com/AdguardTeam/AdGuardHome/issues/2598 [#2598]: https://github.com/AdguardTeam/AdGuardHome/issues/2598
[#2893]: https://github.com/AdguardTeam/AdGuardHome/issues/2893 [#2893]: https://github.com/AdguardTeam/AdGuardHome/issues/2893

30
openapi/CHANGELOG.md
View file

@ -55,9 +55,9 @@
### The new fields `"upstreams_cache_enabled"` and `"upstreams_cache_size"` in `Client` object ### The new fields `"upstreams_cache_enabled"` and `"upstreams_cache_size"` in `Client` object
- The new field `"upstreams_cache_enabled"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods shows if client's DNS cache is enabled for the client. If not set AdGuard Home will use default value (false). - The new field `"upstreams_cache_enabled"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods shows if client’s DNS cache is enabled for the client. If not set AdGuard Home will use default value (false).
- The new field `"upstreams_cache_size"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods is the size of client's DNS cache in bytes. - The new field `"upstreams_cache_size"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods is the size of client’s DNS cache in bytes.
### The new field `"ratelimit_subnet_len_ipv4"` in `DNSConfig` object ### The new field `"ratelimit_subnet_len_ipv4"` in `DNSConfig` object
@ -218,7 +218,7 @@ The new field `blocked_services_schedule` has been added to JSON objects. It ha
- The `GET /control/stats_info` HTTP API; use the new `GET /control/stats/config` API instead. - The `GET /control/stats_info` HTTP API; use the new `GET /control/stats/config` API instead.
**NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/stats/config/update` and it's not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons. **NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/stats/config/update` and it’s not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons.
- The `POST /control/stats_config` HTTP API; use the new `PUT /control/stats/config/update` API instead. - The `POST /control/stats_config` HTTP API; use the new `PUT /control/stats/config/update` API instead.
@ -244,7 +244,7 @@ These `control/stats/config/update` and `control/stats/config` APIs accept and r
- The `GET /control/querylog_info` HTTP API; use the new `GET /control/querylog/config` API instead. - The `GET /control/querylog_info` HTTP API; use the new `GET /control/querylog/config` API instead.
**NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/querylog/config/update` and it's not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons. **NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/querylog/config/update` and it’s not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons.
- The `POST /control/querylog_config` HTTP API; use the new `PUT /control/querylog/config/update` API instead. - The `POST /control/querylog_config` HTTP API; use the new `PUT /control/querylog/config/update` API instead.
@ -501,7 +501,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
- Value of `-1` is now used for rules generated from the operating system hosts files. - Value of `-1` is now used for rules generated from the operating system hosts files.
- Value of `-2` is now used for blocked services' rules. - Value of `-2` is now used for blocked services’ rules.
- Value of `-3` is now used for rules generated by parental control web service. - Value of `-3` is now used for rules generated by parental control web service.
@ -511,7 +511,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
### New possible value of `"name"` field in `QueryLogItemClient` ### New possible value of `"name"` field in `QueryLogItemClient`
- The value of `"name"` field in `GET /control/querylog` method is never empty, either persistent client's name or runtime client's hostname. - The value of `"name"` field in `GET /control/querylog` method is never empty, either persistent client’s name or runtime client’s hostname.
### Lists in `AccessList` ### Lists in `AccessList`
@ -531,7 +531,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
### New possible value of `"interval"` field in `QueryLogConfig` ### New possible value of `"interval"` field in `QueryLogConfig`
- The value of `"interval"` field in `POST /control/querylog_config` and `GET /control/querylog_info` methods could now take the value of `0.25`. It's equal to 6 hours. - The value of `"interval"` field in `POST /control/querylog_config` and `GET /control/querylog_info` methods could now take the value of `0.25`. It’s equal to 6 hours.
- All the possible values of `"interval"` field are enumerated. - All the possible values of `"interval"` field are enumerated.
@ -543,7 +543,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
### The new field `"unicode_name"` in `DNSQuestion` ### The new field `"unicode_name"` in `DNSQuestion`
- The new optional field `"unicode_name"` is the Unicode representation of question's domain name. It is only presented if the original question's domain name is an IDN. - The new optional field `"unicode_name"` is the Unicode representation of question’s domain name. It is only presented if the original question’s domain name is an IDN.
### Documentation fix of `DNSQuestion` ### Documentation fix of `DNSQuestion`
@ -555,11 +555,11 @@ Previously, the API accepted the name of the network interface as a plain-text s
### `POST /control/dhcp/reset_leases` ### `POST /control/dhcp/reset_leases`
- The new `POST /control/dhcp/reset_leases` HTTP API allows removing all leases from the DHCP server's database without erasing its configuration. - The new `POST /control/dhcp/reset_leases` HTTP API allows removing all leases from the DHCP server’s database without erasing its configuration.
### The parameter `"host"` in `GET /apple/*.mobileconfig` is now required ### The parameter `"host"` in `GET /apple/*.mobileconfig` is now required
- The parameter `"host"` in `GET` requests for `/apple/doh.mobileconfig` and `/apple/doh.mobileconfig` is now required to prevent unexpected server name's value. - The parameter `"host"` in `GET` requests for `/apple/doh.mobileconfig` and `/apple/doh.mobileconfig` is now required to prevent unexpected server name’s value.
### The new field `"default_local_ptr_upstreams"` in `GET /control/dns_info` ### The new field `"default_local_ptr_upstreams"` in `GET /control/dns_info`
@ -589,7 +589,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
### New fields `"resolve_clients"` and `"local_ptr_upstreams"` in DNS configuration ### New fields `"resolve_clients"` and `"local_ptr_upstreams"` in DNS configuration
- The new optional field `"resolve_clients"` of `DNSConfig` is used to turn resolving clients' addresses on and off. - The new optional field `"resolve_clients"` of `DNSConfig` is used to turn resolving clients’ addresses on and off.
- The new optional field `"local_ptr_upstreams"` of `"DNSConfig"` contains the upstream servers for resolving addresses from locally-served networks. The empty `"local_ptr_resolvers"` states that AGH should use resolvers provided by the operating system. - The new optional field `"local_ptr_upstreams"` of `"DNSConfig"` contains the upstream servers for resolving addresses from locally-served networks. The empty `"local_ptr_resolvers"` states that AGH should use resolvers provided by the operating system.
@ -615,7 +615,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
### Multiple matched rules in `GET /filtering/check_host` and `GET /querylog` ### Multiple matched rules in `GET /filtering/check_host` and `GET /querylog`
- The properties `rule` and `filter_id` are now deprecated. API users should inspect the newly-added `rules` object array instead. For most rules, it's either empty or contains one object, which contains the same things as the old two properties did, but under more correct names: - The properties `rule` and `filter_id` are now deprecated. API users should inspect the newly-added `rules` object array instead. For most rules, it’s either empty or contains one object, which contains the same things as the old two properties did, but under more correct names:
```js ```js
{ {
@ -678,7 +678,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
- Added optional "offset" and "limit" parameters. - Added optional "offset" and "limit" parameters.
We are still using "older_than" approach in AdGuard Home UI, but we realize that it's easier to use offset/limit so here is this option now. We are still using "older_than" approach in AdGuard Home UI, but we realize that it’s easier to use offset/limit so here is this option now.
## v0.102: API changes ## v0.102: API changes
@ -914,9 +914,9 @@ Replaces the `POST /control/enable_protection` and `POST /control/disable_protec
### A note about web user authentication ### A note about web user authentication
If AdGuard Home's web user is password-protected, a web client must use authentication mechanism when sending requests to server. Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests: If AdGuard Home’s web user is password-protected, a web client must use authentication mechanism when sending requests to server. Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests:
```none ```http
Authorization: Basic BASE64_DATA Authorization: Basic BASE64_DATA
``` ```

24
openapi/README.md
View file

@ -1,35 +1,27 @@
# AdGuard Home OpenAPI # AdGuard Home OpenAPI
We are using We are using [OpenAPI specification](https://swagger.io/docs/specification/about/) to generate AdGuard Home API specification.
[OpenAPI specification](https://swagger.io/docs/specification/about/)
to generate AdGuard Home API specification.
## How To Edit The API Spec ## How to edit the API spec
The easiest way would be to use The easiest way would be to use [Swagger Editor](http://editor.swagger.io/) and just copy/paste the YAML file there.
[Swagger Editor](http://editor.swagger.io/)
and just copy/paste the YAML file there.
## How To Read The API Doc ## How to read the API doc
1. `yarn install` 1. `yarn install`
2. `yarn start` 2. `yarn start`
3. Open `http://localhost:4000/` 3. open `http://localhost:4000/`
## Changelog ## Changelog
[Here](CHANGELOG.md) we keep track of all non-compatible changes that are being [Here](CHANGELOG.md) we keep track of all non-compatible changes that are being made.
made.
## Authentication ## Authentication
If AdGuard Home's web user is password-protected, a web client must use If AdGuard Home’s web user is password-protected, a web client must use authentication mechanism when sending requests to server. Basic access authentication is the most simple method: a client must pass `Authorization` HTTP header along with all requests:
authentication mechanism when sending requests to server. Basic access
authentication is the most simple method - a client must pass `Authorization`
HTTP header along with all requests:
```http ```http
Authorization: Basic BASE64_DATA Authorization: Basic BASE64_DATA
``` ```
Where BASE64_DATA is base64-encoded data for `username:password` string. Where `BASE64_DATA` is base64-encoded data for `username:password` string.

284
scripts/README.md
View file

@ -1,96 +1,72 @@
# AdGuard Home Scripts # AdGuard Home scripts
## `hooks/`: Git Hooks ## `hooks/`: Git hooks
### Usage ### Usage
Run `make init` from the project root. Run `make init` from the project root.
## `querylog/`: Query Log Helpers
### Usage
## `querylog/`: Query Log Helpers - `npm install`: install dependencies. Run this first.
### Usage - `npm run anonymize <source> <dst>`: read the query log from the `<source>` and write anonymized version to `<dst>`.
* `npm install`: install dependencies. Run this first. ## `make/`: Makefile scripts
* `npm run anonymize <source> <dst>`: read the query log from the `<source>`
and write anonymized version to `<dst>`.
The release channels are: `development` (the default), `edge`, `beta`, and `release`. If verbosity levels aren’t documented here, there are only two: `0`, don’t print anything, and `1`, be verbose.
### `build-docker.sh`: Build a multi-architecture Docker image
## `make/`: Makefile scripts
The release channels are: `development` (the default), `edge`, `beta`, and
`release`. If verbosity levels aren't documented here, there are only two: `0`,
don't print anything, and `1`, be verbose.
### `build-docker.sh`: Build a multi-architecture Docker image
Required environment: Required environment:
* `CHANNEL`: release channel, see above. - `CHANNEL`: release channel, see above.
* `DIST_DIR`: the directory where a release has previously been built. - `DIST_DIR`: the directory where a release has previously been built.
* `REVISION`: current Git revision. - `REVISION`: current Git revision.
* `VERSION`: release version. - `VERSION`: release version.
Optional environment: Optional environment:
* `DOCKER_IMAGE_NAME`: the name of the resulting Docker container. By default - `DOCKER_IMAGE_NAME`: the name of the resulting Docker container. By default it’s `adguardhome-dev`.
it's `adguardhome-dev`.
* `DOCKER_OUTPUT`: the `--output` parameters. By default they are - `DOCKER_OUTPUT`: the `--output` parameters. By default they are `type=image,name=${DOCKER_IMAGE_NAME},push=false`.
`type=image,name=${DOCKER_IMAGE_NAME},push=false`.
* `SUDO`: allow users to use `sudo` or `doas` with `docker`. By default none - `SUDO`: allow users to use `sudo` or `doas` with `docker`. By default none is used.
is used.
### `build-release.sh`: Build a release for all platforms
### `build-release.sh`: Build a release for all platforms
Required environment: Required environment:
* `CHANNEL`: release channel, see above. - `CHANNEL`: release channel, see above.
* `GPG_KEY` and `GPG_KEY_PASSPHRASE`: data for `gpg`. Only required if `SIGN` - `GPG_KEY` and `GPG_KEY_PASSPHRASE`: data for `gpg`. Only required if `SIGN` is `1`.
is `1`.
Optional environment: Optional environment:
* `ARCH` and `OS`: space-separated list of architectures and operating systems - `ARCH` and `OS`: space-separated list of architectures and operating systems for which to build a release. For example, to build only for 64-bit ARM and AMD on Linux and Darwin:
for which to build a release. For example, to build only for 64-bit ARM and
AMD on Linux and Darwin:
```sh ```sh
make ARCH='amd64 arm64' OS='darwin linux' … build-release make ARCH='amd64 arm64' OS='darwin linux' … build-release
``` ```
The default value is `''`, which means build everything. The default value is `''`, which means build everything.
* `DIST_DIR`: the directory to build a release into. The default value is - `DIST_DIR`: the directory to build a release into. The default value is `dist`.
`dist`.
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `SIGN`: `0` to not sign the resulting packages, `1` to sign. The default - `SIGN`: `0` to not sign the resulting packages, `1` to sign. The default value is `1`.
value is `1`.
* `VERBOSE`: `1` to be verbose, `2` to also print environment. This script - `VERBOSE`: `1` to be verbose, `2` to also print environment. This script calls `go-build.sh` with the verbosity level one level lower, so to get verbosity level `2` in `go-build.sh`, set this to `3` when calling `build-release.sh`.
calls `go-build.sh` with the verbosity level one level lower, so to get
verbosity level `2` in `go-build.sh`, set this to `3` when calling
`build-release.sh`.
* `VERSION`: release version. Will be set by `version.sh` if it is unset or - `VERSION`: release version. Will be set by `version.sh` if it is unset or if it has the default `Makefile` value of `v0.0.0`.
if it has the default `Makefile` value of `v0.0.0`.
We're using Go's [forward compatibility mechanism][go-toolchain] for updating We’re using Go’s [forward compatibility mechanism][go-toolchain] for updating the Go version. This means that if your `go` version is 1.21+ but is different from the one required by AdGuard Home, the `go` tool will automatically download the required version.
the Go version. This means that if your `go` version is 1.21+ but is different
from the one required by AdGuard Home, the `go` tool will automatically download
the required version.
If you want to use the version installed on your builder, run: If you want to use the version installed on your builder, run:
@ -103,220 +79,164 @@ and call `make` with `GOTOOLCHAIN=local`.
[go-toolchain]: https://go.dev/blog/toolchain [go-toolchain]: https://go.dev/blog/toolchain
### `go-bench.sh`: Run backend benchmarks
### `go-bench.sh`: Run backend benchmarks
Optional environment: Optional environment:
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is - `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is `--timeout=30s`.
`--timeout=30s`.
* `VERBOSE`: verbosity level. `1` shows every command that is run and every - `VERBOSE`: verbosity level. `1` shows every command that is run and every Go package that is processed. `2` also shows subcommands and environment. The default value is `0`, don’t be verbose.
Go package that is processed. `2` also shows subcommands and environment.
The default value is `0`, don't be verbose.
### `go-build.sh`: Build the backend
### `go-build.sh`: Build the backend
Optional environment: Optional environment:
* `GOAMD64`: architectural level for [AMD64][amd64]. The default value is - `GOAMD64`: architectural level for [AMD64][amd64]. The default value is `v1`.
`v1`.
* `GOARM`: ARM processor options for the Go compiler. - `GOARM`: ARM processor options for the Go compiler.
* `GOMIPS`: ARM processor options for the Go compiler. - `GOMIPS`: ARM processor options for the Go compiler.
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `OUT`: output binary name. - `OUT`: output binary name.
* `PARALLELISM`: set the maximum number of concurrently run build commands - `PARALLELISM`: set the maximum number of concurrently run build commands (that is, compiler, linker, etc.).
(that is, compiler, linker, etc.).
* `SOURCE_DATE_EPOCH`: the [standardized][repr] environment variable for the - `SOURCE_DATE_EPOCH`: the [standardized][repr] environment variable for the Unix epoch time of the latest commit in the repository. If set, overrides the default obtained from Git. Useful for reproducible builds.
Unix epoch time of the latest commit in the repository. If set, overrides
the default obtained from Git. Useful for reproducible builds.
* `VERBOSE`: verbosity level. `1` shows every command that is run and every - `VERBOSE`: verbosity level. `1` shows every command that is run and every Go package that is processed. `2` also shows subcommands and environment. The default value is `0`, don’t be verbose.
Go package that is processed. `2` also shows subcommands and environment.
The default value is `0`, don't be verbose.
* `VERSION`: release version. Will be set by `version.sh` if it is unset or - `VERSION`: release version. Will be set by `version.sh` if it is unset or if it has the default `Makefile` value of `v0.0.0`.
if it has the default `Makefile` value of `v0.0.0`.
Required environment: Required environment:
* `CHANNEL`: release channel, see above. - `CHANNEL`: release channel, see above.
[amd64]: https://github.com/golang/go/wiki/MinimumRequirements#amd64 [amd64]: https://github.com/golang/go/wiki/MinimumRequirements#amd64
[repr]: https://reproducible-builds.org/docs/source-date-epoch/ [repr]: https://reproducible-builds.org/docs/source-date-epoch/
### `go-deps.sh`: Install backend dependencies
### `go-deps.sh`: Install backend dependencies
Optional environment: Optional environment:
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `VERBOSE`: verbosity level. `1` shows every command that is run and every - `VERBOSE`: verbosity level. `1` shows every command that is run and every Go package that is processed. `2` also shows subcommands and environment. The default value is `0`, don’t be verbose.
Go package that is processed. `2` also shows subcommands and environment.
The default value is `0`, don't be verbose.
### `go-fuzz.sh`: Run backend fuzz tests
### `go-fuzz.sh`: Run backend fuzz tests
Optional environment: Optional environment:
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `FUZZTIME_FLAGS`: set fuss flags for tests. The default value is - `FUZZTIME_FLAGS`: set fuss flags for tests. The default value is `--fuzztime=20s`.
`--fuzztime=20s`.
* `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is - `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is `--timeout=30s`.
`--timeout=30s`.
* `VERBOSE`: verbosity level. `1` shows every command that is run and every - `VERBOSE`: verbosity level. `1` shows every command that is run and every Go package that is processed. `2` also shows subcommands and environment. The default value is `0`, don’t be verbose.
Go package that is processed. `2` also shows subcommands and environment.
The default value is `0`, don't be verbose.
### `go-lint.sh`: Run backend static analyzers
Don’t forget to run `make go-tools` once first!
### `go-lint.sh`: Run backend static analyzers
Don't forget to run `make go-tools` once first!
Optional environment: Optional environment:
* `EXIT_ON_ERROR`: if set to `0`, don't exit the script after the first - `EXIT_ON_ERROR`: if set to `0`, don’t exit the script after the first encountered error. The default value is `1`.
encountered error. The default value is `1`.
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `VERBOSE`: verbosity level. `1` shows every command that is run. `2` also - `VERBOSE`: verbosity level. `1` shows every command that is run. `2` also shows subcommands. The default value is `0`, don’t be verbose.
shows subcommands. The default value is `0`, don't be verbose.
### `go-test.sh`: Run backend tests
### `go-test.sh`: Run backend tests
Optional environment: Optional environment:
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
* `RACE`: set to `0` to not use the Go race detector. The default value is - `RACE`: set to `0` to not use the Go race detector. The default value is `1`, use the race detector.
`1`, use the race detector.
* `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is - `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is `--timeout=30s`.
`--timeout=30s`.
* `VERBOSE`: verbosity level. `1` shows every command that is run and every - `VERBOSE`: verbosity level. `1` shows every command that is run and every Go package that is processed. `2` also shows subcommands. The default value is `0`, don’t be verbose.
Go package that is processed. `2` also shows subcommands. The default
value is `0`, don't be verbose.
### `go-tools.sh`: Install backend tooling
Installs the Go static analysis and other tools into `${PWD}/bin`. Either add `${PWD}/bin` to your `$PATH` before all other entries, or use the commands directly, or use the commands through `make` (for example, `make go-lint`).
### `go-tools.sh`: Install backend tooling
Installs the Go static analysis and other tools into `${PWD}/bin`. Either add
`${PWD}/bin` to your `$PATH` before all other entries, or use the commands
directly, or use the commands through `make` (for example, `make go-lint`).
Optional environment: Optional environment:
* `GO`: set an alternative name for the Go compiler. - `GO`: set an alternative name for the Go compiler.
### `version.sh`: Generate And Print The Current Version
### `version.sh`: Generate And Print The Current Version
Required environment: Required environment:
* `CHANNEL`: release channel, see above. - `CHANNEL`: release channel, see above.
## `snap/`: Snapcraft scripts
### `build.sh`
## `snap/`: Snapcraft scripts
### `build.sh`
Builds the Snapcraft packages from the binaries created by `download.sh`. Builds the Snapcraft packages from the binaries created by `download.sh`.
### `download.sh` ### `download.sh`
Downloads the binaries to pack them into Snapcraft packages. Downloads the binaries to pack them into Snapcraft packages.
Required environment: Required environment:
* `CHANNEL`: release channel, see above. - `CHANNEL`: release channel, see above.
### `upload.sh` ### `upload.sh`
Uploads the Snapcraft packages created by `build.sh`. Uploads the Snapcraft packages created by `build.sh`.
Required environment: Required environment:
* `SNAPCRAFT_CHANNEL`: Snapcraft release channel: `edge`, `beta`, or - `SNAPCRAFT_CHANNEL`: Snapcraft release channel: `edge`, `beta`, or `candidate`.
`candidate`.
* `SNAPCRAFT_STORE_CREDENTIALS`: Credentials for Snapcraft store. - `SNAPCRAFT_STORE_CREDENTIALS`: Credentials for Snapcraft store.
Optional environment: Optional environment:
* `SNAPCRAFT_CMD`: Overrides the Snapcraft command. Default: `snapcraft`. - `SNAPCRAFT_CMD`: Overrides the Snapcraft command. Default: `snapcraft`.
## `translations/`: Twosky Integration Script
### Usage
## `translations/`: Twosky Integration Script - `go run ./scripts/translations help`: print usage.
### Usage - `go run ./scripts/translations download [-n <count>]`: download and save all translations. `n` is optional flag where count is a number of concurrent downloads.
* `go run ./scripts/translations help`: print usage. - `go run ./scripts/translations upload`: upload the base `en` locale.
* `go run ./scripts/translations download [-n <count>]`: download and save - `go run ./scripts/translations summary`: show the current locales summary.
all translations. `n` is optional flag where count is a number of
concurrent downloads.
* `go run ./scripts/translations upload`: upload the base `en` locale. - `go run ./scripts/translations unused`: show the list of unused strings.
* `go run ./scripts/translations summary`: show the current locales summary. - `go run ./scripts/translations auto-add`: add locales with additions to the git and restore locales with deletions.
* `go run ./scripts/translations unused`: show the list of unused strings. After the download you’ll find the output locales in the `client/src/__locales/` directory.
* `go run ./scripts/translations auto-add`: add locales with additions to the
git and restore locales with deletions.
After the download you'll find the output locales in the `client/src/__locales/`
directory.
Optional environment: Optional environment:
* `DOWNLOAD_LANGUAGES`: set a list of specific languages to `download`. For - `DOWNLOAD_LANGUAGES`: set a list of specific languages to `download`. For example `ar be bg`. If it set to `blocker` then script will download only those languages, which need to be fully translated (`de en es fr it ja ko pt-br pt-pt ru zh-cn zh-tw`).
example `ar be bg`. If it set to `blocker` then script will download only
those languages, which need to be fully translated (`de en es fr it ja ko
pt-br pt-pt ru zh-cn zh-tw`).
* `UPLOAD_LANGUAGE`: set an alternative language for `upload`. - `UPLOAD_LANGUAGE`: set an alternative language for `upload`.
* `TWOSKY_URI`: set an alternative URL for `download` or `upload`. - `TWOSKY_URI`: set an alternative URL for `download` or `upload`.
* `TWOSKY_PROJECT_ID`: set an alternative project ID for `download` or - `TWOSKY_PROJECT_ID`: set an alternative project ID for `download` or `upload`.
`upload`.
## `companiesdb/`: Whotracks.me database converter
A simple script that downloads and updates the companies DB in the `client` code from [the repo][companiesrepo].
## `companiesdb/`: Whotracks.me Database Converter ### Usage
A simple script that downloads and updates the companies DB in the `client`
code from [the repo][companiesrepo].
### Usage
```sh ```sh
sh ./scripts/companiesdb/download.sh sh ./scripts/companiesdb/download.sh
@ -324,19 +244,15 @@ sh ./scripts/companiesdb/download.sh
[companiesrepo]: https://github.com/AdguardTeam/companiesdb [companiesrepo]: https://github.com/AdguardTeam/companiesdb
## `blocked-services/`: Blocked-services updater
A simple script that downloads and updates the blocked services index from AdGuard’s [Hostlists Registry][reg].
## `blocked-services/`: Blocked Services Updater
A simple script that downloads and updates the blocked services index from
AdGuard's [Hostlists Registry][reg].
Optional environment: Optional environment:
* `URL`: the URL of the index file. By default it's - `URL`: the URL of the index file. By default it’s `https://adguardteam.github.io/HostlistsRegistry/assets/services.json`.
`https://adguardteam.github.io/HostlistsRegistry/assets/services.json`.
### Usage ### Usage
```sh ```sh
go run ./scripts/blocked-services/main.go go run ./scripts/blocked-services/main.go
@ -344,19 +260,15 @@ go run ./scripts/blocked-services/main.go
[reg]: https://github.com/AdguardTeam/HostlistsRegistry [reg]: https://github.com/AdguardTeam/HostlistsRegistry
## `vetted-filters/`: Vetted-filters updater
Similar to the one above, a script that downloads and updates the vetted filtering list data from AdGuard’s [Hostlists Registry][reg].
## `vetted-filters/`: Vetted Filters Updater
Similar to the one above, a script that downloads and updates the vetted
filtering list data from AdGuard's [Hostlists Registry][reg].
Optional environment: Optional environment:
* `URL`: the URL of the index file. By default it's - `URL`: the URL of the index file. By default it’s `https://adguardteam.github.io/HostlistsRegistry/assets/filters.json`.
`https://adguardteam.github.io/HostlistsRegistry/assets/filters.json`.
### Usage ### Usage
```sh ```sh
go run ./scripts/vetted-filters/main.go go run ./scripts/vetted-filters/main.go

13
scripts/make/md-lint.sh
View file

@ -8,14 +8,21 @@
verbose="${VERBOSE:-0}" verbose="${VERBOSE:-0}"
readonly verbose readonly verbose
set -e -f -u # Don't use -f, because we use globs in this script.
set -e -u
if [ "$verbose" -gt '0' ]; then if [ "$verbose" -gt '0' ]; then
set -x set -x
fi fi
# TODO(e.burkov): Lint allmarkdown documents within this project. # TODO(e.burkov): Add README.md and possibly AGHTechDoc.md.
markdownlint \ markdownlint \
./CHANGELOG.md \ ./CHANGELOG.md \
./openapi/CHANGELOG.md \ ./CONTRIBUTING.md \
./HACKING.md \
./SECURITY.md \
./internal/next/changelog.md \
./internal/dhcpd/*.md \
./openapi/*.md \
./scripts/*.md \
; ;