### Example Output of Runtime Configuration

Source: https://0xerr0r.github.io/blocky/latest/additional_information

This is an example of the output you can expect when sending a SIGUSR1 signal to the Blocky process, showing detailed configuration and runtime metrics.

```text
INFO server: current configuration:
INFO server: -> resolver: 'ClientNamesResolver'
INFO server:      singleNameOrder = "[2 1]"
INFO server:      externalResolver = "upstream 'tcp+udp:192.168.178.1:53'"
INFO server:      cache item count = 7
INFO server: -> resolver: 'QueryLoggingResolver'
INFO server:      logDir= "/logs"
INFO server:      perClient = false
INFO server:      logRetentionDays= 7
INFO server: -> resolver: 'MetricsResolver'
INFO server:      metrics:
INFO server:        Enable = true
INFO server:        Path   = /metrics
INFO server: -> resolver: 'ConditionalUpstreamResolver'
INFO server:      fritz.box = "parallel upstreams 'upstream 'tcp+udp:192.168.178.1:53''"
INFO server: -> resolver: 'CustomDNSResolver'
INFO server: runtime information:
... 
INFO server: MEM Alloc =                 9 MB
INFO server: MEM HeapAlloc =             9 MB
INFO server: MEM Sys =                  88 MB
INFO server: MEM NumGC =              1533
INFO server: RUN NumCPU =                4
INFO server: RUN NumGoroutine =         18

```

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

### Start Docker Compose

Source: https://0xerr0r.github.io/blocky/latest/installation

Command to start the Docker containers defined in a docker-compose.yml file in detached mode.

```bash
docker-compose up -d

```

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

### Define Sources for Resolvers

Source: https://0xerr0r.github.io/blocky/latest/configuration

Examples of defining sources for Blocky resolvers, including HTTP(S) URLs, local file paths, and inline configuration.

```yaml
- https://example.com/a/source # blocky will download and parse the file
- /a/file/path # blocky will read the local file
- | # blocky will parse the content of this multi-line string
  # inline configuration

```

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

### Good DNS64 Configuration (Includes Prefix)

Source: https://0xerr0r.github.io/blocky/latest/configuration

This is a good configuration example that correctly includes the configured DNS64 prefix within the exclusion set to prevent synthesis loops.

```yaml
dns64:
  prefixes:
    - 64:ff9b::/96
  exclusionSet:
    - ::ffff:0:0/96
    - 64:ff9b::/96   # Includes configured prefix

```

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

### Enable HTTP/3 (DoH3)

Source: https://0xerr0r.github.io/blocky/latest/configuration

Example configuration to enable DNS-over-HTTPS over HTTP/3. This requires the HTTPS listener to be enabled on a specific port.

```yaml
ports:
  https: 443
http3:
  enable: true

```

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

### Custom DNS with Domain Rewriting and Mapping

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configure custom DNS entries and rewrite domain names before resolution. This example shows how 'printer.home' is rewritten to 'printer.lan' and 'sub.example.com' to 'sub.example-rewrite.com'.

```yaml
customDNS:
  rewrite:
    home: lan
    example.com: example-rewrite.com
  mapping:
    printer.lan: 192.168.178.3
    example-rewrite.com: 1.2.3.4

```

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

### Custom DNS Zone File Configuration

Source: https://0xerr0r.github.io/blocky/latest/configuration

Define DNS records using standard zone file syntax for complex configurations. This example sets up A and AAAA records for 'www' and a CNAME for '@' within the 'example.com' origin.

```yaml
customDNS:
  zone: |
    $ORIGIN example.com.
    www 3600 A 1.2.3.4
    www 3600 AAAA 2001:db8:85a3::8a2e:370:7334
    @ 3600 CNAME www

```

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

### Configure Redis Connection

Source: https://0xerr0r.github.io/blocky/latest/configuration

Example configuration for connecting Blocky to a Redis instance, including address, authentication, database selection, and connection parameters. Sentinel configuration is also shown.

```yaml
redis:
  address: redismaster
  username: usrname
  password: passwd
  database: 2
  required: true
  connectionAttempts: 10
  connectionCooldown: 3s
  sentinelUsername: sentUsrname
  sentinelPassword: sentPasswd
  sentinelAddresses:
    - redis-sentinel1:26379
    - redis-sentinel2:26379
    - redis-sentinel3:26379

```

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

### Query Healthcheck Endpoint

Source: https://0xerr0r.github.io/blocky/latest/configuration

Example command to query the Blocky healthcheck endpoint. This query should return NOERROR with no answer records.

```bash
dig @<blocky-host> -p <dns-port> healthcheck.blocky A +short

```

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

### Advanced Docker Compose with Persistent Storage

Source: https://0xerr0r.github.io/blocky/latest/installation

An advanced docker-compose.yml setup for Blocky, including persistent storage for query logs and custom lists via CIFS (Samba) mount.

```yaml
version: "2.1"
services:
  blocky:
    image: spx01/blocky
    container_name: blocky
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "4000:4000/tcp" # Prometheus stats (if enabled)
    environment:
      - TZ=Europe/Berlin
    volumes:
      # config file
      - ./config.yml:/app/config.yml:ro
      # write query logs in this volume
      - queryLogs:/logs
      # put your custom allow/denylists in these directories
      - ./denylists:/app/denylists/
      - ./allowlists:/app/allowlists/

volumes:
  queryLogs:
    driver: local
    driver_opts:
      type: cifs
      o: username=USER,password=PASSWORD,rw
      device: //NAS_HOSTNAME/blocky

```

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

### Get Blocking Status via CLI

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Prints the current blocking status using the Blocky CLI. Ensure the Blocky DNS server is running.

```shell
./blocky blocking status

```

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

### Conditional DNS Resolution Configuration

Source: https://0xerr0r.github.io/blocky/latest/configuration

Set up conditional DNS resolution to direct queries for specific domains to designated resolvers. This example maps 'fritz.box' and 'lan.net' to local IPs, handles reverse lookups, and redirects unqualified hostnames.

```yaml
conditional:
  fallbackUpstream: false
  rewrite:
    example.com: fritz.box
    replace-me.com: with-this.com
  mapping:
    fritz.box: 192.168.178.1
    lan.net: 192.170.1.2,192.170.1.3
    # for reverse DNS lookups of local devices
    178.168.192.in-addr.arpa: 192.168.178.1
    # for all unqualified hostnames
    .: 168.168.0.1

```

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

### Enable Docker Image Creation on Fork

Source: https://0xerr0r.github.io/blocky/latest/additional_information

To enable Docker image creation on a GitHub fork, create a secret named `DEVELOPMENT_DOCKER` with the value `true`. This will trigger a workflow on pushes to branches starting with `fb-`.

```yaml
name: Docker Image Creation

on: push

jobs:
  build_image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: your-dockerhub-username/blocky:${{ github.ref_name }}
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
        if: github.event_name == 'push' && startsWith(github.sha, 'fb-') && secrets.DEVELOPMENT_DOCKER == 'true'

```

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

### Basic Upstream Configuration

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configure the initial startup strategy for upstream resolvers. Use 'fast' for quicker startup.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/0xERR0R/blocky/main/docs/config.schema.json
upstreams:
  init:
    # Configure startup behavior.
    # accepted: blocking, failOnError, fast
    # default: blocking
    strategy: fast
```

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

### Get Blocking Status

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Retrieves the current global blocking status from Blocky.

```APIDOC
## GET /api/blocking/status

### Description
Return current blocking status as JSON.

### Method
GET

### Endpoint
/api/blocking/status

### Response
#### Success Response (200)
Returns current blocking status as JSON.
```

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

### Get Blocking Status

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Retrieves the current status of the DNS blocking feature, including whether it's enabled and any disabled groups.

```APIDOC
## GET /blocking/status

### Description
Get the current blocking status.

### Method
GET

### Endpoint
/blocking/status

### Response
#### Success Response (200)
- Description: Returns current blocking status
- Content Type: application/json
- Schema: api.BlockingStatus
  - **enabled** (boolean) - Required - True if blocking is enabled
  - **autoEnableInSec** (integer) - Optional - If blocking is temporary disabled: amount of seconds until blocking will be enabled
  - **disabledGroups** (array) - Optional - Disabled group names, items are strings
```

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

### Hosts File Configuration

Source: https://0xerr0r.github.io/blocky/latest/configuration

Enable and configure local hosts file resolution, specifying sources, TTL, and loopback filtering.

```yaml
hostsFile:
  sources:
    - /etc/hosts
  hostsTTL: 1h
  loading:
    refreshPeriod: 30m
    strategy: fast
```

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

### Get Blocking Status via Docker Exec

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Retrieves the current blocking status by executing the Blocky CLI command within a Docker container.

```shell
docker exec blocky ./blocky blocking status

```

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

### Run Blocky with Multiple Configuration Files

Source: https://0xerr0r.github.io/blocky/latest/installation

Specify a directory containing multiple YAML configuration files to be loaded by Blocky. Ensure no configuration options are duplicated across files to avoid loading errors.

```bash
./blocky --config ./config/

```

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

### Enable pprof Endpoint for Debugging

Source: https://0xerr0r.github.io/blocky/latest/additional_information

If the HTTP listener is enabled in the configuration, the pprof debugging and profiling endpoint is automatically available at `/debug/pprof`.

```go
http://localhost:PORT/debug/pprof/
```

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

### Enable Prometheus Metrics

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configuration to enable Prometheus metrics exposition. Requires the HTTP listener to be enabled. Specifies the URL path for the metrics endpoint.

```yaml
prometheus:
  enable: true
  path: /metrics

```

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

### Print Runtime Configuration with SIGUSR1

Source: https://0xerr0r.github.io/blocky/latest/additional_information

Send a SIGUSR1 signal to the running process to print its current configuration and runtime statistics. This is useful for monitoring and debugging.

```bash
kill -s USR1 <PID>
```

```bash
docker kill -s SIGUSR1 blocky
```

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

### Load Redis Password from File

Source: https://0xerr0r.github.io/blocky/latest/configuration

Demonstrates how to load sensitive values like Redis passwords from files using the 'file:' prefix. This is useful for Docker/Kubernetes secrets and file permission management.

```yaml
redis:
  password: file:/run/secrets/redis_password

```

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

### Bad DNS64 Configuration (Missing Prefix)

Source: https://0xerr0r.github.io/blocky/latest/configuration

This configuration is flagged as bad because it omits the configured DNS64 prefix from the exclusion set, which can lead to synthesis loops.

```yaml
dns64:
  prefixes:
    - 64:ff9b::/96
  exclusionSet:
    - ::ffff:0:0/96  # Missing configured prefix!

```

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

### Configure HTTP(S) Source Download Parameters

Source: https://0xerr0r.github.io/blocky/latest/configuration

Defines parameters for downloading HTTP(S) sources, including timeouts for connection, writing, reading, and reading headers, as well as the number of download attempts and cooldown period between them.

```yaml
loading:
  downloads:
    timeout: 4m
    attempts: 5
    cooldown: 10s

```

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

### Set NET_BIND_SERVICE Capability (Restricted Runtime)

Source: https://0xerr0r.github.io/blocky/latest/installation

Alternative command for setting the NET_BIND_SERVICE capability when Blocky runs under a restricted capability bounding set, using '+p' for permitted only.

```bash
setcap 'cap_net_bind_service=+p' ./blocky
```

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

### Configure Custom DNS Simple Mapping

Source: https://0xerr0r.github.io/blocky/latest/configuration

Set up simple domain-to-IP mappings for local DNS resolution. This allows custom hostnames to resolve to specific IP addresses, including multiple IPs for a single domain.

```yaml
customDNS:
  customTTL: 1h
  mapping:
    printer.lan: 192.168.178.3
    otherdevice.lan: 192.168.178.15,2001:0db8:85a3:08d3:1319:8a2e:0370:7344

```

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

### Run DNS Query (A Record) via CLI

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Executes a DNS query for an A record of a domain using the Blocky CLI. Useful for debugging.

```shell
./blocky query <domain>

```

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

### Configure Network Ports and Addresses

Source: https://0xerr0r.github.io/blocky/latest/configuration

Define listen addresses for DNS, DoT, HTTP (metrics, pprof, REST API, DoH), and HTTPS. Also configure the DoH path and free binding option.

```yaml
ports:
  dns: 53
  tls: [853, "[::1]:853"]
  http:
    - 80
    - 4000
  https: 443
  dohPath: /my-custom-dns-query
```

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

### QUIC Settings

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configure QUIC-specific settings, including maximum idle timeout and keep-alive interval. These are only relevant when using QUIC upstreams.

```yaml
  quic:
    # optional: maximum idle timeout before closing connection. Default: 30s
    maxIdleTimeout: 30s
    # optional: keep-alive interval to maintain connection. Default: 15s
    keepAlivePeriod: 15s
```

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

### Enable Blocking via CLI

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Enables global blocking using the Blocky CLI. Ensure the Blocky DNS server is running before executing.

```shell
./blocky blocking enable

```

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

### Enable DNS64 Synthesis

Source: https://0xerr0r.github.io/blocky/latest/configuration

Enable DNS64 synthesis for IPv4-to-IPv6 address conversion. Do not enable if filtering AAAA queries, as it will be ineffective.

```yaml
dns64:
  enable: false
```

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

### Validate Configuration via CLI

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Validates the Blocky configuration file. Optionally specify a custom path to the configuration file.

```shell
./blocky validate [--config /path/to/config.yaml]

```

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

### Configure DNS64 Prefixes

Source: https://0xerr0r.github.io/blocky/latest/configuration

Specify IPv6 prefixes for DNS64 synthesis. Multiple prefixes can be used for load balancing. Prefixes must not overlap.

```yaml
dns64:
  prefixes:
    - 64:ff9b::/96
```

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

### Configure Logging Options in Blocky

Source: https://0xerr0r.github.io/blocky/latest/configuration

Set logging level, format, timestamp inclusion, and privacy obfuscation. Ensure 'privacy' is true to obfuscate sensitive data.

```yaml
log:
  level: debug
  format: json
  timestamp: false
  privacy: true

```

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

### Define Blocking and Allowlisting Groups

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configures denylist and allowlist groups, specifying sources for each. Supports URLs, local files, and inline definitions for domains and regex patterns.

```yaml
blocking:
  denylists:
    ads:
      - https://s3.amazonaws.com/lists.disconnect.me/simple_ad.txt
      - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
      - |
        # inline definition using YAML literal block scalar style
        # content is in plain domain list format
        someadsdomain.com
        anotheradsdomain.com
        *.wildcard.example.com # blocks wildcard.example.com and all subdomains
      - |
        # inline definition with a regex
        /^banners?[_.-]/
    special:
      - https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews/hosts
  allowlists:
    ads:
      - allowlist.txt
      - /path/to/file.txt
      - |
        # inline definition with YAML literal block scalar style
        allowlistdomain.com

```

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

### Configure Loading Settings for Resolvers

Source: https://0xerr0r.github.io/blocky/latest/configuration

These settings apply to the 'blocking' and 'hostsFile' resolvers independently. They control the loading behavior specific to each resolver.

```yaml
blocking:
  loading:
    # only applies to allow/denylists

hostsFile:
  loading:
    # only applies to hostsFile sources

```

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

### Refresh Lists via CLI

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Reloads all allow and denylists using the Blocky CLI. Ensure the Blocky DNS server is running.

```shell
./blocky lists refresh

```

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

### Configure Custom DNS64 Exclusion Set

Source: https://0xerr0r.github.io/blocky/latest/configuration

Use this configuration to define a custom exclusion set for DNS64. Ensure that configured DNS64 prefixes are explicitly included to prevent synthesis loops.

```yaml
dns64:
  enable: true
  prefixes:
    - 64:ff9b::/96
  exclusionSet:
    - ::ffff:0:0/96  # IPv4-mapped (REQUIRED by RFC)
    - ::1/128        # Loopback (recommended)
    - fe80::/10      # Link-local (recommended)
    - 64:ff9b::/96   # Your configured prefix (recommended to prevent loops)
    - 2001:db8::/32  # Custom exclusion range

```

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

### Docker Compose for Blocky

Source: https://0xerr0r.github.io/blocky/latest/installation

A docker-compose.yml file to define and run the Blocky service, including port mappings, environment variables, and volume mounts for configuration.

```yaml
version: "2.1"
services:
  blocky:
    image: spx01/blocky
    container_name: blocky
    restart: unless-stopped
    # Optional the instance hostname for logging purpose
    hostname: blocky-hostname
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "4000:4000/tcp"
    environment:
      - TZ=Europe/Berlin # Optional to synchronize the log timestamp with host
    volumes:
      # Optional to synchronize the log timestamp with host
      - /etc/localtime:/etc/localtime:ro
      # config file
      - ./config.yml:/app/config.yml:ro

```

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

### Configure Loading Strategy

Source: https://0xerr0r.github.io/blocky/latest/configuration

Specifies the strategy for handling errors during the initialization (loading and parsing) of sources. 'failOnError' means parsing stops if a single source fails.

```yaml
loading:
  strategy: failOnError

```

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

### Configure Bootstrap DNS

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configures bootstrap DNS using DoH and DoT servers by IP, and reads resolvers from a file for OpenWrt systems.

```yaml
    bootstrapDns:
      - upstream: tcp-tls:dns.example.com
        ips:
        - 123.123.123.123
      - upstream: https://234.234.234.234/dns-query
      # read the DHCP-provided resolvers from a file (e.g. OpenWrt)
      - resolvFile: /tmp/resolv.conf.auto
```

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

### Basic Blocky Configuration

Source: https://0xerr0r.github.io/blocky/latest/installation

A simple YAML configuration file for Blocky, enabling basic features like upstream DNS groups, ad blocking, and port definitions.

```yaml
upstreams:
  groups:
    default:
      - 46.182.19.48
      - 80.241.218.68
      - tcp-tls:fdns1.dismail.de:853
      - https://dns.digitale-gesellschaft.ch/dns-query
blocking:
  denylists:
    ads:
      - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  clientGroupsBlock:
    default:
      - ads
ports:
  dns: 53
  http: 4000

```

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

### Configure Minimum TLS Version and IP Version

Source: https://0xerr0r.github.io/blocky/latest/configuration

Set the minimum TLS version for DoT and DoH servers and specify the IP version for outgoing connections.

```yaml
minTlsServeVersion: 1.1
connectIPVersion: v4
```

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

### Run DNS Query with Specific Type via CLI

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Executes a DNS query for a specified record type (e.g., A, AAAA, MX) of a domain using the Blocky CLI.

```shell
./blocky query <domain> --type <queryType>

```

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

### Enable Blocky Service on NixOS

Source: https://0xerr0r.github.io/blocky/latest/installation

Configure Blocky as a service on NixOS by adding it to your system's configuration. You can specify custom settings within the `settings` block.

```nix
services.blocky = {
  enable = true;

  settings = {
    # anything from config.yml
  };
};


```

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

### Run Blocky Docker Container

Source: https://0xerr0r.github.io/blocky/latest/installation

Command to run the Blocky Docker container, mapping configuration and ports, and naming the container.

```bash
docker run --name blocky -v /path/to/config.yml:/app/config.yml -p 4000:4000 -p 53:53/udp spx01/blocky

```

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

### Set NET_BIND_SERVICE Capability

Source: https://0xerr0r.github.io/blocky/latest/installation

Command to add the NET_BIND_SERVICE capability to the Blocky binary, allowing it to bind to privileged ports (< 1024) as a non-root user on Linux.

```bash
setcap 'cap_net_bind_service=+ep' ./blocky
```

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

### Run DNS Query

Source: https://0xerr0r.github.io/blocky/latest/interfaces

Executes a DNS query through Blocky and returns the result in JSON format.

```APIDOC
## POST /api/query

### Description
Run a DNS query through Blocky and return the result as JSON.

### Method
POST

### Endpoint
/api/query

### Parameters
#### Request Body
- **domain** (string) - Required - The domain name to query.
- **type** (string) - Optional - The DNS query type (e.g., `A`, `AAAA`, `MX`). Defaults to `A` if not specified.

### Response
#### Success Response (200)
Returns the DNS query result as JSON.
```

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

### Configure Rate Limiting

Source: https://0xerr0r.github.io/blocky/latest/configuration

Enable and configure rate limiting to control query volume per client. Adjust rate, burst, and IP prefix aggregation for effective traffic management. Allowlist specific IPs to bypass rate limits.

```yaml
rateLimit:
  enable: true
  rate: 50           # avg queries per second per client
  burst: 100         # optional, default rate × 2; must be >= rate
  ipv4Prefix: 32     # default: aggregate by /32 (one IP = one client)
  ipv6Prefix: 64     # default: aggregate by /64 (one subscriber prefix)
  allowlist:
    - 127.0.0.1/32   # localhost (recommended if /api/query is used)
    - ::1/128
    - 10.0.0.0/8
    - 192.168.0.0/16

```

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

### Prometheus Query for Cache Hit/Miss Ratio

Source: https://0xerr0r.github.io/blocky/latest/blocky-grafana.json

Calculates the cache hit ratio as a percentage. A 100% hit ratio means all queries were served from the cache, while 0% means all queries required external DNS resolution. Use this to assess cache efficiency.

```prometheus
sum(increase(blocky_cache_hits_total[$__range])) / (sum(increase(blocky_cache_hits_total[$__range])) + sum(increase(blocky_cache_misses_total[$__range])))
```

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

### Traefik Configuration for Blocky

Source: https://0xerr0r.github.io/blocky/latest/network_configuration

This configuration sets up Traefik to proxy requests to the Blocky service. Traefik automatically handles the X-Forwarded-For header.

```yaml
http:
  services:
    blocky:
      loadBalancer:
        servers:
          - url: "http://blocky-backend:4000"
  middlewares: {}
  # Traefik sets X-Forwarded-For automatically; no extra config needed.
```

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

### Prometheus Query for Denylist Entries

Source: https://0xerr0r.github.io/blocky/latest/blocky-grafana.json

Calculates the total number of denylist entries by summing the `blocky_denylist_cache_entries` and `blocky_denylist_cache` metrics. It normalizes this count by the number of active `up` targets for the specified job.

```PromQL
(sum(blocky_denylist_cache_entries) or sum(blocky_denylist_cache)) / sum(up{job=~"$job"})
```

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

### CSV Query Log Configuration

Source: https://0xerr0r.github.io/blocky/latest/configuration

Configure CSV format for query logging, specifying the target directory, retention period, and fields to log.

```yaml
queryLog:
  type: csv
  target: /logs
  logRetentionDays: 7
  fields:
  - clientIP
  - duration
  flushInterval: 30s
```

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

### Percentage of Blocked Queries

Source: https://0xerr0r.github.io/blocky/latest/blocky-grafana.json

Calculates and displays the percentage of DNS queries that were blocked by Blocky. It compares the increase in blocked query metrics against the total increase in all queries over the specified time range.

```promql
sum(increase(blocky_response_total{response_type="BLOCKED"}[$__range])) / sum(increase(blocky_query_total[$__range])) 
```

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

### Configure Nginx as a Reverse Proxy for Blocky

Source: https://0xerr0r.github.io/blocky/latest/network_configuration

This nginx configuration forwards DNS queries to the Blocky backend and sets the X-Forwarded-For header to the client's IP address.

```nginx
location /dns-query {
    proxy_pass http://blocky-backend:4000/dns-query;
    proxy_set_header X-Forwarded-For $remote_addr;
}
```

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

### Domain-Specific Resolver Configuration

Source: https://0xerr0r.github.io/blocky/latest/configuration

Specify which DNS resolver(s) should be used for queries to a particular domain, including all its subdomains. Multiple resolvers can be listed, separated by commas.

```yaml
# optional: definition, which DNS resolver(s) should be used for queries to the domain (with all sub-domains). Multiple resolvers must be separated by a comma

```

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

### Count Queries Per Client (30m)

Source: https://0xerr0r.github.io/blocky/latest/blocky-query-grafana-postgres.json

This query counts the number of queries per client, grouped into 30-minute intervals. It filters by response type, client name, and an optional search string.

```json
{
          "format": "time_series",
          "group": [],
          "metricColumn": "none",
          "rawQuery": true,
          "rawSql": "SELECT\n $__timeGroupAlias(t.request_Ts, '30m'),\n  t.client_name,\n  count(*) as c\nFROM log_entries t\nWHERE\n  $__timeFilter(t.request_Ts) and \n  t.response_type in ($response_type) and \n  t.client_name in ($client_name) and \n  (length('$question') = 0 or POSITION(lower('$question') IN t.question_name) > 0)\nGROUP BY 1,2\nORDER BY 1",
          "refId": "A",
          "select": [
            [
              {
                "params": [
                  "duration_ms"
                ],
                "type": "column"
              }
            ]
          ],
          "table": "log_entries",
          "timeColumn": "request_ts",
          "timeColumnType": "timestamp",
          "where": [
            {
              "name": "$__timeFilter",
              "params": [],
              "type": "macro"
            }
          ]
        }
```

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

### Enable Automatic Fork Synchronization

Source: https://0xerr0r.github.io/blocky/latest/additional_information

To enable automatic synchronization of your fork with the upstream repository, create a secret named `FORK_SYNC_TOKEN` containing a GitHub access token with write permissions. The workflow syncs the main branch every 30 minutes.

```yaml
name: Fork Sync

on:
  schedule:
    - cron: '*/30 * * * *'
  workflow_dispatch:

jobs:
  sync_fork:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          persist-credentials: false

      - name: Sync fork
        uses:wearereasonable/actions-sync@v1
        with:
          github_token: ${{ secrets.FORK_SYNC_TOKEN }}
          source_repo: '0xerr0r/blocky'
          source_branch: 'main'
          destination_branch: 'main'

```

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

### Configure Block TTL

Source: https://0xerr0r.github.io/blocky/latest/configuration

Set the Time-To-Live (TTL) for blocked domain responses. This customizes how long clients will ask for blocked domains again. The default is 6 hours.

```yaml
blocking:
  blockType: 192.100.100.15, 2001:0db8:85a3:08d3:1319:8a2e:0370:7344
  blockTTL: 10s

```

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

### Configure Client-Specific Upstream DNS Groups

Source: https://0xerr0r.github.io/blocky/latest/configuration

Define multiple upstream groups to serve different clients based on their IP address, client name, or subnet. The client matching logic follows a strict order: IP, client name, then CIDR.

```yaml
upstreams:
  groups:
    default:
      - 5.9.164.112
      - 1.1.1.1
      - tcp-tls:fdns1.dismail.de:853
      - https://dns.digitale-gesellschaft.ch/dns-query
    laptop*:
      - 123.123.123.123
    10.43.8.67/28:
      - 1.1.1.1
      - 9.9.9.9

```