diff --git a/config/upstream.go b/config/upstream.go index 80caa4f3..b6cf6876 100644 --- a/config/upstream.go +++ b/config/upstream.go @@ -87,7 +87,7 @@ func (u *Upstream) UnmarshalText(data []byte) error { return nil } -// ParseUpstream creates new Upstream from passed string in format [net]:host[:port][/path][#commonname] +// ParseUpstream creates new Upstream from passed string in format [net:]host[:port][/path][#commonname] // or DNS Stamp format: sdns://... func ParseUpstream(upstream string) (Upstream, error) { // Check if it's a DNS stamp diff --git a/docs/config.schema.json b/docs/config.schema.json index cf7d9df9..54dce076 100644 --- a/docs/config.schema.json +++ b/docs/config.schema.json @@ -41,7 +41,7 @@ "additionalProperties": { "items": { "type": "string", - "description": "Upstream DNS server: [net]:host[:port][/path][#commonName] or sdns://...", + "description": "Upstream DNS server: [net:]host[:port][/path][#commonName] or sdns://...", "examples": [ "tcp+udp:1.1.1.1", "https://dns.google/dns-query", @@ -1661,7 +1661,7 @@ "additionalProperties": { "items": { "type": "string", - "description": "Upstream DNS server: [net]:host[:port][/path][#commonName] or sdns://...", + "description": "Upstream DNS server: [net:]host[:port][/path][#commonName] or sdns://...", "examples": [ "tcp+udp:1.1.1.1", "https://dns.google/dns-query", diff --git a/docs/config.yml b/docs/config.yml index 3b734efc..7fbe0587 100644 --- a/docs/config.yml +++ b/docs/config.yml @@ -7,7 +7,7 @@ upstreams: strategy: fast groups: # these external DNS resolvers will be used. Blocky picks 2 random resolvers from the list for each query - # format for resolver: [net:]host:[port][/path][#commonname]. net could be empty (default, shortcut for tcp+udp), tcp+udp, tcp, udp, tcp-tls or https (DoH). If port is empty, default port will be used (53 for udp and tcp, 853 for tcp-tls, 443 for https (Doh)) + # format for resolver: [net:]host[:port][/path][#commonname]. net could be empty (default, shortcut for tcp+udp), tcp+udp, tcp-tls, https (DoH) or quic (DoQ). If port is empty, default port will be used (53 for tcp+udp, 853 for tcp-tls and quic, 443 for https (DoH)) # alternative format: DNS Stamp (sdns://...) - compact format that encodes all parameters including optional certificate hashes for automatic certificate pinning # this configuration is mandatory, please define at least one external DNS resolver default: diff --git a/docs/configuration.md b/docs/configuration.md index a32e1233..0600c714 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -184,17 +184,21 @@ following network protocols (net part of the resolver URL): Per default blocky uses the `parallel_best` upstream strategy where blocky picks 2 random resolvers from the list for each query and returns the answer from the fastest one. -Each resolver must be defined as a string in following format: `[net:]host:[port][/path][#commonName]`. +Each resolver must be defined as a string in following format: `[net:]host[:port][/path][#commonName]`. | Parameter | Type | Mandatory | Default value | | ---------- | -------------------------------- | --------- | ------------------------------------------------- | | net | enum (tcp+udp, tcp-tls, https or quic) | no | tcp+udp | | host | IP or hostname | yes | | | port | int (1 - 65535) | no | 53 for udp/tcp, 853 for tcp-tls and quic, 443 for https | +| path | string | no | only relevant for https (DoH); ignored for other protocols | | commonName | string | no | the host value | The `commonName` parameter overrides the expected certificate common name value used for verification. +The `path` parameter is only used by the `https` (DoH) protocol, where it is the URL path of the +DNS endpoint (for example `/dns-query`). It is accepted but ignored for all other protocols. + #### DNS Stamp Format As an alternative to the traditional format, Blocky supports **DNS Stamps** (`sdns://...`), which encode all connection parameters in a compact, shareable format. diff --git a/docs/installation.md b/docs/installation.md index 2338e4d7..dd35e8c5 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -141,6 +141,7 @@ ports: ## Container configuration file You can define the location of the config file in the container with environment variable `BLOCKY_CONFIG_FILE`. +Using this environment variable a folder containing configuration files can also be specified. Default value is `/app/config.yml`. !!! note "Legacy: `CONFIG_FILE`" diff --git a/tools/schemagen/overrides.go b/tools/schemagen/overrides.go index 723598c9..4f7829d6 100644 --- a/tools/schemagen/overrides.go +++ b/tools/schemagen/overrides.go @@ -122,7 +122,7 @@ type enumValuer interface { func stringForms() map[reflect.Type]stringSpec { return map[reflect.Type]stringSpec{ reflect.TypeFor[config.Upstream](): { - "Upstream DNS server: [net]:host[:port][/path][#commonName] or sdns://...", + "Upstream DNS server: [net:]host[:port][/path][#commonName] or sdns://...", []string{"tcp+udp:1.1.1.1", "https://dns.google/dns-query", "tcp-tls:1.1.1.1:853"}, }, reflect.TypeFor[config.BytesSource](): {