### Namebench Configuration File Example (INI)

Source: https://context7.com/catap/namebench/llms.txt

A sample INI configuration file for Namebench, detailing default options for benchmarks. It includes settings for general parameters like query count, run count, selection mode, thread counts, timeouts, server limits, results sharing, and the nameserver list file.

```ini
# config/namebench.cfg
[general]

# Number of DNS queries per benchmark run
query_count=200

# Number of benchmark runs per server
run_count=1

# Test selection mode: automatic, weighted, random, chunk
select_mode=automatic

# Thread counts for health checks and benchmarks
health_thread_count=30
benchmark_thread_count=2

# Timeout settings (seconds)
timeout=3.25
ping_timeout=0.5
health_timeout=2

# Maximum nameservers to include in benchmark
num_servers=11

# Results sharing configuration
site_url=http://namebench.appspot.com/
upload_results=0
hide_results=0

# DNS server listing file
server_list=config/servers.csv
```

--------------------------------

### Example JSON Data Structure for namebench Upload

Source: https://github.com/catap/namebench/blob/master/JSON.txt

Illustrates the structure of the JSON data submitted by namebench, including privacy-sensitive fields like 'client_id' and 'submit_id'. These fields are used for identifying unique users and preventing duplicate submissions, respectively, with defined data retention policies.

```JSON
{
  "client_id": 1078802240,
  "submit_id": 34923485
}
```

--------------------------------

### GET /submissions/{id}

Source: https://github.com/catap/namebench/blob/master/JSON.txt

Retrieves the details of a specific DNS benchmark submission, including nameserver performance data and individual query results.

```APIDOC
## GET /submissions/{id}

### Description
Retrieves the full dataset for a specific benchmark submission, including nameserver performance metrics and diagnostic information.

### Method
GET

### Endpoint
/submissions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the submission.

### Response
#### Success Response (200)
- **hidden** (boolean) - Whether the submission is unlisted.
- **data** (object) - The benchmark data containing nameservers and performance metrics.

#### Response Example
{
  "hidden": false,
  "data": {
    "nameservers": [
      {
        "ip": "208.67.220.220",
        "overall_average": 571.28,
        "hostname": "resolver2.opendns.com",
        "is_disabled": false
      }
    ]
  }
}
```

--------------------------------

### Configuration Management (Python)

Source: https://context7.com/catap/namebench/llms.txt

Illustrates how to load and merge configuration settings from files and command-line arguments using the libnamebench.config module. It covers accessing merged options, loading nameserver data from CSV, retrieving sanity checks, and expanding server set tags.

```python
from libnamebench import config

# Get merged configuration (command-line + config file)
options = config.GetMergedConfiguration()

# Access configuration values
print(f"Version: {options.version}")
print(f"Query count: {options.query_count}")
print(f"Run count: {options.run_count}")
print(f"Timeout: {options.timeout}s")
print(f"Health timeout: {options.health_timeout}s")
print(f"Thread count: {options.health_thread_count}")
print(f"Servers to test: {options.num_servers}")
print(f"Server sets: {options.tags}")

# Load nameserver data from CSV
ns_data = config.GetNameServerData(filename='config/servers.csv')
print(f"Loaded {len(ns_data)} nameservers")

# Get sanity checks (auto-updates from remote if enabled)
sanity_checks = config.GetSanityChecks()
# Returns dict with 'primary' and 'secondary' check lists

# Expand server sets to tags
tags = config.ExpandSetsToTags(['global', 'isp'])
# 'global' -> {'global', 'preferred'}
# 'isp' -> {'isp', 'dhcp', 'internal', 'likely-isp'}
# 'all' -> all available tags
# 'system' -> {'system', 'dhcp'}
print(f"Expanded tags: {tags}")
```

--------------------------------

### Manage Nameservers Collection (Python)

Source: https://context7.com/catap/namebench/llms.txt

Demonstrates how to create, populate, filter, and sort a collection of DNS nameservers using the NameServers class. It includes setting client location, applying health checks, and accessing sorted lists of enabled, disabled, and visible servers.

```python
from libnamebench import nameserver_list
from libnamebench import nameserver

# Create nameservers collection
ns_list = nameserver_list.NameServers(
    thread_count=35,
    max_servers_to_check=350
)

# Add nameservers to the collection
ns_list.append(nameserver.NameServer('8.8.8.8', name='Google DNS', tags=['global', 'preferred']))
ns_list.append(nameserver.NameServer('8.8.4.4', name='Google DNS-2', tags=['global']))
ns_list.append(nameserver.NameServer('208.67.222.222', name='OpenDNS', tags=['global', 'preferred']))

# Set client location for nearby server selection
ns_list.SetClientLocation(
    latitude=37.7749,
    longitude=-122.4194,
    client_country='US'
)

# Filter servers by tags
ns_list.FilterByTag(
    include_tags={'global', 'preferred'},
    require_tags={'ipv4'}
)

# Set timeouts for all servers
ns_list.SetTimeouts(
    timeout=3.5,
    ping_timeout=0.5,
    health_timeout=2.0
)

# Define sanity checks for health verification
sanity_checks = {
    'primary': [
        ('A www.google.com.', '74.125.,172.217.,142.250.'),
        ('A a.root-servers.net.', '198.41.0.4'),
    ],
    'secondary': [
        ('A www.yahoo.com.', '98.,74.'),
    ]
}

# Run comprehensive health checks
ns_list.CheckHealth(sanity_checks=sanity_checks, max_servers=11)

# Access filtered server lists
enabled = ns_list.enabled_servers    # Healthy servers
disabled = ns_list.disabled_servers  # Failed health checks
visible = ns_list.visible_servers    # Not hidden

# Sort by performance
fastest = ns_list.SortEnabledByFastest()
near = ns_list.SortEnabledByNearest()

for ns in fastest[:5]:
    print(f"{ns.name}: {ns.check_average:.2f}ms avg")
```

--------------------------------

### Running namebench from Command Line

Source: https://context7.com/catap/namebench/llms.txt

Execute DNS benchmarks using various command-line arguments to customize server selection, query counts, reporting, and data sources. Supports options for system-configured, all available, or custom DNS servers, and enables features like censorship checks and IPv6 testing.

```bash
# Basic usage - runs with default settings and GUI (if available)
./namebench.py

# Force command-line interface
./namebench.py -x

# Test specific DNS servers
./namebench.py 8.8.8.8 8.8.4.4 208.67.222.222

# Test only system-configured nameservers
./namebench.py -s system

# Test all available DNS servers (comprehensive benchmark)
./namebench.py -s all

# Test preferred global DNS servers plus custom server
./namebench.py -s global 10.0.0.1

# Run with specific query count and number of runs
./namebench.py -q 250 -r 2

# Generate report with specific output file
./namebench.py -o /tmp/dns_benchmark.html -t html

# Export detailed CSV results
./namebench.py -c /tmp/dns_details.csv

# Use specific data source for test queries
./namebench.py -i alexa

# Test with IPv6 nameservers only
./namebench.py -6

# Enable censorship checks
./namebench.py -C

# Upload anonymized results
./namebench.py -u

# Control thread count for health checks and benchmarks
./namebench.py -j 40 -J 4
```

--------------------------------

### Namebench Configuration Options

Source: https://github.com/catap/namebench/blob/master/JSON.txt

Details the configuration options selected by the user for the Namebench run.

```APIDOC
## Namebench Configuration Options Structure

### Description
Lists the various settings and parameters configured by the user for the Namebench benchmark.

### Endpoint
N/A (This describes a data structure within a larger response)

### Parameters
N/A

### Request Body
N/A

### Response
#### Config Object
- **query_count** (integer) - The number of queries to perform.
- **benchmark_thread_count** (integer) - The number of threads for benchmarking.
- **template** (string) - The output template format (e.g., 'html').
- **health_thread_count** (integer) - The number of threads for health checks.
- **version** (string) - The version of Namebench being used.
- **only** (boolean) - If true, only specific options are used.
- **select_mode** (string) - The selection mode for nameservers (e.g., 'automatic').
- **platform** (string) - The operating system platform.
- **num_servers** (integer) - The number of nameservers to select.
- **hide_results** (integer) - Flag to hide results (0 for false).
- **ping_timeout** (float) - Timeout for ping operations.
- **timeout** (float) - Overall timeout for the benchmark.
- **run_count** (integer) - The number of times to run the benchmark.
- **input_source** (string) - The source of the input data (e.g., 'chrome').
- **health_timeout** (float) - Timeout for health checks.
- **upload_results** (boolean) - Whether to upload the results.

### Response Example
```json
{
   "query_count": 25,
   "benchmark_thread_count": 2,
   "template": "html",
   "health_thread_count": 40,
   "version": "1.3-BETA1",
   "only": true,
   "select_mode": "automatic",
   "platform": "Mac OS X",
   "num_servers": 11,
   "hide_results": 0,
   "ping_timeout": 0.5,
   "timeout": 3.5,
   "run_count": 1,
   "input_source": "chrome",
   "health_timeout": 3.75,
   "upload_results": true
}
```
```

--------------------------------

### Generate DNS Test Records (Python)

Source: https://context7.com/catap/namebench/llms.txt

Illustrates how to use the DataSources class to manage and generate DNS test queries from various sources like browser history, Alexa rankings, or custom files. It covers listing source types, retrieving source details, selecting the best source, and generating test records with different selection modes.

```python
from libnamebench import data_sources

# Initialize data sources with default config
ds = data_sources.DataSources(
    config_path='config/data_sources.cfg',
    status_callback=lambda msg, **kw: print(msg)
)

# List all available source types
source_types = ds.ListSourceTypes()
# Returns: ['alexa', 'cachehit', 'cachemiss', 'chrome', 'firefox', 'safari', ...]

# Get details about each source (name, synthetic flag, record count)
details = ds.ListSourcesWithDetails()
for source_type, name, is_synthetic, count in details:
    print(f"{name}: {count} records (synthetic: {is_synthetic})")

# Get the best available source (most records, organic data preferred)
best_source = ds.GetBestSourceDetails()
print(f"Best source: {best_source[1]} with {best_source[3]} records")

# Generate test records from a source
# select_mode options: 'automatic', 'weighted', 'random', 'chunk'
test_records = ds.GetTestsFromSource(
    source='alexa',
    count=250,
    select_mode='weighted'
)

# Each record is a tuple of (request_type, hostname)
for req_type, hostname in test_records[:5]:
    print(f"{req_type} {hostname}")

# Use browser history as source (e.g., Chrome)
chrome_tests = ds.GetTestsFromSource('chrome', count=100)

# Use custom file as data source
custom_tests = ds.GetTestsFromSource('/path/to/domains.txt', count=50)
```

--------------------------------

### Generate Benchmark Reports (Python)

Source: https://context7.com/catap/namebench/llms.txt

Shows how to generate benchmark reports in various formats (ASCII, HTML, CSV, JSON) using the ReportGenerator class. It covers obtaining the best overall and nearest nameservers, saving reports to files, and exporting detailed results.

```python
from libnamebench import reporter
from libnamebench import benchmark

# After running a benchmark
# results = bmark.Run(test_records)

# Create report generator
report_gen = reporter.ReportGenerator(
    config=options,           # Configuration object with version, timeout, etc.
    nameservers=nameservers,  # NameServers collection
    results=results,          # Benchmark results dict
    index=index_results,      # Optional index test results
    geodata={'country_code': 'US', 'latitude': 37.7, 'longitude': -122.4}
)

# Get the best overall nameserver
best_ns = report_gen.BestOverallNameServer()
print(f"Recommended: {best_ns.name} ({best_ns.ip})")

# Get nearest nameservers by latency
near = report_gen.NearestNameServers(count=3)
for ns in nearest:
    print(f"Near: {ns.name}")

# Generate ASCII report (for terminal output)
ascii_report = report_gen.CreateReport(format='ascii')
print(ascii_report)

# Generate HTML report to file
with open('/tmp/namebench_report.html', 'w') as f:
    report_gen.CreateReport(
        format='html',
        output_fp=f,
        csv_path='/tmp/namebench_results.csv',
        sharing_url='http://example.com/shared/abc123',
        sharing_state='public'
    )

# Save detailed results to CSV
report_gen.SaveResultsToCsv('/tmp/detailed_results.csv')
# CSV columns: IP, Name, Test_Num, Record, Record_Type, Duration, TTL, Answer_Count, Response

# Generate JSON for sharing/upload
json_data = report_gen.CreateJsonData()
```

--------------------------------

### DNS Server Health Check Methods (Python)

Source: https://context7.com/catap/namebench/llms.txt

Demonstrates various methods for verifying DNS server health, detecting hijacking, and censorship using the libnamebench.nameserver module. It includes tests for standard queries, NXDOMAIN hijacking, subdomain hijacking, root server response, and comprehensive health checks.

```python
from libnamebench import nameserver

ns = nameserver.NameServer('8.8.8.8', name='Google DNS')
ns.health_timeout = 2.0

# Test if server responds correctly to standard queries
is_broken, error_msg, duration = ns.TestAnswers(
    record_type='A',
    record='www.google.com.',
    expected=('74.125.', '172.217.', '142.250.'),  # Expected IP prefixes
    critical=True,
    timeout=3.0
)
if error_msg:
    print(f"Warning: {error_msg}")

# Test for NXDOMAIN hijacking
is_broken, error_msg, duration = ns.TestNegativeResponse()
if error_msg:
    print(f"NXDOMAIN issue: {error_msg}")

# Test www subdomain hijacking specifically
is_broken, error_msg, duration = ns.TestWwwNegativeResponse()

# Test root server response (basic connectivity check)
is_broken, error_msg, duration = ns.TestARootServerResponse()

# Run comprehensive health check
# Returns True if server is disabled after checks
sanity_checks = [
    ('A www.google.com.', '74.125.,172.217.'),
    ('A a.root-servers.net.', '198.41.0.4'),
]
is_disabled = ns.CheckHealth(
    sanity_checks=sanity_checks,
    fast_check=False,
    final_check=False
)

# Check for censorship
censorship_checks = [
    ('A twitter.com.', '104.244.'),
    ('A facebook.com.', '157.240.,31.13.'),
]
ns.CheckCensorship(censorship_checks)

# Access check results
for test_name, is_broken, warning, duration in ns.checks:
    status = "FAIL" if is_broken else "OK"
    print(f"{test_name}: {status} ({duration:.2f}ms) {warning or ''}")
```

--------------------------------

### Namebench Server Data

Source: https://github.com/catap/namebench/blob/master/JSON.txt

This section describes the structure of data returned for each nameserver, including its position, version, port diversity, and performance metrics.

```APIDOC
## Namebench Server Data Structure

### Description
Provides detailed information about individual nameservers, including performance metrics and configuration details.

### Endpoint
N/A (This describes a data structure within a larger response)

### Parameters
N/A

### Request Body
N/A

### Response
#### Server Object
- **sys_position** (null) - The system position of the nameserver.
- **version** (string) - The version number of the nameserver, if available. Removed for private IPs.
- **is_regional** (boolean) - Indicates if the nameserver is regional.
- **port_behavior** (string) - Data on OARC port diversity, available for public IPs.
- **duration_max** (float) - The precomputed slowest query time.
- **duration_min** (float) - The precomputed fastest query time.
- **averages** (array of floats) - An array containing average query times for each run.

### Response Example
```json
{
   "sys_position": null,
   "version": "",
   "is_regional": false,
   "port_behavior": "208.67.217.8 is GREAT: 26 queries in 2.0 seconds from 26 ports with std dev 18425",
   "duration_max": 721.9398021697998,
   "duration_min": 37.251949310302734,
   "averages": [
      571.28124237060547
   ]
}
```
```

--------------------------------

### Define nameserver benchmark result structure

Source: https://github.com/catap/namebench/blob/master/JSON.txt

This snippet illustrates the JSON structure used to store nameserver performance data, including latency averages, individual query durations, and index host results.

```json
{
  "nameservers": [
    {
      "timeout_count": 0,
      "check_average": 433.19,
      "node_ids": ["3.nyc"],
      "ip": "208.67.220.220",
      "durations": [[671.98, 611.46, 625.26]],
      "is_disabled": false,
      "is_global": false,
      "error_count": 0,
      "nx_count": 0,
      "position": 0,
      "is_failure_prone": false,
      "overall_average": 571.28,
      "index": [["www.google.com.", "A", 716.68, 2, 30, "google.navigation.opendns.com."]],
      "is_reference": true,
      "is_custom": false,
      "name": "",
      "notes": [{"url": "http://code.google.com/p/namebench/wiki/FAQ", "text": "www.google.com is hijacked"}],
      "hostname": "resolver2.opendns.com"
    }
  ]
}
```

--------------------------------

### Benchmark Class for DNS Performance Testing

Source: https://context7.com/catap/namebench/llms.txt

The Benchmark class orchestrates DNS performance tests against multiple nameservers using multi-threaded execution. It allows configuration of test parameters like run count, query count, and thread count, and processes results for analysis.

```python
from libnamebench import benchmark
from libnamebench import nameserver_list

# Assume nameservers is a NameServers list object
nameservers = nameserver_list.NameServers()

# Create benchmark with configuration
bmark = benchmark.Benchmark(
    nameservers=nameservers,
    run_count=2,           # Number of test runs per server
    query_count=200,       # DNS queries per run
    thread_count=4,        # Concurrent benchmark threads
    status_callback=lambda msg, **kw: print(f"Status: {msg}")
)

# Define test records as list of (type, hostname) tuples
test_records = [
    ('A', 'www.google.com.'),
    ('A', 'www.facebook.com.'),
    ('A', 'www.youtube.com.'),
    ('AAAA', 'www.google.com.'),
    ('MX', 'gmail.com.'),
]

# Run the benchmark
# Returns: dict keyed by nameserver with list of results per run
results = bmark.Run(test_records)

# Process results
for ns, runs in results.items():
    print(f"\n{ns.name} ({ns.ip}):")
    for run_num, run_results in enumerate(runs):
        durations = [r[2] for r in run_results]  # r[2] is duration
        avg_duration = sum(durations) / len(durations)
        print(f"  Run {run_num + 1}: avg {avg_duration:.2f}ms")

# Run index tests (for specific reference hosts)
index_hosts = [('A', 'a.root-servers.net.'), ('A', 'www.google.com.')]
index_results = bmark.RunIndex(index_hosts)
```

--------------------------------

### Python Client ID Generation using zlib crc32

Source: https://github.com/catap/namebench/blob/master/JSON.txt

Generates a unique client ID for identifying subsequent runs from the same user. It concatenates system information and computes a CRC32 checksum using the zlib library. This ID is intended to detect duplicate submissions within a 6-hour window and is deleted from the datastore within 12 hours.

```Python
import platform
import sys
import os
import zlib

def generate_client_id():
    data_string = (
        platform.platform() + 
        sys.version + 
        platform.node() + 
        os.getenv('HOME')
    )
    checksum = zlib.crc32(data_string.encode('utf-8'))
    return checksum
```

--------------------------------

### Namebench Results Upload API

Source: https://github.com/catap/namebench/blob/master/JSON.txt

This API endpoint allows users to opt-in to upload their Namebench performance results. It details the structure of the JSON payload, including client identification and submission specific data.

```APIDOC
## POST /api/namebench/upload

### Description
Allows users to upload their Namebench performance results to a central server. This feature is opt-in and used for performance analysis and comparison.

### Method
POST

### Endpoint
/api/namebench/upload

### Parameters
#### Request Body
- **client_id** (integer) - Required - A checksum-based identifier derived from system information (OS, Python version, hostname, home directory) to detect subsequent runs from the same user. Deleted from datastore within 12 hours.
- **submit_id** (integer) - Required - A random integer used to prevent duplicate submissions in case of client or server errors. Deleted from datastore within 12 hours.

### Request Example
```json
{
  "client_id": 1078802240,
  "submit_id": 34923485
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the upload operation.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Results uploaded successfully."
}
```
```

--------------------------------

### NameServer Class for DNS Server Management

Source: https://context7.com/catap/namebench/llms.txt

The NameServer class represents a DNS server, providing methods for querying, health checking, and measuring performance. It allows configuration of timeouts and retrieval of server information like version and IP addresses.

```python
from libnamebench import nameserver

# Create a nameserver instance
ns = nameserver.NameServer(
    ip='8.8.8.8',
    name='Google Public DNS',
    tags=['global', 'preferred'],
    provider='Google',
    location='US'
)

# Configure timeouts
ns.timeout = 3.5          # General query timeout (seconds)
ns.health_timeout = 2.0   # Health check timeout
ns.ping_timeout = 0.5     # Initial ping timeout

# Execute a timed DNS request
# Returns: (response, duration_ms, error_msg)
response, duration, error = ns.TimedRequest('A', 'www.google.com.')
print(f"Query took {duration:.2f}ms")

if response and response.answer:
    print(f"Answer: {nameserver.ResponseToAscii(response)}")

# Get server version (BIND version query)
version, duration = ns.GetVersion()
print(f"Server version: {version}")

# Reverse DNS lookup
hostname = ns.GetReverseIp('8.8.8.8')
print(f"Hostname: {hostname}")

# Get TXT record with timing
txt_value, duration = ns.GetTxtRecordWithDuration('example.com.')

# Get IP from hostname with timing
ip, duration = ns.GetIpFromNameWithDuration('www.google.com.')

# Access server properties
print(f"IP: {ns.ip}")
print(f"Hostname: {ns.hostname}")
print(f"Check average: {ns.check_average:.2f}ms")
print(f"Is disabled: {ns.is_disabled}")
print(f"Warnings: {ns.warnings_string}")
print(f"Failure rate: {ns.failure_rate:.1f}%")
```

--------------------------------

### Accessing Computed Averages

Source: https://context7.com/catap/namebench/llms.txt

This snippet shows how to access and print computed DNS server averages from the report_gen.ComputeAverages() function. It iterates through the results, displaying the nameserver, overall average latency, fastest, and slowest response times.

```python
averages = report_gen.ComputeAverages()
for ns, overall_avg, run_avgs, fastest, slowest, failures, nx_count, total in averages:
    print(f"{ns.name}: avg={overall_avg:.2f}ms, min={fastest:.2f}ms, max={slowest:.2f}ms")
```

--------------------------------

### Namebench GeoIP Data

Source: https://github.com/catap/namebench/blob/master/JSON.txt

Details the GeoIP data returned by the Google Gears JSON API, used for geographic result localization.

```APIDOC
## Namebench GeoIP Data Structure

### Description
Provides geographical location information for the user, derived from GeoIP data.

### Endpoint
N/A (This describes a data structure within a larger response)

### Parameters
N/A

### Request Body
N/A

### Response
#### GeoData Object
- **city** (string) - The city name.
- **region_name** (string) - The name of the region or state.
- **source** (string) - The source of the GeoIP data (e.g., 'gloc' for Google).
- **longitude** (float) - The longitude coordinate.
- **latitude** (float) - The latitude coordinate.
- **country_code** (string) - The two-letter country code.
- **country_name** (string) - The full country name.

### Response Example
```json
{
   "city": "Manchester",
   "region_name": "New Hampshire",
   "source": "gloc",
   "longitude": -71.454,
   "latitude": 42.995,
   "country_code": "US",
   "country_name": "United States"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.