mirror/AdGuardDNS

Fork 0

mirror of https://github.com/AdguardTeam/AdGuardDNS.git synced 2026-01-19 04:28:30 -05:00

Files

Andrey Meshkov b6a98906a5 Sync v2.0

2022-08-26 14:18:35 +03:00

7.3 KiB

Raw Permalink Blame History

AdGuard DNS Development Setup

Development is supported on Linux and macOS (aka Darwin) systems.

Install Go 1.18 or later.
Call make init to set up the Git pre-commit hook.
Call make go-tools to install analyzers and other tools into the bin directory.

Common Makefile Macros And Targets

Most development tasks are done through the use of our Makefile. Please keep the Makefile POSIX-compliant and portable.

Macros

This is not an extensive list. See ../Makefile and the scripts in the ../scripts/make/ directory.

OUT: The name of the binary to build. Default: ./AdGuardDNS.
RACE: Set to 1 to enable the race detector. The race detector is always enabled for make go-test.
VERBOSE: Set to 1 to enable verbose mode. Default: 0.

Targets

This is not an extensive list. See ../Makefile.

make init: Set up the pre-commit hook that runs checks, linters, and tests.
make go-build: Build the binary. See also the OUT and RACE macros.
make go-gen: Regenerate the automatically generated Go files. Those generated files are ../internal/agd/country_generate.go and ../internal/geoip/asntops_generate.go. They need to be periodically updated.
make go-lint: Run Go checkers and static analysis.
make go-test: Run Go tests.
make go-bench: Run Go benchmarks.
make go-tools: Install the Go static analysis tools locally.
make test: Currently does the same thing as make go-test but is defined both because it's a common target and also in case code in another language appears in the future.
make txt-lint: Run plain text checkers.

How To Run AdGuard DNS

This is an example on how to run AdGuard DNS locally.

Step 1: Prepare The TLS Certificate And The Key

Keeping the test files in the test directory since it's added to .gitignore:

mkdir test
cd test

Generate the TLS certificate and the key:

openssl req -nodes -new -x509 -keyout cert.key -out cert.crt

Also, generate TLS session tickets:

openssl rand 32 > ./tls_key_1
openssl rand 32 > ./tls_key_2

Step 2: Prepare The DNSCrypt Configuration

Install the dnscrypt tool:

On macOS, install from Brew:
```
brew install ameshkov/tap/dnscrypt
```
On other unixes, such as Linux, download and install the latest release manually.

Then, generate the configuration:

dnscrypt generate -p testdns -o ./dnscrypt.yml

Step 3: Prepare The Configuration File

cd ../
cp -f config.dist.yml config.yml

Step 4: Prepare The Test Data

echo '<html><body>Dangerous content ahead</body></html>' > ./test/block_page_sb.html
echo '<html><body>Adult content ahead</body></html>' > ./test/block_page_adult.html
echo '<html><body>Error 404</body></html>' > ./test/error_404.html
echo '<html><body>Error 500</body></html>' > ./test/error_500.html

Step 5: Compile AdGuard DNS

make build

Step 6: Prepare Cache Data And GeoIP

We'll use the test versions of the GeoIP databases here.

rm -f -r ./test/cache/
mkdir ./test/cache
curl 'https://raw.githubusercontent.com/maxmind/MaxMind-DB/main/test-data/GeoIP2-Country-Test.mmdb' -o ./test/GeoIP2-Country-Test.mmdb
curl 'https://raw.githubusercontent.com/maxmind/MaxMind-DB/main/test-data/GeoLite2-ASN-Test.mmdb' -o ./test/GeoLite2-ASN-Test.mmdb

Step 7: Run AdGuard DNS

You'll need to supply the following:

BACKEND_ENDPOINT
CONSUL_ALLOWLIST_URL
GENERAL_SAFE_SEARCH_URL
YOUTUBE_SAFE_SEARCH_URL

See the external HTTP API documentation.

You may need to change the listen ports in config.yml which are less than 1024 to some other ports. Otherwise, sudo or doas is required to run AdGuardDNS.

Examples below are for the configuration with the following changes:

Plain DNS: 53 → 5354
DoT: 853 → 8853
DoH: 443 → 8443
DoQ: 853 → 8853

env \
    BACKEND_ENDPOINT='PUT BACKEND URL HERE' \
    BLOCKED_SERVICE_INDEX_URL='https://atropnikov.github.io/HostlistsRegistry/assets/services.json'\
    CONSUL_ALLOWLIST_URL='PUT CONSUL ALLOWLIST URL HERE' \
    CONFIG_PATH='./config.yml' \
    DNSDB_PATH='./test/cache/dnsdb.bolt' \
    FILTER_INDEX_URL='https://atropnikov.github.io/HostlistsRegistry/assets/filters.json' \
    FILTER_CACHE_PATH='./test/cache' \
    GENERAL_SAFE_SEARCH_URL='https://adguardteam.github.io/HostlistsRegistry/assets/engines_safe_search.txt' \
    GEOIP_ASN_PATH='./test/GeoLite2-ASN-Test.mmdb' \
    GEOIP_COUNTRY_PATH='./test/GeoIP2-Country-Test.mmdb' \
    QUERYLOG_PATH='./test/cache/querylog.jsonl' \
    LISTEN_ADDR='127.0.0.1' \
    LISTEN_PORT='8081' \
    RULESTAT_URL='https://testchrome.adtidy.org/api/1.0/rulestats.html' \
    SENTRY_DSN='https://1:1@localhost/1' \
    VERBOSE='1' \
    YOUTUBE_SAFE_SEARCH_URL='https://adguardteam.github.io/HostlistsRegistry/assets/youtube_safe_search.txt' \
    ./AdGuardDNS

Step 8: Test Your Instance

Plain DNS:

dnslookup example.org 127.0.0.1:5354

DoT:

VERIFY=0 dnslookup example.org tls://127.0.0.1:8853

DoH:

VERIFY=0 dnslookup example.org https://127.0.0.1:8443/dns-query

DoQ:

VERIFY=0 dnslookup example.org quic://127.0.0.1:8853

Open http://127.0.0.1:8081/metrics to see the server's metrics.

DNSCrypt is a bit trickier. You need to open dnscrypt.yml and use values from there to generate an SDNS stamp on https://dnscrypt.info/stamps.

NOTE: The example below is for a test configuration that won't work for you.

dnslookup example.org sdns://AQcAAAAAAAAADjEyNy4wLjAuMTo1NDQzIAbKgP3dmXybr1DaKIFgKjsc8zSFX4rgT_hFgymSq6w1FzIuZG5zY3J5cHQtY2VydC50ZXN0ZG5z

7.3 KiB Raw Permalink Blame History

AdGuard DNS Development Setup

7.3 KiB

Raw Permalink Blame History