dnsmasq: Direct import of version 2.51
Signed-off-by: San Mehat <san@google.com>
diff --git a/FAQ b/FAQ
new file mode 100755
index 0000000..b51c31e
--- /dev/null
+++ b/FAQ
@@ -0,0 +1,471 @@
+Q: Why does dnsmasq open UDP ports >1024 as well as port 53.
+ Is this a security problem/trojan/backdoor?
+
+A: The high ports that dnsmasq opens are for replies from the upstream
+ nameserver(s). Queries from dnsmasq to upstream nameservers are sent
+ from these ports and replies received to them. The reason for doing this is
+ that most firewall setups block incoming packets _to_ port 53, in order
+ to stop DNS queries from the outside world. If dnsmasq sent its queries
+ from port 53 the replies would be _to_ port 53 and get blocked.
+
+ This is not a security hole since dnsmasq will only accept replies to that
+ port: queries are dropped. The replies must be to oustanding queries
+ which dnsmasq has forwarded, otherwise they are dropped too.
+
+ Addendum: dnsmasq now has the option "query-port" (-Q), which allows
+ you to specify the UDP port to be used for this purpose. If not
+ specified, the operating system will select an available port number
+ just as it did before.
+
+ Second addendum: following the discovery of a security flaw in the
+ DNS protocol, dnsmasq from version 2.43 has changed behavior. It
+ now uses a new, randomly selected, port for each query. The old
+ default behaviour (use one port allocated by the OS) is available by
+ setting --query-port=0, and setting the query port to a positive
+ value is still works. You should think hard and know what you are
+ doing before using either of these options.
+
+Q: Why doesn't dnsmasq support DNS queries over TCP? Don't the RFC's specify
+ that?
+
+A: Update: from version 2.10, it does. There are a few limitations:
+ data obtained via TCP is not cached, and source-address
+ or query-port specifications are ignored for TCP.
+
+Q: When I send SIGUSR1 to dump the contents of the cache, some entries have
+ no IP address and are for names like mymachine.mydomain.com.mydomain.com.
+ What are these?
+
+A: They are negative entries: that's what the N flag means. Dnsmasq asked
+ an upstream nameserver to resolve that address and it replied "doesn't
+ exist, and won't exist for <n> hours" so dnsmasq saved that information so
+ that if _it_ gets asked the same question it can answer directly without
+ having to go back to the upstream server again. The strange repeated domains
+ result from the way resolvers search short names. See "man resolv.conf" for
+ details.
+
+
+Q: Will dnsmasq compile/run on non-Linux systems?
+
+A: Yes, there is explicit support for *BSD and MacOS X and Solaris.
+ There are start-up scripts for MacOS X Tiger and Panther
+ in /contrib. Dnsmasq will link with uclibc to provide small
+ binaries suitable for use in embedded systems such as
+ routers. (There's special code to support machines with flash
+ filesystems and no battery-backed RTC.)
+ If you encounter make errors with *BSD, try installing gmake from
+ ports and building dnsmasq with "make MAKE=gmake"
+ For other systems, try altering the settings in config.h.
+
+Q: My company's nameserver knows about some names which aren't in the
+ public DNS. Even though I put it first in /etc/resolv.conf, it
+ dosen't work: dnsmasq seems not to use the nameservers in the order
+ given. What am I doing wrong?
+
+A: By default, dnsmasq treats all the nameservers it knows about as
+ equal: it picks the one to use using an algorithm designed to avoid
+ nameservers which aren't responding. To make dnsmasq use the
+ servers in order, give it the -o flag. If you want some queries
+ sent to a special server, think about using the -S flag to give the
+ IP address of that server, and telling dnsmasq exactly which
+ domains to use the server for.
+
+Q: OK, I've got queries to a private nameserver working, now how about
+ reverse queries for a range of IP addresses?
+
+A: Use the standard DNS convention of <reversed address>.in-addr.arpa.
+ For instance to send reverse queries on the range 192.168.0.0 to
+ 192.168.0.255 to a nameserver at 10.0.0.1 do
+ server=/0.168.192.in-addr.arpa/10.0.0.1
+ Note that the "bogus-priv" option take priority over this option,
+ so the above will not work when the bogus-priv option is set.
+
+Q: Dnsmasq fails to start with an error like this: "dnsmasq: bind
+ failed: Cannot assign requested address". What's the problem?
+
+A: This has been seen when a system is bringing up a PPP interface at
+ boot time: by the time dnsmasq start the interface has been
+ created, but not brought up and assigned an address. The easiest
+ solution is to use --interface flags to specify which interfaces
+ dnsmasq should listen on. Since you are unlikely to want dnsmasq to
+ listen on a PPP interface and offer DNS service to the world, the
+ problem is solved.
+
+Q: I'm running on BSD and dnsmasq won't accept long options on the
+ command line.
+
+A: Dnsmasq when built on some BSD systems doesn't use GNU getopt by
+ default. You can either just use the single-letter options or
+ change config.h and the Makefile to use getopt-long. Note that
+ options in /etc/dnsmasq.conf must always be the long form,
+ on all platforms.
+
+Q: Names on the internet are working fine, but looking up local names
+ from /etc/hosts or DHCP doesn't seem to work.
+
+A: Resolver code sometime does strange things when given names without
+ any dots in. Win2k and WinXP may not use the DNS at all and just
+ try and look up the name using WINS. On unix look at "options ndots:"
+ in "man resolv.conf" for details on this topic. Testing lookups
+ using "nslookup" or "dig" will work, but then attempting to run
+ "ping" will get a lookup failure, appending a dot to the end of the
+ hostname will fix things. (ie "ping myhost" fails, but "ping
+ myhost." works. The solution is to make sure that all your hosts
+ have a domain set ("domain" in resolv.conf, or set a domain in
+ your DHCP server, see below fr Windows XP and Mac OS X).
+ Any domain will do, but "localnet" is traditional. Now when you
+ resolve "myhost" the resolver will attempt to look up
+ "myhost.localnet" so you need to have dnsmasq reply to that name.
+ The way to do that is to include the domain in each name on
+ /etc/hosts and/or to use the --expand-hosts and --domain options.
+
+Q: How do I set the DNS domain in Windows XP or MacOS X (ref: previous
+ question)?
+
+A: for XP, Control Panel > Network Connections > { Connection to gateway /
+ DNS } > Properties > { Highlight TCP/IP } > Properties > Advanced >
+ DNS Tab > DNS suffix for this connection:
+
+A: for OS X, System Preferences > Network > {Connection to gateway / DNS } >
+ Search domains:
+
+Q: Can I get dnsmasq to save the contents of its cache to disk when
+ I shut my machine down and re-load when it starts again?
+
+A: No, that facility is not provided. Very few names in the DNS have
+ their time-to-live set for longer than a few hours so most of the
+ cache entries would have expired after a shutdown. For longer-lived
+ names it's much cheaper to just reload them from the upstream
+ server. Note that dnsmasq is not shut down between PPP sessions so
+ go off-line and then on-line again will not lose the contents of
+ the cache.
+
+Q: Who are Verisign, what do they have to do with the bogus-nxdomain
+ option in dnsmasq and why should I wory about it?
+
+A: [note: this was written in September 2003, things may well change.]
+ Versign run the .com and .net top-level-domains. They have just
+ changed the configuration of their servers so that unknown .com and
+ .net domains, instead of returning an error code NXDOMAIN, (no such
+ domain) return the address of a host at Versign which runs a web
+ server showing a search page. Most right-thinking people regard
+ this new behaviour as broken :-). You can test to see if you are
+ suffering Versign brokeness by run a command like
+
+ host jlsdajkdalld.com
+
+ If you get "jlsdajkdalld.com" does not exist, then all is fine, if
+ host returns an IP address, then the DNS is broken. (Try a few
+ different unlikely domains, just in case you picked a wierd one
+ which really _is_ registered.)
+
+ Assuming that your DNS is broken, and you want to fix it, simply
+ note the IP address being returned and pass it to dnsmasq using the
+ --bogus-nxdomain flag. Dnsmasq will check for results returning
+ that address and substitute an NXDOMAIN instead.
+
+ As of writing, the IP address in question for the .com and .net
+ domains is is 64.94.110.11. Various other, less prominent,
+ registries pull the same stunt; there is a list of them all, and
+ the addresses to block, at http://winware.org/bogus-domains.txt
+
+Q: This new DHCP server is well and good, but it doesn't work for me.
+ What's the problem?
+
+A: There are a couple of configuration gotchas which have been
+ encountered by people moving from the ISC dhcpd to the dnsmasq
+ integrated DHCP daemon. Both are related to differences in
+ in the way the two daemons bypass the IP stack to do "ground up"
+ IP configuration and can lead to the dnsmasq daemon failing
+ whilst the ISC one works.
+
+ The first thing to check is the broadcast address set for the
+ ethernet interface. This is normally the adddress on the connected
+ network with all ones in the host part. For instance if the
+ address of the ethernet interface is 192.168.55.7 and the netmask
+ is 255.255.255.0 then the broadcast address should be
+ 192.168.55.255. Having a broadcast address which is not on the
+ network to which the interface is connected kills things stone
+ dead.
+
+ The second potential problem relates to firewall rules: since the ISC
+ daemon in some configurations bypasses the kernel firewall rules
+ entirely, the ability to run the ISC daemon does not indicate
+ that the current configuration is OK for the dnsmasq daemon.
+ For the dnsmasq daemon to operate it's vital that UDP packets to
+ and from ports 67 and 68 and broadcast packets with source
+ address 0.0.0.0 and destination address 255.255.255.255 are not
+ dropped by iptables/ipchains.
+
+Q: I'm running Debian, and my machines get an address fine with DHCP,
+ but their names are not appearing in the DNS.
+
+A: By default, none of the DHCP clients send the host-name when asking
+ for a lease. For most of the clients, you can set the host-name to
+ send with the "hostname" keyword in /etc/network/interfaces. (See
+ "man interfaces" for details.) That doesn't work for dhclient, were
+ you have to add something like "send host-name daisy" to
+ /etc/dhclient.conf [Update: the lastest dhcpcd packages _do_ send
+ the hostname by default.
+
+Q: I'm network booting my machines, and trying to give them static
+ DHCP-assigned addresses. The machine gets its correct address
+ whilst booting, but then the OS starts and it seems to get
+ allocated a different address.
+
+A: What is happening is this: The boot process sends a DHCP
+ request and gets allocated the static address corresponding to its
+ MAC address. The boot loader does not send a client-id. Then the OS
+ starts and repeats the DHCP process, but it it does send a
+ client-id. Dnsmasq cannot assume that the two requests are from the
+ same machine (since the client ID's don't match) and even though
+ the MAC address has a static allocation, that address is still in
+ use by the first incarnation of the machine (the one from the boot,
+ without a client ID.) dnsmasq therefore has to give the machine a
+ dynamic address from its pool. There are three ways to solve this:
+ (1) persuade your DHCP client not to send a client ID, or (2) set up
+ the static assignment to the client ID, not the MAC address. The
+ default client-id will be 01:<MAC address>, so change the dhcp-host
+ line from "dhcp-host=11:22:33:44:55:66,1.2.3.4" to
+ "dhcp-host=id:01:11:22:33:44:55:66,1.2.3.4" or (3) tell dnsmasq to
+ ignore client IDs for a particular MAC address, like this:
+ dhcp-host=11:22:33:44:55:66,id:*
+
+Q: What network types are supported by the DHCP server?
+
+A: Ethernet (and 802.11 wireless) are supported on all platforms. On
+ Linux all network types (including FireWire) are supported.
+
+Q: What is this strange "bind-interface" option?
+
+A: The DNS spec says that the reply to a DNS query must come from the
+ same address it was sent to. The traditional way to write an UDP
+ server to do this is to find all of the addresses belonging to the
+ machine (ie all the interfaces on the machine) and then create a
+ socket for each interface which is bound to the address of the
+ interface. Then when a packet is sent to address A, it is received
+ on the socket bound to address A and when the reply is also sent
+ via that socket, the source address is set to A by the kernel and
+ everything works. This is the how dnsmasq works when
+ "bind-interfaces" is set, with the obvious extension that is misses
+ out creating sockets for some interfaces depending on the
+ --interface, --address and --except-interface flags. The
+ disadvantage of this approach is that it breaks if interfaces don't
+ exist or are not configured when the daemon starts and does the
+ socket creation step. In a hotplug-aware world this is a real
+ problem.
+
+ The alternative approach is to have only one socket, which is bound
+ to the correct port and the wildcard IP address (0.0.0.0). That
+ socket will receive _all_ packets sent to port 53, no matter what
+ destination address they have. This solves the problem of
+ interfaces which are created or reconfigured after daemon
+ start-up. To make this work is more complicated because of the
+ "reply source address" problem. When a UDP packet is sent by a
+ socket bound to 0.0.0.0 its source address will be set to the
+ address of one of the machine's interfaces, but which one is not
+ determined and can vary depending on the OS being run. To get round
+ this it is neccessary to use a scary advanced API to determine the
+ address to which a query was sent, and force that to be the source
+ address in the reply. For IPv4 this stuff in non-portable and quite
+ often not even available (It's different between FreeBSD 5.x and
+ Linux, for instance, and FreeBSD 4.x, Linux 2.0.x and OpenBSD don't
+ have it at all.) Hence "bind-interfaces" has to always be available
+ as a fall back. For IPv6 the API is standard and universally
+ available.
+
+ It could be argued that if the --interface or --address flags are
+ used then binding interfaces is more appropriate, but using
+ wildcard binding means that dnsmasq will quite happily start up
+ after being told to use interfaces which don't exist, but which are
+ created later. Wildcard binding breaks the scenario when dnsmasq is
+ listening on one interface and another server (most probably BIND)
+ is listening on another. It's not possible for BIND to bind to an
+ (address,port) pair when dnsmasq has bound (wildcard,port), hence
+ the ability to explicitly turn off wildcard binding.
+
+Q: Why doesn't Kerberos work/why can't I get sensible answers to
+ queries for SRV records.
+
+A: Probably because you have the "filterwin2k" option set. Note that
+ it was on by default in example configuration files included in
+ versions before 2.12, so you might have it set on without
+ realising.
+
+Q: Can I get email notification when a new version of dnsmasq is
+ released?
+
+A: Yes, new releases of dnsmasq are always announced through
+ freshmeat.net, and they allow you to subcribe to email alerts when
+ new versions of particular projects are released. New releases are
+ also announced in the dnsmasq-discuss mailing list, subscribe at
+ http://lists.thekelleys.org.uk/mailman/listinfo/dnsmasq-discuss
+
+Q: What does the dhcp-authoritative option do?
+
+A: See http://www.isc.org/index.pl?/sw/dhcp/authoritative.php - that's
+ for the ISC daemon, but the same applies to dnsmasq.
+
+Q: Why does my Gentoo box pause for a minute before getting a new
+ lease?
+
+A: Because when a Gentoo box shuts down, it releases its lease with
+ the server but remembers it on the client; this seems to be a
+ Gentoo-specific patch to dhcpcd. On restart it tries to renew
+ a lease which is long gone, as far as dnsmasq is concerned, and
+ dnsmasq ignores it until is times out and restarts the process.
+ To fix this, set the dhcp-authoritative flag in dnsmasq.
+
+Q: My laptop has two network interfaces, a wired one and a wireless
+ one. I never use both interfaces at the same time, and I'd like the
+ same IP and configuration to be used irrespective of which
+ interface is in use. How can I do that?
+
+A: By default, the identity of a machine is determined by using the
+ MAC address, which is associated with interface hardware. Once an
+ IP is bound to the MAC address of one interface, it cannot be
+ associated with another MAC address until after the DHCP lease
+ expires. The solution to this is to use a client-id as the machine
+ identity rather than the MAC address. If you arrange for the same
+ client-id to sent when either interface is in use, the DHCP server
+ will recognise the same machine, and use the same address. The
+ method for setting the client-id varies with DHCP client software,
+ dhcpcd uses the "-I" flag. Windows uses a registry setting,
+ see http://www.jsiinc.com/SUBF/TIP2800/rh2845.htm
+Addendum:
+ From version 2.46, dnsmasq has a solution to this which doesn't
+ involve setting client-IDs. It's possible to put more than one MAC
+ address in a --dhcp-host configuration. This tells dnsmasq that it
+ should use the specified IP for any of the specified MAC addresses,
+ and furthermore it gives dnsmasq permission to sumarily abandon a
+ lease to one of the MAC addresses if another one comes along. Note
+ that this will work fine only as longer as only one interface is
+ up at any time. There is no way for dnsmasq to enforce this
+ constraint: if you configure multiple MAC addresses and violate
+ this rule, bad things will happen.
+
+Q: Can dnsmasq do DHCP on IP-alias interfaces?
+
+A: Yes, from version-2.21. The support is only available running under
+ Linux, on a kernel which provides the RT-netlink facility. All 2.4
+ and 2.6 kernels provide RT-netlink and it's an option in 2.2
+ kernels.
+
+ If a physical interface has more than one IP address or aliases
+ with extra IP addresses, then any dhcp-ranges corresponding to
+ these addresses can be used for address allocation. So if an
+ interface has addresses 192.168.1.0/24 and 192.68.2.0/24 and there
+ are DHCP ranges 192.168.1.100-192.168.1.200 and
+ 192.168.2.100-192.168.2.200 then both ranges would be used for host
+ connected to the physical interface. A more typical use might be to
+ have one of the address-ranges as static-only, and have known
+ hosts allocated addresses on that subnet using dhcp-host options,
+ while anonymous hosts go on the other.
+
+
+Q: Dnsmasq sometimes logs "nameserver xxx.xxx.xxx.xxx refused
+ to do a recursive query" and DNS stops working. What's going on?
+
+A: Probably the nameserver is an authoritative nameserver for a
+ particular domain, but is not configured to answer general DNS
+ queries for an arbitrary domain. It is not suitable for use by
+ dnsmasq as an upstream server and should be removed from the
+ configuration. Note that if you have more than one upstream
+ nameserver configured dnsmasq will load-balance across them and
+ it may be some time before dnsmasq gets around to using a
+ particular nameserver. This means that a particular configuration
+ may work for sometime with a broken upstream nameserver
+ configuration.
+
+
+Q: Does the dnsmasq DHCP server probe addresses before allocating
+ them, as recommended in RFC2131?
+
+A: Yes, dynmaically allocated IP addresses are checked by sending an
+ ICMP echo request (ping). If a reply is received, then dnsmasq
+ assumes that the address is in use, and attempts to allocate an
+ different address. The wait for a reply is between two and three
+ seconds. Because the DHCP server is not re-entrant, it cannot serve
+ other DHCP requests during this time. To avoid dropping requests,
+ the address probe may be skipped when dnsmasq is under heavy load.
+
+
+Q: I'm using dnsmasq on a machine with the Firestarter firewall, and
+ DHCP doesn't work. What's the problem?
+
+A: This a variant on the iptables problem. Explicit details on how to
+ proceed can be found at
+ http://lists.thekelleys.org.uk/pipermail/dnsmasq-discuss/2005q3/000431.html
+
+
+Q: I'm using dnsmasq on a machine with the shorewall firewall, and
+ DHCP doesn't work. What's the problem?
+
+A: This a variant on the iptables problem. Explicit details on how to
+ proceed can be found at
+ http://lists.thekelleys.org.uk/pipermail/dnsmasq-discuss/2007q4/001764.html
+
+
+Q: Dnsmasq fails to start up with a message about capabilities.
+ Why did that happen and what can do to fix it?
+
+A: Change your kernel configuration: either deselect CONFIG_SECURITY
+ _or_ select CONFIG_SECURITY_CAPABILITIES. Alternatively, you can
+ remove the need to set capabilities by running dnsmasq as root.
+
+Q: Where can I get .rpms Suitable for Suse?
+
+A: Dnsmasq is in Suse itself, and the latest releases are also
+ available at ftp://ftp.suse.com/pub/people/ug/
+
+
+Q: Can I run dnsmasq in a Linux vserver?
+
+A: Yes, as a DNS server, dnsmasq will just work in a vserver.
+ To use dnsmasq's DHCP function you need to give the vserver
+ extra system capabilities. Please note that doing so will lesser
+ the overall security of your system. The capabilities
+ required are NET_ADMIN and NET_RAW. NET_ADMIN is essential, NET_RAW
+ is required to do an ICMP "ping" check on newly allocated
+ addresses. If you don't need this check, you can disable it with
+ --no-ping and omit the NET_RAW capability.
+ Adding the capabilities is done by adding them, one per line, to
+ either /etc/vservers/<vservername>/ccapabilities for a 2.4 kernel or
+ /etc/vservers/<vservername>/bcapabilities for a 2.6 kernel (please
+ refer to the vserver documentation for more information).
+
+
+Q: What's the problem with syslog and dnsmasq?
+
+A: In almost all cases: none. If you have the normal arrangement with
+ local daemons logging to a local syslog, which then writes to disk,
+ then there's never a problem. If you use network logging, then
+ there's a potential problem with deadlock: the syslog daemon will
+ do DNS lookups so that it can log the source of log messages,
+ these lookups will (depending on exact configuration) go through
+ dnsmasq, which also sends log messages. With bad timing, you can
+ arrive at a situation where syslog is waiting for dnsmasq, and
+ dnsmasq is waiting for syslog; they will both wait forever. This
+ problem is fixed from dnsmasq-2.39, which introduces asynchronous
+ logging: dnsmasq no longer waits for syslog and the deadlock is
+ broken. There is a remaining problem in 2.39, where "log-queries"
+ is in use. In this case most DNS queries generate two log lines, if
+ these go to a syslog which is doing a DNS lookup for each log line,
+ then those queries will in turn generate two more log lines, and a
+ chain reaction runaway will occur. To avoid this, use syslog-ng
+ and turn on syslog-ng's dns-cache function.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+