lazydns

Environment Variable Overrides

lazydns supports overriding configuration values via environment variables at runtime. This is useful for containerized deployments and CI/CD pipelines where configuration needs to be adjusted dynamically without modifying the YAML file.

Overview

The configuration loader will automatically apply environment variable overrides when loading the YAML configuration. Overrides happen after YAML deserialization but before validation, allowing for flexible configuration management.

Patterns

1. Top-Level Log Configuration

Override top-level logging settings using these environment variables:

Variable	Config Field	Example	Valid Values
`LOG_LEVEL`	`log.level`	`debug`	`trace`, `debug`, `info`, `warn`, `error`
`LOG_FORMAT`	`log.format`	`json`	`text`, `json`
`LOG_FILE`	`log.file`	`/var/log/lazydns.log`	Any file path
`LOG_ROTATE`	`log.rotate`	`daily`	`never`, `daily`, `hourly`, `size:100M`

Note: The time_format option (and LOG_TIME_FORMAT) has been removed; logs now use local time by default.

2. Server Configuration

Override server settings using these environment variables:

Variable	Config Field	Example	Valid Values
`ADMIN_ENABLED`	`admin.enabled`	`true`	`true`, `false`, `1`, `0`, `yes`, `no`
`ADMIN_ADDR`	`admin.addr`	`127.0.0.1:8080`	Any valid address:port
`METRICS_ENABLED`	`metrics.enabled`	`true`	`true`, `false`, `1`, `0`, `yes`, `no`
`METRICS_ADDR`	`metrics.addr`	`127.0.0.1:9090`	Any valid address:port

3. Plugin Arguments

Override plugin arguments using the pattern:

PLUGINS_<TAG>_ARGS_<KEY>=value

Where:

<TAG> is the plugin tag name (normalized to lowercase, _ → -)
<KEY> is the argument key (normalized to lowercase, _ → -)
value is parsed as YAML (supports numbers, booleans, strings, arrays)

Examples

Override plugin server URL:

export PLUGINS_ADD_GFWLIST_ARGS_SERVER="http://10.100.100.1"

Override cache size:

export PLUGINS_CACHE_ARGS_SIZE="2048"

Override cache negative TTL:

export PLUGINS_CACHE_ARGS_NEGATIVE_TTL="3600"

Override enable-prefetch flag:

export PLUGINS_CACHE_ARGS_ENABLE_PREFETCH="true"

Value Type Conversion

Environment variable values are automatically converted based on their format:

Input	Parsed As	Example
`123`	Number	`2048` → u64
`true`/`false`	Boolean	`true` → bool
`[1,2,3]`	Array	`[8.8.8.8, 1.1.1.1]` → Sequence
`text`	String	`debug` → String

Usage Examples

Container Deployment

docker run -e LOG_FORMAT=json \
           -e LOG_LEVEL=info \
           -e ADMIN_ADDR=0.0.0.0:8080 \
           -e METRICS_ENABLED=true \
           -e METRICS_ADDR=0.0.0.0:9090 \
           -e PLUGINS_CACHE_ARGS_SIZE=4096 \
           -v /path/to/config.yaml:/etc/lazydns/config.yaml \
           lazydns:latest

Docker Compose

services:
  lazydns:
    image: lazydns:latest
    environment:
      LOG_FORMAT: json
      LOG_LEVEL: debug
      ADMIN_ENABLED: true
      ADMIN_ADDR: "0.0.0.0:8080"
      METRICS_ENABLED: true
      METRICS_ADDR: "0.0.0.0:9090"
      PLUGINS_ADD_GFWLIST_ARGS_SERVER: "http://list-server:8080"
      PLUGINS_CACHE_ARGS_SIZE: "2048"
    volumes:
      - ./config.yaml:/etc/lazydns/config.yaml

Kubernetes

env:
  - name: LOG_LEVEL
    value: "info"
  - name: LOG_FORMAT
    value: "json"
  - name: ADMIN_ENABLED
    value: "true"
  - name: ADMIN_ADDR
    value: "0.0.0.0:8080"
  - name: METRICS_ENABLED
    value: "true"
  - name: METRICS_ADDR
    value: "0.0.0.0:9090"
  - name: PLUGINS_CACHE_ARGS_SIZE
    value: "4096"
  - name: PLUGINS_ADD_GFWLIST_ARGS_SERVER
    value: "http://list-server.default:8080"

CI/CD Pipeline

#!/bin/bash
export LOG_FORMAT=json
export LOG_LEVEL=warn
export ADMIN_ENABLED=true
export ADMIN_ADDR=0.0.0.0:8080
export METRICS_ENABLED=true
export METRICS_ADDR=0.0.0.0:9090
export PLUGINS_CACHE_ARGS_NEGATIVE_TTL=7200
./lazydns -c /etc/config.yaml

Configuration File Example

You don’t need to modify the YAML file; these are typically set in YAML directly, but can now be overridden:

admin:
  enabled: true # Can be overridden by ADMIN_ENABLED
  addr: "127.0.0.1:8080" # Can be overridden by ADMIN_ADDR

metrics:
  enabled: false # Can be overridden by METRICS_ENABLED
  addr: "127.0.0.1:9090" # Can be overridden by METRICS_ADDR

log:
  level: info # Can be overridden by LOG_LEVEL
  format: text # Can be overridden by LOG_FORMAT
  file: null # Can be overridden by LOG_FILE

plugins:
  - tag: cache
    plugin_type: cache
    args:
      size: 1024 # Can be overridden by PLUGINS_CACHE_ARGS_SIZE
      negative_ttl: 300 # Can be overridden by PLUGINS_CACHE_ARGS_NEGATIVE_TTL

  - tag: add-gfwlist
    plugin_type: add-gfwlist
    args:
      server: http://default.com # Can be overridden by PLUGINS_ADD_GFWLIST_ARGS_SERVER

Priority

Environment variable overrides have the highest priority and will:

Override values from the YAML configuration file
Be applied before configuration validation
Be visible in logs (use LOG_LEVEL=debug to see applied overrides)

Testing

Run tests with single thread to avoid environment variable interference:

cargo test -- --test-threads=1

Troubleshooting

Override Not Applied

Check the variable name: Ensure it matches the pattern exactly
- Plugin tags must use _ which get converted to -
- Example: add_gfwlist → add-gfwlist
Check the plugin exists: If a plugin with the tag doesn’t exist, a warning is logged
Check value format: Numbers should be valid YAML numbers, booleans should be true/false
Enable debug logging: Set LOG_LEVEL=debug to see which overrides were applied

Invalid Value Format

If an environment variable value doesn’t parse as valid YAML (for non-string types), it will be treated as a string fallback.

Example:

export PLUGINS_CACHE_ARGS_SIZE="2048"    # Parsed as u64
export PLUGINS_CACHE_ARGS_SIZE="invalid"  # Falls back to string "invalid", may cause validation error

This site is open source. Improve this page.