| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| docs:guide-user:base-system:dns_configuration [2019/04/07 11:03] – [MX RR] merged with dhcp#mx_rr vgaetera | docs:guide-user:base-system:dns_configuration [2019/04/10 10:52] – title vgaetera |
|---|
| ====== DNS configuration ====== | ====== DNS configuration ====== |
| The dns configuration is located in ''/etc/config/dhcp'' and controls both DNS and DHCP server options on the device (both DHCP and DNS services are implemented using //dnsmasq//). | Follow: [[docs:guide-user:base-system:dhcp|DNS and DHCP configuration /etc/config/dhcp]] |
| |
| In the default configuration this file contains one //common section// to specify DNS and daemon related options and one or more //DHCP pools// to define DHCP serving on network interfaces. | |
| |
| ===== Sections ===== | |
| Possible section types of the ''dhcp'' configuration file are defined below. Not all types may appear in the file and most of them are only needed for special configurations. The common ones are the //Common Options//, the //DHCP Pools// and //Static Leases//. | |
| |
| ==== Common Options ==== | |
| The config section type ''dnsmasq'' determines values and options relevant to the overall operation of dnsmasq | |
| and the DHCP options on all interfaces served. The following table lists all available options, their default value, | |
| as well as the corresponding //dnsmasq// command line option. See [[http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html|the dnsmasq man page]] for further details. | |
| |
| These are the default settings for the common options: | |
| |
| <code> | |
| config 'dnsmasq' | |
| option local '/lan/' | |
| option domain 'lan' | |
| option leasefile '/tmp/dhcp.leases' | |
| option resolvfile '/tmp/resolv.conf.auto' | |
| option domainneeded 1 | |
| option boguspriv 1 | |
| option filterwin2k 0 | |
| option localise_queries 1 | |
| option rebind_protection 1 | |
| option rebind_localhost 0 | |
| option expandhosts 1 | |
| option nonegcache 0 | |
| option authoritative 1 | |
| option readethers 1 | |
| </code> | |
| * Options: | |
| * ''local'' and ''domain'' enable //dnsmasq// to serve entries in ''/etc/hosts'', as well as DHCP client's names if configured under //lan// domain. | |
| * ''domainneeded'', ''boguspriv'', ''localise_queries'', and ''expandhosts'' ensure requests for local host names are not forwarded to upstream DNS servers. | |
| * ''authoritative'' makes router the only DHCP server on this network; clients get their IP lease a lot faster this way. | |
| * ''leasefile'' stores leases in a file so they can be picked up again if //dnsmasq// is restarted. | |
| * ''resolvfile'' tells //dnsmasq// to use this file to find upstream name servers; it gets created by the WAN DHCP or PPP client. | |
| * ''enable_tftp'' and ''tftp_root'' turn on the TFTP server and serve files from tftp_root. | |
| * May need to set server's IP on client, changing it by setting ''serverip'' (e.g. ''setenv serverip 192.168.1.10''). | |
| |
| ==== All Options ==== | |
| |
| ^ Name ^ Type ^ Default ^ Option ^ Description ^ | |
| | ''add_local_domain'' | boolean | ''1'' | | Add the local domain as search directive in resolv.conf. | | |
| | ''add_local_hostname'' | boolean | ''1'' | | Add A, AAAA, & PTR records only on DHCP served LAN. \\ :!: enhanced function available on Trunk with option ''add_local_fqdn'' | | |
| | ''add_local_fqdn'' | integer | ''1'' | | Add A, AAAA, & PTR records only on DHCP served LAN.\\ :!: ''add_local_fqdn'' on Trunk but not 17.01.0 \\ ''0''**:** Disable.\\ ''1''**:** Hostname on Primary Address.\\ ''2''**:** Hostname on All Addresses.\\ ''3''**:** FDQN on All Addresses.\\ ''4''**:** ''iface.host.domain'' on All Addresses. | | |
| | ''add_wan_fqdn'' | integer | ''0'' | | Labels WAN interfaces like ''add_local_fqdn'' instead of your ISP assigned default which may be obscure. WAN is inferred from ''config dhcp'' sections with ''option ignore 1'' set, so they do not need to be named //WAN// \\ :!: ''add_wan_fqdn'' on Trunk but not 17.01.0 | | |
| | ''addnhosts'' | list of file paths | //(none)// | ''-H'' | Additional host files to read for serving DNS responses | | |
| | ''authoritative'' | boolean | ''1'' | ''-K'' | Force //dnsmasq// into authoritative mode. This speeds up DHCP leasing. Used if this is the only server on the network | | |
| | ''bogusnxdomain'' | list of IP addresses | //(none)// | ''-B'' | IP addresses to convert into NXDOMAIN responses (to counteract "helpful" upstream DNS servers that never return NXDOMAIN). | | |
| | ''boguspriv'' | boolean | ''0'' | ''-b'' | Reject reverse lookups to private IP ranges where no corresponding entry exists in ''/etc/hosts'' | | |
| | ''cachelocal'' | boolean | ''1'' | | When set to ''0'', use each network interface's ''dns'' address in the local ''/etc/resolv.conf''. Normally, only the loopback address is used, and all queries go through //dnsmasq//. | | |
| | ''cachesize'' | integer | ''150'' | ''-c'' | Size of //dnsmasq// query cache. | | |
| | ''dbus'' | boolean | ''0'' | ''-1'' | Enable DBus messaging for //dnsmasq//.\\ :!: Standard builds of //dnsmasq// on OpenWrt do not include DBus support. | | |
| | ''dhcp_boot'' | string | //(none)// | ''-''''-dhcp-boot'' | Specifies BOOTP options, in most cases just the file name. You can also use: "''file name'', ''tftp server name'', ''tftp ip address''"| | |
| | ''dhcphostsfile'' | file path | //(none)// | ''-''''-dhcp-hostsfile'' | Specify an external file with per host DHCP options | | |
| | ''dhcpleasemax'' | integer | ''150'' | ''-X'' | Maximum number of DHCP leases | | |
| | ''dnsforwardmax'' | integer | ''150'' | ''-0'' (zero) | Maximum number of concurrent connections | | |
| | ''domain'' | domain name | //(none)// | ''-s'' | DNS domain handed out to DHCP clients | | |
| | ''domainneeded'' | boolean | ''1'' | ''-D'' | Tells //dnsmasq// never to forward queries for plain names, without dots or domain parts, to upstream nameservers. If the name is not known from /etc/hosts or DHCP then a "not found" answer is returned | | |
| | ''dnssec'' | boolean | ''0'' | ''-''''-dnssec'' | Validate DNS replies and cache DNSSEC data.\\ :!: Requires the //dnsmasq-full// package. | | |
| | ''dnsseccheckunsigned'' | boolean | ''0'' | ''-''''-dnssec-check-unsigned'' | Check the zones of unsigned replies to ensure that unsigned replies are allowed in those zones. This protects against an attacker forging unsigned replies for signed DNS zones, but is slower and requires that the nameservers upstream of //dnsmasq// are DNSSEC-capable.\\ :!: Requires the //dnsmasq-full// package.\\ :!: Caution: If you use this option on a device that doesn't have a hardware clock, dns resolution may break after a reboot of the device due to an incorrect system time. | | |
| | ''ednspacket_max'' | integer | ''1280'' | ''-P'' | Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder | | |
| | ''enable_tftp'' | boolean | ''0'' | ''-''''-enable-tftp'' | Enable the builtin TFTP server | | |
| | ''expandhosts'' | boolean | ''1'' | ''-E'' | Add the local domain part to names found in ''/etc/hosts'' | | |
| | ''filterwin2k'' | boolean | ''0'' | ''-f'' | Do not forward requests that cannot be answered by public name servers | | |
| | ''fqdn'' | boolean | ''0'' | ''-''''-dhcp-fqdn'' | Do not resolve unqualifed local hostnames. Needs ''domain'' to be set. | | |
| | ''interface'' | list of interface names | //(all interfaces)// | ''-i'' | List of interfaces to listen on. If unspecified, //dnsmasq// will listen to all interfaces except those listed in ''notinterface''. Note that //dnsmasq// listens on loopback by default. | | |
| | ''leasefile'' | file path | //(none)// | ''-l'' (ell) | Store DHCP leases in this file | | |
| | ''local'' | string | //(none)// | ''-S'' | Look up DNS entries for this domain from ''/etc/hosts''. This follows the same syntax as ''server'' entries, see the man page. | | |
| | ''localise_queries'' | boolean | ''0'' | ''-y'' | Choose IP address to match the incoming interface if multiple addresses are assigned to a host name in ''/etc/hosts''. :!: Note well the spelling of this option. | | |
| | ''localservice'' | boolean | ''1'' | ''-''''-local-service'' | Accept DNS queries only from hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server. | | |
| | ''logqueries'' | boolean | ''0'' | ''-q'' | Log the results of DNS queries, dump cache on SIGUSR1 | | |
| | ''nodaemon'' | boolean | ''0'' | ''-d'' | Don't daemonize the //dnsmasq// process | | |
| | ''nohosts'' | boolean | ''0'' | ''-h'' | Don't read DNS names from ''/etc/hosts'' | | |
| | ''nonegcache'' | boolean | ''0'' | ''-N'' | Disable caching of negative "no such domain" responses | | |
| | ''noresolv'' | boolean | ''0'' | ''-R'' | Don't read upstream servers from ''/etc/resolv.conf'' | | |
| | ''notinterface'' | list of interface names | //(none)// | ''-I'' (eye) | Interfaces //dnsmasq// should not listen on. | | |
| | ''nonwildcard'' | boolean | ''0'' | ''-z'' | Bind only configured interface addresses, instead of the wildcard address. | | |
| | ''port'' | port number | ''53'' | ''-p'' | Listening port for DNS queries, disables DNS server functionality if set to ''0'' | | |
| | ''queryport'' | integer | //(none)// | ''-Q'' | Use a fixed port for outbound DNS queries | | |
| | ''readethers'' | boolean | ''0'' | ''-Z'' | Read static lease entries from ''/etc/ethers'', re-read on SIGHUP | | |
| | ''rebind_protection'' | boolean | ''1'' | ''-''''-stop-dns-rebind'' | Enables DNS rebind attack protection by discarding upstream RFC1918 responses | | |
| | ''rebind_localhost'' | boolean | ''0'' | ''-''''-rebind-localhost-ok'' | Allows upstream 127.0.0.0/8 responses, required for DNS based blacklist services, only takes effect if rebind protection is enabled | | |
| | ''rebind_domain'' | list of domain names | //(none)// | ''-''''-rebind-domain-ok'' | List of domains to allow RFC1918 responses for, only takes effect if rebind protection is enabled | | |
| | ''resolvfile'' | file path | ''/etc/resolv.conf'' | ''-r'' | Specifies an alternative resolv file | | |
| | ''server'' | list of strings | //(none)// | ''-S'' | List of DNS servers to forward requests to. See the //dnsmasq// man page for syntax details. | | |
| | ''strictorder'' | boolean | ''0'' | ''-o'' | Obey order of DNS servers in ''/etc/resolv.conf'' | | |
| | ''tftp_root'' | directory path | //(none)// | ''-''''-tftp-root'' | Specifies the TFTP root directory | | |
| |
| |
| ===== Using plain dnsmasq.conf ===== | |
| |
| It is possible to mix the traditional ''/etc/dnsmasq.conf'' configuration file with the options found in ''/etc/config/dhcp''. | |
| |
| The ''dnsmasq.conf'' file does not exist by default but will be processed by //dnsmasq// on startup if it is present. | |
| * **NOTE:** Options in ''/etc/config/dhcp'' take precendence over ''dnsmasq.conf'' since they are translated to command line arguments. | |
| |
| You can have dnsmasq execute a script on every action: ''dhcp-script = /sbin/action.sh'' | |
| |
| |
| ===== Examples ===== | |
| ==== Custom Domain ==== | |
| Define a custom domain name and the corresponding PTR record - assigns the IP address ''192.168.1.140'' to the domain name ''typhoon'' and construct an appropriate reverse record ''140.1.168.192.in-addr.arpa''. It works like an entry in ''/etc/hosts'' but more flexible | |
| and integrated. | |
| |
| :!: Note that this currently only works for IPv4 addresses and that this functionality is not present in release prior to 8.09.2 . | |
| |
| :!: Note that reverse records are not properly generated at present. (Barrier Breaker 14.07-RC2) | |
| |
| <code> | |
| config 'domain' | |
| option name 'typhoon' | |
| option ip 192.168.1.140 | |
| </code> | |
| |
| another example: redirect www.facebook.com | |
| |
| <code> | |
| # www.facebook.com resolves to 1.2.3.4 | |
| | |
| config 'domain' | |
| option name 'www.facebook.com' | |
| option ip 1.2.3.4 | |
| </code> | |
| |
| ==== SRV RR for SIP ==== | |
| To define an SRV record for SIP over UDP, with the default port of 5060 on the host pbx.mydomain.com, with a class of 0 and a weight of 10 one would use: | |
| |
| <code> | |
| config 'srvhost' | |
| option srv '_sip._udp.mydomain.com' | |
| option target 'pbx.mydomain.com' | |
| option port 5060 | |
| option class 0 | |
| option weight 10 | |
| </code> | |
| |
| ==== CNAME RR ==== | |
| A Canonical Name record specifes that a domain name is an alias for another domain, the "canonical" domain. To specify that the web server also doubles as the FTP server, one might use: | |
| |
| <code> | |
| config 'cname' | |
| option cname 'ftp.example.com' | |
| option target 'www.example.com' | |
| </code> | |
| |
| Note that it is necessary to use fully qualified domain names. | |
| |
| |
| ==== Enabling DNS without enabling DHCP ==== | |
| dnsmasq can be used to provide clients with a DNS server, but not with DHCP (for example, if DHCP is already supplied by a separate server). | |
| |
| - dnsmasq must be turned on for the internal interface: | |
| - **Network -> Interfaces:** Click desired internal interface to select it | |
| - **DHCP Server:** Click //Setup DHCP Server//, which enables both DHCP and DNS | |
| - DHCP portion of dnsmasq needs to be turned off. | |
| - **Network -> Interfaces:** Click desired internal interface to select it | |
| - **DHCP Server:** Enable option //Ignore interface// | |
| - Save & Apply | |
| |
| This change will turn off just DHCP but leave DNS services available on the specified interface. | |
| |
| ==== Several DNS servers ==== | |
| <code> | |
| # NOTE: | |
| # Some options should be absent, or set to 0, to allow | |
| # forwarding towards private networks ('boguspriv') | |
| # See: http://en.wikipedia.org/wiki/Private_network | |
| |
| config dnsmasq | |
| option local '/lan/' | |
| option domain 'lan' | |
| option leasefile '/tmp/dhcp.leases' | |
| option resolvfile '/tmp/resolv.conf.auto' | |
| list server '/subdomain.example.com/192.0.2.1' | |
| list server '/example.com/208.67.222.222' | |
| option domainneeded 1 | |
| option localise_queries 1 | |
| option expandhosts 1 | |
| option authoritative 1 | |
| option readethers 1 | |
| option rebind_protection 0 | |
| </code> | |
| |
| |
| ==== Conditional DNS Forwarding for Windows Active Directory Domains / DNS Dependent Directory Based Authentication Services ==== | |
| - Install dnsmasq using your local package manager | |
| - Edit **/etc/dnsmasq.conf** | |
| - Tells dnsmasq to forward anything with the domain of remote.local to DNS server 10.25.11.2 //(example)// | |
| * ''server = /remote.local/10.25.11.2'' | |
| - Listen only to requests coming from the local machine | |
| * ''listen-address = 127.0.0.1'' | |
| - Do not cache anything | |
| * ''cache-size = 0'' | |
| - Edit **/etc/resolv.conf** | |
| - Local LAN Domain | |
| * ''hostname.lan'' | |
| - local dnsmasq server | |
| * ''nameserver 127.0.0.1'' | |
| - Your main dns server //(dnsmasq will forward all requests to this example server)// | |
| * ''nameserver 10.20.1.1'' | |
| - Start dnsmasq | |
| - Test: Ping a local server and remote server using the FQDN | |
| * All DNS requests will be forwarded to 10.20.1.1, except any matching *.remote.local. server.remote.local will be forwarded to 10.25.11.2 | |
| * See: [[http://pyther.net/2010/12/dns-conditional-forwarding-dnsmasq/|DNS Conditional Forwarding]] | |
| |
| <code> | |
| # Define Domain and Domain Controller IPs via 'list server' | |
| |
| config dnsmasq | |
| option domain 'example.local' | |
| option leasefile '/tmp/dhcp.leases' | |
| option resolvfile '/etc/resolv.conf' | |
| option local '/example.local/192.168.1.X' | |
| list server '/0.openwrt.pool.ntp.org/8.8.8.8' | |
| list server '/1.openwrt.pool.ntp.org/8.8.8.8' | |
| list server '/2.openwrt.pool.ntp.org/8.8.8.8' | |
| list server '/3.openwrt.pool.ntp.org/8.8.8.8' | |
| option localise_queries 1 | |
| option rebind_protection 0 | |
| option authoritative 1 | |
| option localservice 1 | |
| option dnssec 0 | |
| option cachesize 0 | |
| option readethers 1 | |
| option logqueries 1 | |
| option fliterwin2k 1 | |
| option boguspriv 1 | |
| |
| config dhcp 'lan' | |
| option interface 'lan' | |
| option start 100 | |
| option limit 150 | |
| option leasetime '12h' | |
| </code> | |
| |
| Now on to the finalization of the /etc/resolv.conf | |
| Traditionally /etc/resolv.conf is populated via symlink based on interface settings which get inserted via script into /tmp/resolv.conf. We're going to disable this symlink because without doing so it would override our static settings. | |
| |
| You'll want to remove /etc/resolv.conf | |
| That will remove the resolv.conf symlink. Then we will add the ip address of the secondary DNS and external resolving address inside the /etc/resolv.conf file finally establishing conditional forwarding, something that should be specified for easy configuration via the GUI. | |
| |
| <code> | |
| rm /etc/resolv.conf | |
| |
| echo "domain example.local" >> /etc/resolv.conf | |
| echo "nameserver 127.0.0.1" >> /etc/resolv.conf | |
| echo "nameserver 208.67.220.220" >> /etc/resolv.conf | |
| </code> | |
| |
| <code> | |
| # Define Domain & Public DNS below. | |
| |
| domain example.local | |
| nameserver 127.0.0.1 | |
| nameserver 208.67.220.220 | |
| </code> | |