Update FAQ to cover --bind-dynamic.

CHANGELOG

@@ -27,7 +27,16 @@ version 2.63
 	    Fix regression in 2.61 which broke caching of CNAME
 	    chains. Thanks to Atul Gupta for the bug report.
 
-	    Allow the target of a --cname flag to be anothe --cname.
+	    Allow the target of a --cname flag to be another --cname.
+
+            Teach DHCPv6 about the RFC 4242 information-refresh-time
+	    option, and add parsing if the minutes, hours and days
+	    format for options. Thanks to Francois-Xavier Le Bail for
+	    the suggestion.
+
+	    Allow "w" (for week) as multiplier in lease times, as well
+	    as seconds, minutes, hours and days.  Álvaro Gámez Machado 
+	    spotted the ommission.
 
 
 version 2.62
@@ -54,7 +63,6 @@ version 2.62
 	    two addresses in the same network. Thanks to Jim Bos for
 	    his help nailing this.
 
-
 version 2.61
 	    Re-write interface discovery code on *BSD to use
 	    getifaddrs. This is more portable, more straightforward,

FAQ

@@ -236,53 +236,70 @@ 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?
+Q: What are these strange "bind-interface" and "bind-dynamic" options?
 
-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.
+A: Dnsmasq from v2.63 can operate in one of three different "networking
+   modes". This is unfortunate as it requires users configuring dnsmasq
+   to take into account some rather bizzare contraints and select the
+   mode which best fits the requirements of a particular installation.
+   The origin of these are deficiencies in the Unix networking
+   model and APIs and each mode has different advantages and
+   problems. Just to add to the confusion, not all modes are available on
+   all platforms (due the to lack of supporting network APIs).To further
+   add to the confusion, the rules for the DHCP subsystem on dnsmasq are
+   different to the rules for the DNS and TFTP subsystems.
 
-   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.
+   The three modes are "wildcard", "bind-interfaces" and "bind-dynamic".
 
-   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.
+   In "wildcard" mode, dnsmasq binds the wildcard IP address (0.0.0.0 or
+   ::). This allows it to recieve all the packets sent to the server on
+   the relevant port. Access control (--interface, --except-interface,
+   --listen-address, etc) is implemented by dnsmasq: it queries the
+   kernel to determine the interface on which a packet was recieved and
+   the address to which it was sent, and applies the configured
+   rules. Wildcard mode is the default if neither of the other modes are
+   specified. 
+
+   In "bind-interfaces" mode, dnsmasq runs through all the network
+   interfaces available when it starts, finds the set of IP addresses on
+   those interfaces, filters that set using the access control
+   configuration, and then binds the set of IP addresses. Only packets
+   sent to the allowed addresses are delivered by the kernel to dnsmasq.
+
+   In "bind-dynamic" mode, access control filtering is done both by
+   binding individual IP addresses, as for bind-interfaces, and by
+   inspecting individual packets on arrival as for wildcard mode. In
+   addition, dnsmasq notices when new interfaces appear or new addresses
+   appear on existing interfaces, and the resulting IP addresses are
+   bound automatically without having to restart dnsmasq.
+
+   The mode chosen has four different effects: co-existence with other
+   servers, semantics of --interface access control, effect of new
+   interfaces, and legality of --interface specifications for
+   non-existent inferfaces. We will deal with these in order.
+
+   A dnsmasq instance running in wildcard mode precludes a machine from
+   running a second instance of dnsmasq or any other DNS, TFTP or DHCP
+   server. Attempts to do so will fail with an "address in use" error. 
+   Dnsmasq running in --bind-interfaces or bind-dynamic mode allow other
+   instances of dnsmasq or other servers, as long as no two servers are
+   configured to listen on the same interface address. 
+
+   The semantics of --interface varies subtly between wildcard or
+   bind-dynamic mode and bind-interfaces mode. The situation where this
+   matters is a request which arrives via one interface (A), but with a
+   destination address of a second interface (B) and when dnsmasq is
+   configured to listen only on B. In wildcard or bind-dynamic mode, such
+   a request will be ignored, in bind-interfaces mode, it will be
+   accepted.
+
+   The creation of new network interfaces after dnsmasq starts is ignored
+   by dnsmasq when in --bind-interfaces mode. In wildcard or bind-dynamic
+   mode, such interfaces are handled normally.
+
+   A --interface specification for a non-existent interface is a fatal
+   error at start-up when in --bind-interfaces mode, by just generates a
+   warning in wildcard or bind-dynamic mode.
 
 Q: Why doesn't Kerberos work/why can't I get sensible answers to
    queries for SRV records.

debian/changelog

@@ -1,6 +1,7 @@
 dnsmasq (2.63-1) unstable; urgency=low
 
    * New upstream.
+   * Move /etc/dbus-1/system.d/dnsmasq.conf from dnsmasq to dnsmasq-base.
 
  -- Simon Kelley <simon@thekelleys.org.uk>  Mon, 11 Jun 2012 21:55:35 +0000
 

debian/conffiles

@@ -2,5 +2,4 @@
 /etc/default/dnsmasq
 /etc/dnsmasq.conf
 /etc/resolvconf/update.d/dnsmasq
-/etc/dbus-1/system.d/dnsmasq.conf
 /etc/insserv.conf.d/dnsmasq

debian/control

@@ -23,7 +23,8 @@ Description: Small caching DNS proxy and DHCP/TFTP server
 Package: dnsmasq-base
 Architecture: any
 Depends: ${shlibs:Depends}
-Conflicts: dnsmasq (<<2.41)
+Breaks: dnsmasq (<< 2.62-3)
+Replaces: dnsmasq (<< 2.62-3)
 Description: Small caching DNS proxy and DHCP/TFTP server
  This package contains the dnsmasq executable and documentation, but
  not the infrastructure required to run it as a system daemon. For

debian/rules

@@ -85,7 +85,6 @@ binary-indep:	checkroot
 	        -d debian/daemon/etc/resolvconf/update.d \
 		-d debian/daemon/usr/lib/resolvconf/dpkg-event.d \
 	        -d debian/daemon/etc/default \
-		-d debian/daemon/etc/dbus-1/system.d \
 		-d debian/daemon/lib/systemd/system \
                 -d debian/daemon/etc/insserv.conf.d
 	install -m 644 debian/conffiles debian/daemon/DEBIAN
@@ -96,7 +95,6 @@ binary-indep:	checkroot
 	install -m 644 debian/default debian/daemon/etc/default/dnsmasq
 	install -m 644 dnsmasq.conf.example debian/daemon/etc/dnsmasq.conf
 	install -m 644 debian/readme.dnsmasq.d debian/daemon/etc/dnsmasq.d/README
-	install -m 644 debian/dbus.conf debian/daemon/etc/dbus-1/system.d/dnsmasq.conf
 	install -m 644 debian/systemd.service debian/daemon/lib/systemd/system/dnsmasq.service
 	install -m 644 debian/insserv debian/daemon/etc/insserv.conf.d/dnsmasq
 	ln -s $(package) debian/daemon/usr/share/doc/dnsmasq
@@ -111,6 +109,7 @@ binary-arch:	checkroot
 	rm -rf debian/base
 	install -m 755 \
 		-d debian/base/DEBIAN \
+		-d debian/base/etc/dbus-1/system.d \
 	        -d debian/base/usr/share/doc/$(package) \
 		-d debian/base/usr/share/doc/$(package)/examples \
 	        -d debian/base/var/run \
@@ -129,10 +128,12 @@ ifeq (,$(findstring nodocs,$(DEB_BUILD_OPTIONS)))
 	install -m 644 dbus/DBus-interface debian/base/usr/share/doc/$(package)/.
 	gzip -9 debian/base/usr/share/doc/$(package)/DBus-interface	
 endif
+	install -m 644 debian/dnsmasq-base.conffiles debian/base/DEBIAN/conffiles
 	install -m 644 debian/changelog debian/base/usr/share/doc/$(package)/changelog.Debian
 	gzip -9 debian/base/usr/share/doc/$(package)/changelog.Debian
 	install -m 644 debian/readme debian/base/usr/share/doc/$(package)/README.Debian
 	install -m 644 debian/copyright debian/base/usr/share/doc/$(package)/copyright
+	install -m 644 debian/dbus.conf debian/base/etc/dbus-1/system.d/dnsmasq.conf
 	gzip -9 debian/base/usr/share/man/man8/dnsmasq.8
 	for f in debian/base/usr/share/man/*; do \
 		if [ -f $$f/man8/dnsmasq.8 ]; then \

dnsmasq.conf.example

@@ -326,6 +326,9 @@
 # dnsmasq and another.
 #dhcp-option=option6:dns-server,[::],[1234::88]
 
+# Ask client to poll for option changes every six hours. (RFC4242)
+#dhcp-option=option6:information-refresh-time,6h
+
 # Set the NTP time server address to be the same machine as
 # is running dnsmasq
 #dhcp-option=42,0.0.0.0

src/dhcp-common.c

@@ -487,15 +487,15 @@ static const struct opttab_t {
   { "x-windows-fs", 48, OT_ADDR_LIST },
   { "x-windows-dm", 49, OT_ADDR_LIST },
   { "requested-address", 50, OT_INTERNAL | OT_ADDR_LIST },
-  { "lease-time", 51, OT_INTERNAL | OT_DEC },
+  { "lease-time", 51, OT_INTERNAL | OT_TIME },
   { "option-overload", 52, OT_INTERNAL },
   { "message-type", 53, OT_INTERNAL | OT_DEC },
   { "server-identifier", 54, OT_INTERNAL | OT_ADDR_LIST },
   { "parameter-request", 55, OT_INTERNAL },
   { "message", 56, OT_INTERNAL },
   { "max-message-size", 57, OT_INTERNAL },
-  { "T1", 58, OT_INTERNAL | OT_DEC},
-  { "T2", 59, OT_INTERNAL | OT_DEC},
+  { "T1", 58, OT_INTERNAL | OT_TIME},
+  { "T2", 59, OT_INTERNAL | OT_TIME},
   { "vendor-class", 60, 0 },
   { "client-id", 61, OT_INTERNAL },
   { "nis+-domain", 64, OT_NAME },
@@ -546,6 +546,7 @@ static const struct opttab_t opttab6[] = {
   { "nis-domain", 29,  OT_RFC1035_NAME },
   { "nis+-domain", 30, OT_RFC1035_NAME },
   { "sntp-server", 31,  OT_ADDR_LIST },
+  { "information-refresh-time", 32, OT_TIME },
   { "FQDN", 39, OT_INTERNAL | OT_RFC1035_NAME },
   { "ntp-server", 56,  OT_ADDR_LIST },
   { "bootfile-url", 59, OT_NAME },
@@ -710,14 +711,17 @@ char *option_string(int prot, unsigned int opt, unsigned char *val, int opt_len,
 		  }
 	      }	      
 #endif
-	    else if ((ot[o].size & OT_DEC) && opt_len != 0)
+	    else if ((ot[o].size & (OT_DEC | OT_TIME)) && opt_len != 0)
 	      {
 		unsigned int dec = 0;
 		
 		for (i = 0; i < opt_len; i++)
 		  dec = (dec << 8) | val[i]; 
 
-		sprintf(buf, "%u", dec);
+		if (ot[o].size & OT_TIME)
+		  prettyprint_time(buf, dec);
+		else
+		  sprintf(buf, "%u", dec);
 	      }
 	    else
 	      nodecode = 1;

src/dnsmasq.h

@@ -475,7 +475,7 @@ struct frec {
 #define OT_NAME         0x1000
 #define OT_CSTRING      0x0800
 #define OT_DEC          0x0400 
-
+#define OT_TIME         0x0200
 
 /* actions in the daemon->helper RPC */
 #define ACTION_DEL           1

src/option.c

@@ -764,7 +764,7 @@ static int parse_dhcp_opt(char *errstr, char *arg, int flags)
 	  } 
 	else if (c == '.')	
 	  {
-	    is_addr6 =is_dec = is_hex = 0;
+	    is_addr6 = is_dec = is_hex = 0;
 	    dots++;
 	  }
 	else if (c == '-')
@@ -811,8 +811,40 @@ static int parse_dhcp_opt(char *errstr, char *arg, int flags)
       /* or names */
       else if (opt_len & (OT_NAME | OT_RFC1035_NAME | OT_CSTRING))
 	is_addr6 = is_addr = is_dec = is_hex = 0;
-            
-      if (is_hex && digs > 1)
+      
+      if (found_dig && (opt_len & OT_TIME) && strlen(comma) > 0)
+	{
+	  int val, fac = 1;
+
+	  switch (comma[strlen(comma) - 1])
+	    {
+	    case 'w':
+	    case 'W':
+	      fac *= 7;
+	      /* fall through */
+	    case 'd':
+	    case 'D':
+	      fac *= 24;
+	      /* fall though */
+	    case 'h':
+	    case 'H':
+	      fac *= 60;
+	      /* fall through */
+	    case 'm':
+	    case 'M':
+	      fac *= 60;
+	      /* fall through */
+	    case 's':
+	    case 'S':
+	      comma[strlen(comma) - 1] = 0;
+	    }
+	  
+	  new->len = 4;
+	  new->val = opt_malloc(4);
+	  val = atoi(comma);
+	  *((int *)new->val) = htonl(val * fac);	  
+	}  
+      else if (is_hex && digs > 1)
 	{
 	  new->len = digs;
 	  new->val = opt_malloc(new->len);
@@ -2128,6 +2160,10 @@ static int one_opt(int option, char *arg, char *errstr, char *gen_err, int comma
 		  {
 		    switch (a[leasepos][strlen(a[leasepos]) - 1])
 		      {
+		      case 'w':
+		      case 'W':
+			fac *= 7;
+			/* fall through */
 		      case 'd':
 		      case 'D':
 			fac *= 24;
@@ -2278,6 +2314,10 @@ static int one_opt(int option, char *arg, char *errstr, char *gen_err, int comma
 		  last = *lastp;
 		  switch (last)
 		    {
+		    case 'w':
+		    case 'W':
+		      fac *= 7;
+		      /* fall through */
 		    case 'd':
 		    case 'D':
 		      fac *= 24;