ctrld/docs/ephemeral_mode.md

Ephemeral Mode

ctrld can operate in ephemeral mode which won't attempt to read or write any config file to disk. All necessary information is provided via command line flags.

Launch arguments

$ ctrld run --help
Run the DNS proxy server

Usage:
  ctrld run [flags]

Flags:
      --base64_config string        base64 encoded config
      --cache_size int              Enable cache defined amount of slots
      --cd string                   Control D resolver uid
  -c, --config string               Path to config file
  -d, --daemon                      Run as daemon
      --domains strings             list of domain to apply in a split DNS policy
  -h, --help                        help for run
      --listen string               listener address and port, in format: address:port
      --log string                  path to log file
      --primary_upstream string     primary upstream endpoint
      --secondary_upstream string   secondary upstream endpoint

Global Flags:
  -v, --verbose count   verbose log output, "-v" means query logging enabled, "-vv" means debug level logging enabled

For example:

ctrld run --listen=127.0.0.1:53 --primary_upstream=https://freedns.controld.com/p2 --secondary_upstream=8.8.8.8:53 --domains=*.company.int,*.net --log /path/to/log.log

Above command will be translated roughly to this config:

[service]
    log_level = "debug"
    log_path = "/path/to/log.log"

[network.0]
    name = "Network 0"
    cidrs = ["0.0.0.0/0"]

[upstream.0]
    name = "https://freedns.controld.com/p2"
    endpoint = "https://freedns.controld.com/p2"
    type = "doh"

[upstream.1]
    name = "8.8.8.8:53"
    endpoint = "8.8.8.8:53"
    type = "legacy"
	
[listener.0]
    ip = "127.0.0.1"
    port = 53

    [listener.0.policy]
        rules = [
            {"*.company.int" = ["upstream.1"]},
            {"*.net" = ["upstream.1"]},
        ]

Only listen and primary_upstream flags are required.

Base64 encoded config

ctrld can read a complete base64 encoded config via command line flag. This allows you to supply complex configurations.

ctrld run --base64_config="CltsaXN0ZW5lcl0KCiAgW2xpc3RlbmVyLjBdCiAgICBpcCA9ICIxMjcuMC4wLjEiCiAgICBwb3J0ID0gNTMKICAgIHJlc3RyaWN0ZWQgPSBmYWxzZQoKW25ldHdvcmtdCgogIFtuZXR3b3JrLjBdCiAgICBjaWRycyA9IFsiMC4wLjAuMC8wIl0KICAgIG5hbWUgPSAiTmV0d29yayAwIgoKW3Vwc3RyZWFtXQoKICBbdXBzdHJlYW0uMF0KICAgIGJvb3RzdHJhcF9pcCA9ICI3Ni43Ni4yLjExIgogICAgZW5kcG9pbnQgPSAiaHR0cHM6Ly9mcmVlZG5zLmNvbnRyb2xkLmNvbS9wMSIKICAgIG5hbWUgPSAiQ29udHJvbCBEIC0gQW50aS1NYWx3YXJlIgogICAgdGltZW91dCA9IDUwMDAKICAgIHR5cGUgPSAiZG9oIgoKICBbdXBzdHJlYW0uMV0KICAgIGJvb3RzdHJhcF9pcCA9ICI3Ni43Ni4yLjExIgogICAgZW5kcG9pbnQgPSAicDIuZnJlZWRucy5jb250cm9sZC5jb20iCiAgICBuYW1lID0gIkNvbnRyb2wgRCAtIE5vIEFkcyIKICAgIHRpbWVvdXQgPSAzMDAwCiAgICB0eXBlID0gImRvcSIK"