Skip to content

Configurations

parameter Parameter function Default value Value type Example
server-name DNS name host name/smartdns any string like hostname server-name smartdns
bind DNS listening port number [::]:53 Support binding multiple ports
IP:PORT@DEVICE: server IP, port number, and device.
[-group]: The DNS server group used when requesting.
[-no-rule-addr]: Skip the address rule.
[-no-rule-nameserver]: Skip the Nameserver rule.
[-no-rule-ipset]: Skip the Ipset or nftset rules.
[-no-rule-soa]: Skip address SOA(#) rules.
[-no-dualstack-selection]: Disable dualstack ip selection.
[-no-speed-check]: Disable speed measurement.
[-no-cache]: stop caching
[-force-aaaa-soa]: force AAAA query return SOA.
[-force-https-soa]: force HTTPS query return SOA.
[-no-serve-expired]: no lazy cache.
[-ipset]: set IPSet, refer to ipset option
[-nftset]: set nftset, refer to nftset option
bind :53@eth0
bind-tcp TCP mode DNS listening port number [::]:53 Support binding multiple ports
IP:PORT@DEVICE: server IP, port number and device.
[-group]: The DNS server group used when requesting.
[-no-rule-addr]: Skip the address rule.
[-no-rule-nameserver]: Skip the Nameserver rule.
[-no-rule-ipset]: Skip the ipset or nftset rules.
[-no-rule-soa]: Skip address SOA(#) rules.
[-no-dualstack-selection]: Disable dualstack ip selection.
[-no-speed-check]: Disable speed measurement.
[-no-cache]: stop caching
[-force-aaaa-soa]: force AAAA query return SOA.
[-force-https-soa]: force HTTPS query return SOA.
[-no-serve-expired]: no lazy cache.
[-ipset]: set IPSet, refer to ipset option
[-nftset]: set nftset, refer to nftset option
bind-tcp :53
bind-tls DOT mode DNS listening port number [::]:853 Support binding multiple ports
IP:PORT@DEVICE: server IP, port number and device.
[-group]: The DNS server group used when requesting.
[-no-rule-addr]: Skip the address rule.
[-no-rule-nameserver]: Skip the Nameserver rule.
[-no-rule-ipset]: Skip the ipset or nftset rules.
[-no-rule-soa]: Skip address SOA(#) rules.
[-no-dualstack-selection]: Disable dualstack ip selection.
[-no-speed-check]: Disable speed measurement.
[-no-cache]: stop caching
[-force-aaaa-soa]: force AAAA query return SOA.
[-force-https-soa]: force HTTPS query return SOA.
[-no-serve-expired]: no lazy cache.
[-ipset]: set IPSet, refer to ipset option
[-nftset]: set nftset, refer to nftset option
bind-tls :853
bind-https DOH mode DNS listening port number [::]:853 Support binding multiple ports
IP:PORT@DEVICE: server IP, port number and device.
[-group]: The DNS server group used when requesting.
[-no-rule-addr]: Skip the address rule.
[-no-rule-nameserver]: Skip the Nameserver rule.
[-no-rule-ipset]: Skip the ipset or nftset rules.
[-no-rule-soa]: Skip address SOA(#) rules.
[-no-dualstack-selection]: Disable dualstack ip selection.
[-no-speed-check]: Disable speed measurement.
[-no-cache]: stop caching
[-force-aaaa-soa]: force AAAA query return SOA.
[-force-https-soa]: force HTTPS query return SOA.
[-no-serve-expired]: no lazy cache.
[-ipset]: set IPSet, refer to ipset option
[-nftset]: set nftset, refer to nftset option
bind-https :853
bind-cert-file SSL Certificate file path smartdns-cert.pem path bind-cert-file cert.pem
bind-cert-key-file SSL Certificate key file path none smartdns-key.pem bind-cert-key-file key.pem
bind-cert-key-pass SSL Certificate key file password none string bind-cert-key-pass password
cache-size Domain name result cache number Auto: Set cache size by memory size. integer cache-size 512
cache-persist enable persist cache Auto: Enabled if the location of cache-file has more than 128MB of free space. [yes|no] cache-persist yes
cache-file cache persist file /var/cache/
smartdns.cache
path cache-file /tmp/smartdns.cache
cache-checkpoint-time cache persist time 24 hours 0 or greater than 120, 0: disable, other: persis time in seconds cache-checkpoint-time 0
tcp-idle-time TCP connection idle timeout 120 integer tcp-idle-time 120
rr-ttl Domain name TTL Remote query result number greater than 0 rr-ttl 600
rr-ttl-min Domain name Minimum TTL Remote query result number greater than 0 rr-ttl-min 60
local-ttl ttl for address and host rr-ttl-min number greater than 0 local-ttl 600
rr-ttl-reply-max Domain name Minimum Reply TTL Remote query result number greater than 0 rr-ttl-reply-max 60
rr-ttl-max Domain name Maximum TTL Remote query result number greater than 0 rr-ttl-max 600
max-reply-ip-num Maximum number of IPs returned to the client 8 number of IPs, 1~16 max-reply-ip-num 1
max-query-limit Maximum concurrent number of requests. 65535 Number of requests max-query-limit 1000
log-level log level error off,fatal,error,warn,notice,info,debug log-level error
log-file log path /var/log/
smartdns/
smartdns.log
File Pah log-file /var/log/smartdns/smartdns.log
log-size log size 128K number+K,M,G log-size 128K
log-num archived log number 2 for openwrt, 8 for other system Integer, 0 means turn off the log log-num 2
log-file-mode archived log file mode 0640 Integer log-file-mode 644
log-console enable output log to console no [yes|no] log-console yes
log-console enable output log to syslog no [yes|no] log-console yes
audit-enable audit log enable no [yes|no] audit-enable yes
audit-file audit log file /var/log/
smartdns/
smartdns-audit.log
File Path audit-file /var/log/smartdns/smartdns-audit.log
audit-size audit log size 128K number+K,M,G audit-size 128K
audit-num archived audit log number 2 Integer, 0 means turn off the log audit-num 2
audit-file-mode archived audit log file mode 0640 Integer audit-file-mode 644
audit-console enable output audit log to console no [yes|no] audit-console yes
audit-syslog enable output audit log to syslog no [yes|no] audit-syslog yes
acl-enable enable ACL no [yes|no]
Used with client-rules.
acl-enable yes
group-begin rule group start None Group name:
Used with group-end, when enabled, the configuration items after group-begin will be set to the corresponding group until group-end is encountered.
group-begin group-name
group-end rule group end None Used with group-begin. group-end
group-match Match group rules None Use the corresponding rule group when conditions are met.
[-g\|group group-name]: Specify the rule group, optional. If not specified, use the group from the current group-begin.
[-client-ip ip-set\|ip/cidr\|mac address]: Specify the client IP address, use the specified group when matched.
[-domain domain]: Specify the domain name, use the specified group when matched.
group-match -client-ip 1.1.1.1 -domain a.com
group-match -client-ip ip-set:clients -domain domain-set:domainlist
conf-file additional conf file None file [-g|-group group-name]
file: File path, wildcard.
[-g|-group group-name]: The rule group to which the corresponding configuration file configuration belongs.
conf-file /etc/smartdns/smartdns.more.conf
conf-file *.conf
conf-file *.conf -g group-tv
server Upstream UDP DNS server None Repeatable
[ip][:port]|URL: Server IP, port optional OR URL.
[-blacklist-ip]: The "-blacklist-ip" parameter is to filtering IPs which is configured by "blacklist-ip".
[-whitelist-ip]: whitelist-ip parameter specifies that only the IP range configured in whitelist-ip is accepted.
[-g|-group [group] ...]: The group to which the DNS server belongs, such as office, foreign, use with nameserver.
[-e|-exclude-default-group]: Exclude DNS servers from the default group.
[-set-mark mark]: set mark on packets
[-p|-proxy name]: set proxy server
[-b|-bootstrap-dns]: set as bootstrap dns server
[-subnet]:set per server edns-client-subnet.
[-interface]: bind to interface.
server 8.8.8.8:53 -blacklist-ip
server tls://8.8.8.8
server-tcp Upstream TCP DNS server None Repeatable
[ip][:port]: Server IP, port optional.
[-blacklist-ip]: The "-blacklist-ip" parameter is to filtering IPs which is configured by "blacklist-ip".
[-whitelist-ip]: whitelist-ip parameter specifies that only the IP range configured in whitelist-ip is accepted.
[-g|-group [group] ...]: The group to which the DNS server belongs, such as office, foreign, use with nameserver.
[-e|-exclude-default-group]: Exclude DNS servers from the default group
[-set-mark mark]: set mark on packets
[-p|-proxy name]: set proxy server
[-b|-bootstrap-dns]: set as bootstrap dns server
[-subnet]:set per server edns-client-subnet.
[-interface]: bind to interface.
server-tcp 8.8.8.8:53
server-tls Upstream TLS DNS server None Repeatable
[ip][:port]: Server IP, port optional.
[-spki-pin [sha256-pin]]: TLS verify SPKI value, a base64 encoded SHA256 hash
[-host-name]:TLS Server name. - to disable SNI name.
[-host-ip]: host ip address.
[-tls-host-verify]: TLS cert hostname to verify.
[-k|-no-check-certificate]: No check certificate.
[-blacklist-ip]: The "-blacklist-ip" parameter is to filtering IPs which is configured by "blacklist-ip".
[-whitelist-ip]: whitelist-ip parameter specifies that only the IP range configured in whitelist-ip is accepted.
[-g|-group [group] ...]: The group to which the DNS server belongs, such as office, foreign, use with nameserver.
[-e|-exclude-default-group]: Exclude DNS servers from the default group
[-set-mark mark]: set mark on packets
[-p|-proxy name]: set proxy server
[-b|-bootstrap-dns]: set as bootstrap dns server
[-subnet]:set per server edns-client-subnet.
[-interface]: bind to interface.
server-tls 8.8.8.8:853
server-https Upstream HTTPS DNS server None Repeatable
https://[host][:port]/path: Server IP, port optional.
[-spki-pin [sha256-pin]]: TLS verify SPKI value, a base64 encoded SHA256 hash
[-host-name]:TLS Server name
[-http-host]: http header host.
[-host-ip]: host ip address.
[-tls-host-verify]: TLS cert hostname to verify.
[-k|-no-check-certificate]: No check certificate.
[-blacklist-ip]: The "-blacklist-ip" parameter is to filtering IPs which is configured by "blacklist-ip".
[-whitelist-ip]: whitelist-ip parameter specifies that only the IP range configured in whitelist-ip is accepted.
[-g|-group [group] ...]: The group to which the DNS server belongs, such as office, foreign, use with nameserver.
[-e|-exclude-default-group]: Exclude DNS servers from the default group
[-set-mark mark]: set mark on packets
[-p|-proxy name]: set proxy server
[-b|-bootstrap-dns]: set as bootstrap dns server
[-subnet]:set per server edns-client-subnet.
[-interface]: bind to interface.
server-https https://cloudflare-dns.com/dns-query
proxy-server proxy server None Repeatable.
proxy-server URL
[URL]: [socks5\|http]://[username:password@]host:port
[-name]: proxy server name.
proxy-server socks5://user:pass@1.2.3.4:1080 -name proxy
speed-check-mode Speed ​​mode ping,tcp:80,tcp:443 [ping|tcp:[80]|none] speed-check-mode ping,tcp:80,tcp:443
response-mode First query response mode first-ping Mode: [first-ping|fastest-ip|fastest-response]
[first-ping]: The fastest dns + ping response mode, DNS query delay + ping delay is the shortest;
[fastest-ip]: The fastest IP address mode, return the fastest ip address, may take some time to test speed.
[fastest-response]: The fastest response DNS result mode, the DNS query waiting time is the shortest.
response-mode first-ping
expand-ptr-from-address Whether to expand the address record corresponding to PTR record no [yes|no] expand-ptr-from-address yes
address Domain IP address None address /[*|-]domain/[ip1[,ip2,...]|-|-4|-6|#|#4|#6]
- for ignore this rule.
# for return SOA
4 for IPV4
6 for IPV6
* at the beginning means wildcard
- means the main domain name at the beginning
* and - can only be at the beginning of the domain name, other positions will not take effect.
If no domain name is specified, it applies to all domain names.
address /www.example.com/1.2.3.4
address /www.example.com/::1
address /example.com/1.2.3.4,5.6.7.8
address /*-a.example.com/
address /*.example.com/
address /-.example.com/
address #6
address #4
cname set cname to domain None cname /domain/target
- for ignore this rule.
set cname to domain.
cname /www.example.com/cdn.example.com
srv-record add srv record None srv-record /domain/[target][,port][,priority][,weight] srv-record /_vlmcs._tcp/example.com,1688,1,1
https-record Specify HTTPS record None https-record /domain/[target=][,port=][,priority=][,ech=][,ipv4hint=][,ipv6hint=][,alpn=][,noipv4hint][,noipv6hint][#][-]:
[target]: target parameter
[port]: port parameter
[priority]: priority parameter
[ech]: ECH parameter
[alpn]: alph parameter
[ipv4hint]: IPV4 address
[ipv6hint]: IPV6 address
[noipv4hint]: Filter IPV4 addresses
[noipv6hint]: Filter IPV6 addresses
# indicates return SOA
- indicates ignore rule
https-record /example.com/ech="aaa"
https-record /example.com/alpn="h2,http/1.1"
https-record noipv4hint,noipv6hint
https-record #
https-record /example.com/-
ddns-domain Specifies the DDNS domain name None ddns-domain domainin.com, used to resolve the specified domain name to the IP address of the host where smartdns resides. ddns-domain example.com
dns64 dns64 translation None dns64 ip-prefix/mask
ipv6 prefix and mask.
dns64 64:ff9b::/96
mdns-lookup Enable mDNS lookup no [yes|no] mdns-lookup yes
hosts-file set hosts file None hosts file path. hosts-file /etc/hosts
edns-client-subnet DNS ECS None edns-client-subnet ip-prefix/mask
set EDNS client subnet
edns-client-subnet 1.2.3.4/23
nameserver To query domain with specific server group None nameserver /domain/[group|-], group is the group name, - means ignore this rule, use the -group parameter in the related server nameserver /www.example.com/office
ipset Domain IPSet None ipset [/domain/][ipset|-|#[4|6]:[ipset|-][,#[4|6]:[ipset|-]]], - for ignore this rule. ipset /www.example.com/#4:dns4,#6:-
ipset ipsetname
ipset-timeout ipset timeout enable no [yes|no] ipset-timeout yes
ipset-no-speed When speed check fails, set the ip address of the domain name to the ipset None ipset | #[4|6]:ipset ipset-no-speed #4:ipset4,#6:ipset6
ipset-no-speed ipset
nftset Domain nftset None nftset [/domain/][#4|#6|-]:[family#nftable#nftset|-][,#[4|6]:[family#nftable#nftset|-]]]
- to ignore this rule.
the valid families are inet and ip for ipv4 addresses while the valid ones are inet and ip6 for ipv6 addresses
due to the limitation of nftable
two types of addresses have to be stored in two sets
nftset /www.example.com/#4:inet#tab#dns4,#6:-
nftset #4:inet#tab#dns4,#6:-
nftset-timeout nftset timeout enable no [yes|no] nftset-timeout yes
nftset-no-speed When speed check fails, set the ip address of the domain name to the nftset None nftset-no-speed [#4|#6]:[family#nftable#nftset][,#[4|6]:[family#nftable#nftset]]]
the valid families are inet and ip for ipv4 addresses while the valid ones are inet and ip6 for ipv6 addresses
due to the limitation of nftable
two types of addresses have to be stored in two sets
nftset-no-speed #4:inet#tab#set4
nftset-debug nftset debug enable no [yes|no] nftset-debug yes
domain-rules set domain rules None domain-rules /domain/ [-rules...]
[-c|-speed-check-mode]: set speed check mode, same as parameter speed-check-mode
[-a|-address]: same as parameter address
[-n|-nameserver]: same as parameter nameserver
[-p
-ipset]: same as parameter nftset
[-t|-nftset]: same as parameter nftset
[-d|-dualstack-ip-selection]: same as parameter dualstack-ip-selection
[-no-serve-expired]: disable serve expired
[-rr-ttl|-rr-ttl-min|-rr-ttl-max]: same as parameter: rr-ttl, rr-ttl-min, rr-ttl-max
[-no-cache]:not cache this domain.
[-r|-response-mode]:response mode, same as response-mode
[-delete]: delete rule
[no-ip-alias]: ignore ip-alias rule
domain-set collection of domains None domain-set [options...]
[-n|-name]: name of set
[-t|-type] [list]: set type, only support list, one domain per line
[-f|-file]: file path of domain set
used with address, nameserver, ipset, nftset, example: /domain-set:[name]/
domain-set -name set -type list -file /path/to/list
address /domain-set:set/1.2.4.8
client-rules Client rules None [ip-set|ip/subnet|mac address] [-g|group group-name] [-rules...]
Set client rules and rule groups, the rule parameters are the same as bind, please refer to bind for specific parameter options. Generally used with group-begin, group-end.
client-rules 192.168.1.1 -g group-tv
client-rules 00:01:02:03:04:05
client-rules ip-set:clients
bogus-nxdomain bogus IP address None [IP/subnet], Repeatable bogus-nxdomain 1.2.3.4/16
ignore-ip ignore ip address None [ip/subnet], Repeatable ignore-ip 1.2.3.4/16
whitelist-ip ip whitelist None [ip/subnet], Repeatable, When the filtering server responds IPs in the IP whitelist, only result in whitelist will be accepted whitelist-ip 1.2.3.4/16
blacklist-ip ip blacklist None [ip/subnet], Repeatable, When the filtering server responds IPs in the IP blacklist, The result will be discarded directly blacklist-ip 1.2.3.4/16
ip-alias IP alias None [ip/subnet] ip1[,[ip2]...],Repeatable ip-alias 1.2.3.4/16 4.5.6.7
ip-rules IP rules None [ip/subnet] [-rules...]
[-blacklist-ip]: same as parameter blacklist-ip
[-whitelist-ip]: same as parameter whitelist-ip
[-bogus-nxdomain]: same as parameter bogus-nxdomain
[-ignore-ip]: same as parameter ignore-ip
[-ip-alias]: same as parameter ip-alias
ip-rules 1.2.3.4/16 -whitelist-ip
ip-set collection of IPs None ip-set [options...]
[-n|-name]:name of ip set
[-t|-type]:set type, only support list, one domain per line
[-f|-file]:file path of ip set。
used with ip-rules, ip-alias, example: ip-set:[name]
ip-set -name set -type list -file /path/to/list
ip-rules ip-set:set -whitelist-ip
force-AAAA-SOA force AAAA query return SOA no [yes|no] force-AAAA-SOA yes
force-qtype-SOA force specific qtype return SOA qtype id [qtypeid | idstart-id-end | ...]
- prefix means clear qtype.
force-qtype-SOA 65 28 128-256
force-qtype-SOA -
force-qtype-SOA -,23,24
prefetch-domain domain prefetch feature no [yes|no] prefetch-domain yes
dnsmasq-lease-file Support reading dnsmasq dhcp file to resolve local hostname None dnsmasq dhcp lease file dnsmasq-lease-file /var/lib/misc/dnsmasq.leases
serve-expired Cache serve expired feature yes [yes|no], Attempts to serve old responses from cache with a TTL of 0 in the response without waiting for the actual resolution to finish. serve-expired yes
serve-expired-ttl Cache serve expired limit TTL 0 second, 0: disable, > 0 seconds after expiration serve-expired-ttl 0
serve-expired-reply-ttl TTL value to use when replying with expired data 5 second, 0: disable, > 0 seconds after expiration serve-expired-reply-ttl 30
serve-expired-prefetch-time Prefetch time when serve expired 28800 second,prefetch time serve-expired-prefetch-time 86400
dualstack-ip-selection Dualstack ip selection yes [yes|no] dualstack-ip-selection yes
dualstack-ip-selection-threshold Dualstack ip select thresholds 10ms millisecond dualstack-ip-selection-threshold [0-1000]
no-pidfile no create pid file no [yes|no] no-pidfile yes
no-daemon no run as daemon no [yes|no] no-daemon yes
restart-on-crash restart when service crash no [yes|no] restart-on-crash yes
socket-buff-size socket buffer size size 0~1MB socket-buff-size 256K
user run as user root user [username] user nobody
ca-file certificate file /etc/ssl/certs/
ca-certificates.crt
path ca-file /etc/ssl/certs/ca-certificates.crt
ca-path certificates path /etc/ssl/certs path ca-path /etc/ssl/certs

Command Line Options

The command line options for smartdns are as follows, you can also use smartdns -h to view the help.

Option Function Default Value Description
-f Run in foreground None By default, the program runs as a background daemon.
-c Configuration file path /etc/smartdns/smartdns.conf Path to the configuration file.
-p PID file /run/smartdns.pid Path to the process PID file.
-R Automatic restart on exception None Automatically restart the process on exception.
-S Generate coredump on crash None Generate a coredump file on process crash for debugging purposes.
-x Log to terminal None Output logs to the terminal.
-v Display version None Display the version of smartdns.
-h Display command line help None Display the command line help.