From 20e56b71719aa9aa74f78851f31a54d27d4d5602 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Thu, 19 Dec 2024 17:17:40 +0300 Subject: [PATCH] Pull request 2326: more-md-lint Merge in DNS/adguard-home from more-md-lint to master Squashed commit of the following: commit 39e7ea3b441ebf48c5b0d5c2b5b85620515bbea3 Author: Ainar Garipov Date: Thu Dec 19 17:03:36 2024 +0300 all: imp docs more commit 7aa08036b239d7eb19f674a6c4bfaf1325ff4bff Author: Ainar Garipov Date: Thu Dec 19 16:08:13 2024 +0300 all: add more docs to lint --- CHANGELOG.md | 96 ++++++------ internal/dhcpd/README.md | 98 ++++++------ internal/filtering/README.md | 70 --------- internal/next/changelog.md | 15 +- openapi/CHANGELOG.md | 30 ++-- openapi/README.md | 24 +-- scripts/README.md | 284 ++++++++++++----------------------- scripts/make/md-lint.sh | 13 +- 8 files changed, 231 insertions(+), 399 deletions(-) delete mode 100644 internal/filtering/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ccb98bf7..cf02db7b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -175,7 +175,7 @@ See also the [v0.107.52 GitHub milestone][ms-v0.107.52]. - 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): @@ -184,7 +184,7 @@ See also the [v0.107.52 GitHub milestone][ms-v0.107.52]. ./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 @@ -216,7 +216,7 @@ See also the [v0.107.51 GitHub milestone][ms-v0.107.51]. ### 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 @@ -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]). -- 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 [#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]). -- 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 [#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 -- 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. @@ -533,7 +533,7 @@ See also the [v0.107.42 GitHub milestone][ms-v0.107.42]. ### 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]). @@ -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. -- 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 @@ -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]). -- 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]). @@ -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. -- 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 @@ -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]). -- 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 [#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]). - **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]). @@ -1178,7 +1178,7 @@ See also the [v0.107.29 GitHub milestone][ms-v0.107.29]. ### 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 @@ -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]). -- 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. @@ -1272,7 +1272,7 @@ In this release, the schema version has changed from 17 to 20. '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 @@ -1302,7 +1302,7 @@ In this release, the schema version has changed from 17 to 20. ### 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 [#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]). -- 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]). @@ -1535,7 +1535,7 @@ See also the [v0.107.22 GitHub milestone][ms-v0.107.22]. ### 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 @@ -1666,7 +1666,7 @@ See also the [v0.107.17 GitHub milestone][ms-v0.107.17]. ### 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. @@ -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]). -- 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]). @@ -1803,7 +1803,7 @@ See also the [v0.107.13 GitHub milestone][ms-v0.107.13]. ### 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 @@ -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 `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. @@ -1851,7 +1851,7 @@ See also the [v0.107.12 GitHub milestone][ms-v0.107.12]. ### 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]). @@ -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]). -- 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]). @@ -2165,7 +2165,7 @@ See also the [v0.107.6 GitHub milestone][ms-v0.107.6]. ### 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 [#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 -- 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]). @@ -2227,7 +2227,7 @@ See also the [v0.107.3 GitHub milestone][ms-v0.107.3]. - 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 [#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]). -- 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 [#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 -- 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. @@ -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]). -- 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]). @@ -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]). -- 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]). -- 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]). @@ -2416,15 +2416,15 @@ In this release, the schema version has changed from 10 to 12. - 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]). - 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]). @@ -2456,7 +2456,7 @@ In this release, the schema version has changed from 10 to 12. - 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]). @@ -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 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]). @@ -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]). -- Comment handling in clients' custom upstreams ([#2947]). +- Comment handling in clients’ custom upstreams ([#2947]). - 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 -- 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]. @@ -2751,7 +2751,7 @@ See also the [v0.105.2 GitHub milestone][ms-v0.105.2]. - 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]). @@ -2784,7 +2784,7 @@ See also the [v0.105.1 GitHub milestone][ms-v0.105.1]. ### 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]). @@ -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]). -- 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]). @@ -2800,7 +2800,7 @@ See also the [v0.105.1 GitHub milestone][ms-v0.105.1]. - 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 [#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]). -- 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]). diff --git a/internal/dhcpd/README.md b/internal/dhcpd/README.md index 8bb51147..18c7d1d7 100644 --- a/internal/dhcpd/README.md +++ b/internal/dhcpd/README.md @@ -1,61 +1,50 @@ - # Testing DHCP Server +# Testing DHCP Server Contents: - * [Test setup with Virtual Box](#vbox) - * [Quick test with DHCPTest](#dhcptest) -## Test setup with Virtual Box +- [Test setup with Virtual Box](#vbox) +- [Quick test with DHCPTest](#dhcptest) - ### Prerequisites +## Test setup with Virtual Box + +### Prerequisites To set up a test environment for DHCP server you will need: - * Linux AG Home host machine (Virtual). - * Virtual Box. - * Virtual machine (guest OS doesn't matter). +- Linux AG Home host machine (Virtual) +- Virtual Box +- 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 - network: +1. Install Virtual Box and run the following command to create a Host-Only network: - ```sh - $ VBoxManage hostonlyif create - ``` + ```sh + 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.* - ``` - File -> Host Network Manager... - ``` +2. Create your virtual machine and set up its network in *VM Settings → Network → Host-only Adapter.* - 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. - ``` - VM Settings -> Network -> Host-only Adapter - ``` +4. To see the current IP addresses on client OS you can use `ip a` command on Linux or `ipconfig` on Windows. - 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. +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. - 4. To see the current IP addresses on client OS you can use `ip a` command on - Linux or `ipconfig` on Windows. +### Configure server - 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. +1. Edit server configuration file `AdGuardHome.yaml`, for example: - ### Configure server - - 1. Edit server configuration file `AdGuardHome.yaml`, for example: - - ```yaml - dhcp: - enabled: true - interface_name: vboxnet0 - local_domain_name: lan - dhcpv4: + ```yaml + dhcp: + enabled: true + interface_name: vboxnet0 + local_domain_name: lan + dhcpv4: gateway_ip: 192.168.56.1 subnet_mask: 255.255.255.0 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 icmp_timeout_msec: 1000 options: [] - dhcpv6: + dhcpv6: range_start: 2001::1 lease_duration: 86400 ra_slaac_only: false ra_allow_slaac: false - ``` + ``` - 2. Start the server +2. Start the server: - ```sh - ./AdGuardHome -v - ``` + ```sh + ./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: - ``` - [info] DHCP: listening on 0.0.0.0:67 - ``` + ```none + [info] dhcpv4: listening + ``` -## Quick test with DHCPTest utility +## Quick test with DHCPTest utility - ### 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 -interactive mode. +The DHCP server could be tested for DISCOVER-OFFER packets with in interactive mode. [dhcptest-gh]: https://github.com/CyberShadow/dhcptest diff --git a/internal/filtering/README.md b/internal/filtering/README.md deleted file mode 100644 index cd3926f0..00000000 --- a/internal/filtering/README.md +++ /dev/null @@ -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) - } -} -``` diff --git a/internal/next/changelog.md b/internal/next/changelog.md index 224184bc..e9c3c10d 100644 --- a/internal/next/changelog.md +++ b/internal/next/changelog.md @@ -1,15 +1,17 @@ # AdGuard Home v0.108.0 Changelog DRAFT -This changelog should be merged into the main one once the next API matures -enough. +This changelog should be merged into the main one once the next API matures enough. ## [v0.108.0] - TODO ### Added - The ability to change the port of the pprof debug API. + - 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. + - `SIGHUP` now reloads all configuration from the configuration file ([#5676]). ### Changed @@ -20,20 +22,21 @@ enough. #### Other changes -- `-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. +- `-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. ### Fixed - `--check-config` breaking the configuration file ([#4067]). + - Inconsistent application of `--work-dir/-w` ([#2598], [#2902]). + - The order of `-v/--verbose` and `--version` being significant ([#2893]). ### Removed - 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 [#2893]: https://github.com/AdguardTeam/AdGuardHome/issues/2893 diff --git a/openapi/CHANGELOG.md b/openapi/CHANGELOG.md index 7a5cc937..f2bd9baf 100644 --- a/openapi/CHANGELOG.md +++ b/openapi/CHANGELOG.md @@ -55,9 +55,9 @@ ### 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 @@ -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. - **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. @@ -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. - **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. @@ -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 `-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. @@ -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` -- 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` @@ -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` -- 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. @@ -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 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` @@ -555,11 +555,11 @@ Previously, the API accepted the name of the network interface as a plain-text s ### `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` 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` @@ -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 -- 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. @@ -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` -- 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 { @@ -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. - 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 @@ -914,9 +914,9 @@ Replaces the `POST /control/enable_protection` and `POST /control/disable_protec ### 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 ``` diff --git a/openapi/README.md b/openapi/README.md index 387bfb0e..c6e05700 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -1,35 +1,27 @@ # AdGuard Home OpenAPI -We are using -[OpenAPI specification](https://swagger.io/docs/specification/about/) -to generate AdGuard Home API specification. +We are using [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 -[Swagger Editor](http://editor.swagger.io/) -and just copy/paste the YAML file there. +The easiest way would be to use [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` 2. `yarn start` -3. Open `http://localhost:4000/` +3. open `http://localhost:4000/` ## Changelog -[Here](CHANGELOG.md) we keep track of all non-compatible changes that are being -made. +[Here](CHANGELOG.md) we keep track of all non-compatible changes that are being made. ## 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: ```http 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. diff --git a/scripts/README.md b/scripts/README.md index 4835fcb2..6b835b7b 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -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. +## `querylog/`: Query Log Helpers +### Usage -## `querylog/`: Query Log Helpers +- `npm install`: install dependencies. Run this first. - ### Usage +- `npm run anonymize `: read the query log from the `` and write anonymized version to ``. - * `npm install`: install dependencies. Run this first. - * `npm run anonymize `: read the query log from the `` - and write anonymized version to ``. +## `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. - -## `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 +### `build-docker.sh`: Build a multi-architecture Docker image 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: - * `DOCKER_IMAGE_NAME`: the name of the resulting Docker container. By default - it's `adguardhome-dev`. +- `DOCKER_IMAGE_NAME`: the name of the resulting Docker container. By default it’s `adguardhome-dev`. - * `DOCKER_OUTPUT`: the `--output` parameters. By default they are - `type=image,name=${DOCKER_IMAGE_NAME},push=false`. +- `DOCKER_OUTPUT`: the `--output` parameters. By default they are `type=image,name=${DOCKER_IMAGE_NAME},push=false`. - * `SUDO`: allow users to use `sudo` or `doas` with `docker`. By default none - is used. +- `SUDO`: allow users to use `sudo` or `doas` with `docker`. By default none is used. - - - ### `build-release.sh`: Build a release for all platforms +### `build-release.sh`: Build a release for all platforms 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` - is `1`. +- `GPG_KEY` and `GPG_KEY_PASSPHRASE`: data for `gpg`. Only required if `SIGN` is `1`. Optional environment: - * `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: +- `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: ```sh make ARCH='amd64 arm64' OS='darwin linux' … build-release ``` + The default value is `''`, which means build everything. - * `DIST_DIR`: the directory to build a release into. The default value is - `dist`. +- `DIST_DIR`: the directory to build a release into. The default value is `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 - value is `1`. +- `SIGN`: `0` to not sign the resulting packages, `1` to sign. The default value is `1`. - * `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`. +- `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`. - * `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`. +- `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`. -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. +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. 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-bench.sh`: Run backend benchmarks +### `go-bench.sh`: Run backend benchmarks 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=30s`. +- `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is `--timeout=30s`. - * `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. +- `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-build.sh`: Build the backend +### `go-build.sh`: Build the backend Optional environment: - * `GOAMD64`: architectural level for [AMD64][amd64]. The default value is - `v1`. +- `GOAMD64`: architectural level for [AMD64][amd64]. The default value is `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 - (that is, compiler, linker, etc.). +- `PARALLELISM`: set the maximum number of concurrently run build commands (that is, compiler, linker, etc.). - * `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. +- `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. - * `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. +- `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. - * `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`. +- `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`. Required environment: - * `CHANNEL`: release channel, see above. +- `CHANNEL`: release channel, see above. [amd64]: https://github.com/golang/go/wiki/MinimumRequirements#amd64 [repr]: https://reproducible-builds.org/docs/source-date-epoch/ - - - ### `go-deps.sh`: Install backend dependencies +### `go-deps.sh`: Install backend dependencies 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 - Go package that is processed. `2` also shows subcommands and environment. - The default value is `0`, don't be verbose. +- `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-fuzz.sh`: Run backend fuzz tests +### `go-fuzz.sh`: Run backend fuzz tests 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=20s`. +- `FUZZTIME_FLAGS`: set fuss flags for tests. The default value is `--fuzztime=20s`. - * `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is - `--timeout=30s`. +- `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is `--timeout=30s`. - * `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. +- `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-lint.sh`: Run backend static analyzers - - ### `go-lint.sh`: Run backend static analyzers - -Don't forget to run `make go-tools` once first! +Don’t forget to run `make go-tools` once first! Optional environment: - * `EXIT_ON_ERROR`: if set to `0`, don't exit the script after the first - encountered error. The default value is `1`. +- `EXIT_ON_ERROR`: if set to `0`, don’t exit the script after the first 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 - shows subcommands. The default value is `0`, don't be verbose. +- `VERBOSE`: verbosity level. `1` shows every command that is run. `2` also 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: - * `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 - `1`, use the race detector. +- `RACE`: set to `0` to not use the Go race detector. The default value is `1`, use the race detector. - * `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is - `--timeout=30s`. +- `TIMEOUT_FLAGS`: set timeout flags for tests. The default value is `--timeout=30s`. - * `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. +- `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-tools.sh`: Install backend tooling - - ### `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`). +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: - * `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: - * `CHANNEL`: release channel, see above. +- `CHANNEL`: release channel, see above. +## `snap/`: Snapcraft scripts - -## `snap/`: Snapcraft scripts - - ### `build.sh` +### `build.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. Required environment: - * `CHANNEL`: release channel, see above. +- `CHANNEL`: release channel, see above. - ### `upload.sh` +### `upload.sh` Uploads the Snapcraft packages created by `build.sh`. Required environment: - * `SNAPCRAFT_CHANNEL`: Snapcraft release channel: `edge`, `beta`, or - `candidate`. +- `SNAPCRAFT_CHANNEL`: Snapcraft release channel: `edge`, `beta`, or `candidate`. - * `SNAPCRAFT_STORE_CREDENTIALS`: Credentials for Snapcraft store. +- `SNAPCRAFT_STORE_CREDENTIALS`: Credentials for Snapcraft store. 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 ]`: 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 ]`: download and save - all translations. `n` is optional flag where count is a number of - concurrent downloads. +- `go run ./scripts/translations summary`: show the current locales summary. - * `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. - - * `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. +After the download you’ll find the output locales in the `client/src/__locales/` directory. Optional environment: - * `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`). +- `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`). - * `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 - `upload`. +- `TWOSKY_PROJECT_ID`: set an alternative project ID for `download` or `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 - -A simple script that downloads and updates the companies DB in the `client` -code from [the repo][companiesrepo]. - - ### Usage +### Usage ```sh sh ./scripts/companiesdb/download.sh @@ -324,19 +244,15 @@ sh ./scripts/companiesdb/download.sh [companiesrepo]: https://github.com/AdguardTeam/companiesdb +## `blocked-services/`: Blocked-services updater - -## `blocked-services/`: Blocked Services Updater - -A simple script that downloads and updates the blocked services index from -AdGuard's [Hostlists Registry][reg]. +A simple script that downloads and updates the blocked services index from AdGuard’s [Hostlists Registry][reg]. Optional environment: - * `URL`: the URL of the index file. By default it's - `https://adguardteam.github.io/HostlistsRegistry/assets/services.json`. +- `URL`: the URL of the index file. By default it’s `https://adguardteam.github.io/HostlistsRegistry/assets/services.json`. - ### Usage +### Usage ```sh go run ./scripts/blocked-services/main.go @@ -344,19 +260,15 @@ go run ./scripts/blocked-services/main.go [reg]: https://github.com/AdguardTeam/HostlistsRegistry +## `vetted-filters/`: Vetted-filters updater - -## `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]. +Similar to the one above, a script that downloads and updates the vetted filtering list data from AdGuard’s [Hostlists Registry][reg]. Optional environment: - * `URL`: the URL of the index file. By default it's - `https://adguardteam.github.io/HostlistsRegistry/assets/filters.json`. +- `URL`: the URL of the index file. By default it’s `https://adguardteam.github.io/HostlistsRegistry/assets/filters.json`. - ### Usage +### Usage ```sh go run ./scripts/vetted-filters/main.go diff --git a/scripts/make/md-lint.sh b/scripts/make/md-lint.sh index e80d595a..a59e9c16 100644 --- a/scripts/make/md-lint.sh +++ b/scripts/make/md-lint.sh @@ -8,14 +8,21 @@ verbose="${VERBOSE:-0}" 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 set -x fi -# TODO(e.burkov): Lint allmarkdown documents within this project. +# TODO(e.burkov): Add README.md and possibly AGHTechDoc.md. markdownlint \ ./CHANGELOG.md \ - ./openapi/CHANGELOG.md \ + ./CONTRIBUTING.md \ + ./HACKING.md \ + ./SECURITY.md \ + ./internal/next/changelog.md \ + ./internal/dhcpd/*.md \ + ./openapi/*.md \ + ./scripts/*.md \ ;