Merged rt41751 (DHCP4o6 docs)

1 files changed, 160 insertions, 52 deletions

diff --git a/doc/DHCPv4-over-DHCPv6 b/doc/DHCPv4-over-DHCPv6
index de232d73..cccc9c91 100644
--- a/doc/DHCPv4-over-DHCPv6
+++ b/doc/DHCPv4-over-DHCPv6
@@ -3,50 +3,47 @@ Short notice about DHCPv4 over DHCPv6 aka RFC 7341
 Note well: this code is still somewhat experimental and any user
 should take care when trying to use it.
 
-First both the DHCPv4 over DHCPv6 client and server come with two
-processes (named "side" below):
- - a DHCPv6 side which performs usual DHCPv6 operations and
-  forwards DHCPv4-query / DHCPv4-response (eventually encapsulated
-  by / for DHCPv6 relay traversal) from / to the DHCPv4 side
-
- - a DHCPv4 side which processes encapsulated DHCPv4 messages
-
-Both sides support different command line arguments and configuration /
-lease / process ID files even some could be common, for instance
-most of the topology description.
-
-Second open of the hairy issues about configuring a DHCP server is
-the localization, i.e., how to associate a client with a subnetwork
-on a link (aka shared network).
-
-The topology is described in the server configuration file with
-shared-network and subnet/subnet6 declarations. A subnetwork is
-included in a shared-network, a shared network is created for
-each orphan subnetwork. For each requested interface, a shared network
-is built with all subnetworks matching its address.
-
-The procedure for DHCPv4 is in order:
+GENERAL
+The purpose of DHCPv4 over DHCPv6 (RFC7341) is to encapsulate
+a DHCPv4 request within a DHCPv6 request in order to transmit
+it across a v6 only network.  This feature may become useful
+when, during the transition from a v4 to a v6 network, there
+are still v4 clients at the edges and v4 servers in the center
+but the links between them are v6 only.
+
+In order to support this functionality we have chosen to use
+two processes each for the client and server.  In both pairs
+one process handles the DHCPv4 processing and the other handles
+the DHCPv6 processing.
+
+The topology is thus something like this:
+
+ Client processes    network    Server processes
+DHCPv4 <-> DHCPv6  <--ipv6-->  DHCPv6 <-> DHCPv4
+
+The v6 client and server processes can continue to process
+DHCPv6 packets as normal but will also allow a DHCPv4 process
+to connect to them via a socket.  The DHCPv4 client will pass
+a request to the DHCPv6 client which will encapsulate it within
+a DHPCv6 request which is sent to the DHCPv6 server (possibly
+via DHCPv6 relays).  When the DHCPv6 server receives the packet
+it will get the DHPCv4 query and pass it to the DHCPv4
+server.  The response will by handled in a similar fashion.
+
+When starting up the paired processes one should take care that
+they use different files for configuration, leases and process IDs.
+
+LOCALIZATION
+Normally the DHCPv4 server choose a subnet based on a number of options:
  - follow the Relay Agent Link Selection option if exists
-
  - follow the Subnet Selection option if exists
-
  - use the relay address if relayed
-
  - use the receiving interface
 
-At the exception of the last case the address must match a subnet address.
-
-The procedure for DHCPv6 is in order:
- - when relayed, use the first relay with an usable (i.e., not unspecified
-  or link-local) address
-
- - use the receiving interface
+With the exception of the last case the address must match a subnet address.
+Unfortunately when using DHCPv4 over DHCPv6 this information is not available
+in the packet, to quote RFC 7341:
 
-Note there can be multiple relays in DHCPv6, including layer 2 relays
-which provide no usuable link addresses.
-
-The localization issue is more complex (fun!) with DHCPv4 over DHCPv6
-as explained in RFC 7341 quoted here:
    Since the DHCPv4 message is encapsulated in the DHCPv6 message, it
    lacks the information that is typically used by the DHCPv4 server,
    implementing [RFC2131], to make address- allocation decisions,
@@ -56,10 +53,10 @@ as explained in RFC 7341 quoted here:
 
 In DHCPv4 over DHCPv6, there are a mixture of IPv6 and IPv4 addresses.
 The DHCPv4 over DHCPv6 server externally uses only IPv6 addresses,
-even at the DHCPv4 side, so shared networks associated to directly
+even on the DHCPv4 side, so shared networks associated with directly
 attached interfaces are identified by subnet6 declarations.
-For this reason, the DHCPv4 side should request no interface
-by the command line or configuration file: all usable interfaces
+For this reason, the DHCPv4 side shouldn't request an interface
+vai the command line or configuration file: all usable interfaces
 will be requested (i.e., standard behavior when no interface is
 specified in the command line or configuration file) and it is
 not an error to have an interface with an address and no matching
@@ -74,18 +71,14 @@ a relay address are very unlikely cases.
 
 So the procedure is:
  - follow the Relay Agent Link Selection option if exists
-
  - follow the DHCPv4 Subnet Selection option if exists
-
  - use the DHCPv4 relay address if DHCPv4 relayed
-
  - when DHCPv6 relayed, use the first relay with an usable (i.e., not
-  unspecified or link-local) address
-
+   unspecified or link-local) address
  - use the receiving interface
 
-So for more fun one can get a configuration like:
-
+The basic network configuration is something like this:
+----
 shared-network "link1" {
     subnet6 2001:db8:1:1::/64 { }
 
@@ -93,12 +86,14 @@ shared-network "link1" {
         range 192.168.1.100 192.168.1.199;
     }
 }
+----
 
-So a DHCPv4 over DHCPv6 client using the 2001:db8:1:1::10 IPv6 address
-will get a 192.168.1.1xy assigned.
+This groups the 2001:db8:1:1::/64 subnet with the 192.168.1.0 subnet.
+When the a DHCPv4 over DHCPv6 client uses the 2001:db8:1:1::10 IPv6 address
+it will get an address from 192.168.1.1xy assigned.
 
-For more fun there is a remaining question: on which interface
-a DHCPv4 over DHCPv6 client should apply the assigned IPv4 address?
+There is one remaining question: on which interface should 
+a DHCPv4 over DHCPv6 client apply the assigned IPv4 address?
 RFC 7341 does not really help:
    Before applying for an IPv4 address via a DHCPv4-query message, the
    client must identify a suitable network interface for the address.
@@ -111,3 +106,116 @@ The ISC DHCP answer is the IPv4 address is (in fact is required to be)
 specified in the command line of the DHCPv4 side of the DHCPv4 over DHCPv6
 client. BTW in the usual case where the upstream interface is IPv6 only,
 the IPv4 interface will be a different one.
+
+
+                               HOW TO USE
+                               ----------
+
+
+CONFIGURATION
+By default the DHCPv4 over DHCPv6 code is disabled and in order to use
+it you will need to configure it.  Note that this code requires that the
+dhcpv6 code be enabled (it is enabled by default.)
+
+   ./configure --enable-dhcpv4o6
+
+CLIENT SETUP
+The client runs both a DHCPv6 client and a DHCPv4 client on the second
+Ethernet eth1.  The following could be used to launch them from the
+client directory. 
+
+   ./dhclient -d -v -6 -4o6 6767 -lf leases6 -pf pid6 eth1
+
+and
+
+   ./dhclient -d -v -4 -4o6 6767 -lf leases4 -pf pid4 eth1
+
+In this case we are using the port pair 6767 and 6768 for communication
+and one can start or stop either client as necessary (though if the
+v6 client is stopped the v4 client won't be able to contact a server).
+The lease files are leases4 and leases6 and the process id files are pid4 and
+pid6.  You would probably put the files elsewhere.
+
+For testing purposes it is best to run the two clients in the foreground
+and in separate windows.
+
+SERVER SETUP
+As with any DHCP servers you will need to ensure there is a path from
+the clients to the servers - any firewalls must allow DHCPv6 traffic
+through.  You should also verify no other DHCP servers are running
+and will conflict with the DHCPv4 over DHCPv6 pair.
+
+The server VM must have both IPv4 and IPv6 addresses.  On a system
+running Fedora with the second interface named eno33554984,
+the commands are:
+
+   ip addr add 10.10.10.1/24 dev eno33554984
+
+and
+
+   ip -6 addr add 2001:db8:1:1::1/64 dev eno33554984
+
+Note that in theory the IPv4 address is not required but:
+  - there are some DHCPv4 clients which refused responses with no or an
+    invalid server-id
+  - this avoids messages about being unable to find a subnet to configure or
+    something similar
+
+Both ISC DHCP and Kea use 2 processes to manage DHCPv4-over-DHCPv6, one 
+in charge of DHCPv6, the other in charge of DHCPv4. They communicate via UDP.
+
+ISC DHCP DHCPv6 SERVER
+The dhcpd.conf6 example configuration file is:
+----
+# DHCPv6 conf
+
+authoritative;
+
+default-lease-time 3600;
+max-lease-time 7200;
+
+option dhcp6.dhcp4-o-dhcp6-server 2001:db8:1:1::1;
+
+subnet6 2001:db8:1:1::/64 {
+        range6 2001:db8:1:1::1:0/112;
+}
+----
+
+The server is launched from the server directory by:
+
+  ./dhcpd -f -d -6 -4o6 6767 -cf ./dhcpd.conf6 -lf ./leases6 -pf ./pid6 eno33554984
+
+As with the client above the servers are using the port pair 6767 and 6768
+to communicate.  The leases file (leases6) must be created before attempting
+to start the server.
+
+ISC DHCP DHCPv4 SERVER
+The dhcpd.conf4 example configuration file is:
+----
+# DHCPv4o6 conf
+
+authoritative;
+
+default-lease-time 3600;
+max-lease-time 7200;
+
+shared-network "eno33554984" {
+    subnet6 2001:db8:1:1::/64 { }
+
+    subnet 10.10.10.0 netmask 255.255.255.0 {
+       range 10.10.10.100 10.10.10.199;
+    }
+}
+----
+
+The server is launched from the server directory by:
+
+   ./dhcpd -f -d -4 -4o6 6767 -cf ./dhcpd.conf4 -lf ./leases4 -pf ./pid4
+
+Note that the port specification must be the same as used with the v6 server
+and that the configuration, lease and process id files should have different
+names.  Again the The leases file (leases4) must be created before attempting
+to start the server.
+
+Finally note in the configuration file the use of the shared-netowrk to
+connect the DHCPv4 and  DHCPv6 subnets.