dns-bench

dns-bench is a Rust-based command-line tool designed to benchmark DNS server performance. It iterates through a built-in list of public DNS servers, automatically detects your system's configured DNS servers, and attempts to detect your default gateway (router) DNS endpoint. It measures response times and outputs a sorted table of results to help you identify the fastest DNS server for your location.

Key Features:

• Multi-threaded benchmarking: Runs tests in parallel for speed.
• Flexible Configuration: Customize request counts, thread counts, timeouts, and the target domain.
• Protocol Support: Choose between UDP/TCP and IPv4/IPv6.
• Multiple Output Formats: Supports human-readable tables, JSON, XML, and CSV.
• Customization: Use your own DNS server lists and save preferred configurations.

If your Docker environment allows, you can run the container using your current host user's UID and GID. This requires ensuring that any bind-mounted volumes (like configuration or custom server files) are readable/writable by that user.

docker run --rm -it --name dns-bench \
  --user "$(id -u):$(id -g)" \
  --volume "$PWD/.dns-bench:/root/.dns-bench" \
  --volume /path/to/servers.txt:/servers.txt:ro \
  qwerty541/dns-bench:latest \
  --custom-servers-file /servers.txt

If you have the Rust toolchain installed, you can install the stable version directly from crates.io using Cargo.

After installation, you can run the binary using dns-bench [OPTIONS].

$ cargo install dns-bench

To minimize NAT overhead and achieve the most accurate latency measurements on Linux, run the container using the host network stack.

docker run --rm -it --name dns-bench --network host qwerty541/dns-bench:latest

To use dns-bench via Docker, pull the latest image and run it interactively. By default, the container runs dns-bench --skip-system-servers --skip-gateway-detection.

# Pull the image
docker pull qwerty541/dns-bench:latest

# Run an interactive benchmark
docker run --rm -it --name dns-bench qwerty541/dns-bench:latest

# Show help
docker run --rm -it --name dns-bench qwerty541/dns-bench:latest --help

You can run dns-bench in a containerized environment using Docker Hub or GitHub Container Registry (GHCR).

Note: When running in Docker, automatic detection of system DNS and gateway DNS is skipped.

To pull and run the latest image from Docker Hub:

$ docker pull qwerty541/dns-bench:latest
$ docker run --rm -it --name dns-bench qwerty541/dns-bench:latest

To pass options to the tool:

$ docker run --rm -it --name dns-bench \
  qwerty541/dns-bench:latest \
  --requests 50 --domain microsoft.com --style re-structured-text

To use a custom list of DNS servers, mount your local file into the container and use the --custom-servers-file flag:

$ docker run --rm -it --name dns-bench \
  --volume /path/to/ipv4-custom-servers.txt:/servers.txt:ro \
  qwerty541/dns-bench:latest \
  --custom-servers-file /servers.txt

You can benchmark a specific list of DNS servers by mounting a local text file into the container and passing its path using the --custom-servers-file flag. The file should follow the project's IPv4 or IPv6 format.

docker run --rm -it --name dns-bench \
  --volume /path/to/ipv4-custom-servers.txt:/servers.txt:ro \
  qwerty541/dns-bench:latest \
  --custom-servers-file /servers.txt

For Windows users without a Rust environment, you can download the latest pre-compiled .exe file from the official releases page.

Usage:

1. Download the file.
2. Open a command prompt and navigate to the download directory.
3. Run the executable:

dns-bench.exe [OPTIONS]

WARNING

The Windows executable is not signed. You may see a security warning; you can ignore this if you trust the source, or build from source using Cargo to avoid it.

The application stores its configuration in /root/.dns-bench/config.toml inside the container. To persist settings between different Docker runs, bind-mount a host directory to /root/.dns-bench and use the --save-config flag to write the current configuration to that volume.

# Create a local directory for config
mkdir -p "$PWD/.dns-bench"

# Save current flags to the persistent volume
docker run --rm -it --name dns-bench \
  --volume "$PWD/.dns-bench:/root/.dns-bench" \
  qwerty541/dns-bench:latest \
  --save-config

# Subsequent runs will automatically use the saved config
docker run --rm -it --name dns-bench \
  --volume "$PWD/.dns-bench:/root/.dns-bench" \
  qwerty541/dns-bench:latest

Use this method if you want to install a specific version (e.g., a tagged release) or the latest development version from the GitHub repository.

To install version v0.14.0:

$ cargo install --git https://github.com/qwerty541/dns-bench.git --tag v0.14.0 dns-bench

To install the latest development version, omit the --tag option.

The BenchmarkRunner automatically populates the list of DNS servers to test using a multi-step discovery process:

1. Custom/Built-in List: If a custom_servers_file is provided in the config, it reads that file. Otherwise, it uses the built-in IPv4 or IPv6 DNS entry lists based on the configured IP version.
2. Gateway Detection: If skip_gateway_detection is false, the runner attempts to detect the local gateway IP. If the gateway is responsive to a DNS query (e.g., google.com), it is added to the list as "Router (Gateway) DNS".
3. System DNS: If skip_system_servers is false, the runner retrieves the current system DNS servers and adds them to the list as "System DNS".

All detected entries are stored in a thread-safe VecDeque for the worker threads to consume.

The project uses specific color thresholds to indicate the quality of DNS performance in terminal outputs. These are applied to TimeResult and success percentages via the tabled_settings::Color implementation.

Latency Thresholds (TimeResult):

• Bright Green: $\le 30$ ms
• Bright Yellow: $31$ ms to $80$ ms
• Bright Red: $> 80$ ms
• Red: Any failed request

Success Rate Thresholds (RawResultEntry):

• Bright Green: $100%$ success
• Bright Yellow: $50%$ to $99.9%$ success
• Bright Red: $20%$ to $49.9%$ success
• Red: $< 20%$ success