Initial commit

1 files changed, 85 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..c1c0d1e
--- /dev/null
+++ b/README
@@ -0,0 +1,85 @@
+odhcpd - Embedded DHCP/DHCPv6/RA Server & Relay
+
+** Abstract **
+
+odhcpd is a daemon for serving and relaying IP management protocols to
+configure clients and downstream routers. It tries to follow the RFC 6204
+requirements for IPv6 home routers.
+
+odhcpd provides server services for DHCP, RA, stateless and stateful DHCPv6,
+prefix delegation and can be used to relay RA, DHCPv6 and NDP between routed
+(non-bridged) interfaces in case no delegated prefixes are available.
+
+
+** Features **
+
+1. Router Discovery support (solicitations and advertisements) with 2 modes
+   server:	RD server for slave interfaces
+   a) automatic detection of prefixes, delegated prefix and default routes, MTU
+   b) automatic reannouncement when changes to prefixes or routes occur
+
+   relay:	RD relay between master and slave interfaces
+   a) support for rewriting announced DNS-server addresses in relay mode
+   
+3. DHCPv6-support with 2 modes of operation
+   server:	minimalistic server mode
+   a) stateless and stateful address assignment
+   b) prefix delegation support
+   c) dynamic reconfiguration in case prefixes change
+   d) hostname detection and hosts-file creation
+
+   relay: 	mostly standards-compliant DHCPv6-relay
+   a) support for rewriting announced DNS-server addresses
+   
+4. Proxy for Neighbor Discovery messages (solicitations and advertisments)
+   a) support for auto-learning routes to the local routing table
+   b) support for marking interfaces "external" not proxying NDP for them
+      and only serving NDP for DAD and for traffic to the router itself
+      [Warning: you should provide additional firewall rules for security]
+
+
+** Compiling **
+
+odhcpd uses cmake:
+* To prepare a Makefile use:  "cmake ." 
+* To build / install use: "make" / "make install" afterwards.
+* To build DEB or RPM packages use: "make package" afterwards.
+
+
+** Server Mode **
+
+0. Server mode is used as a minimalistic alternative for full-blown servers
+   like radvd or ISC DHCP if simplicity or a small footprint matter.
+   Note: The master interface is unused in this mode. It should be set to '.'.
+
+1. If there are non-local addresses assigned to the slave interface when a
+   router solicitation is received, said prefixes are announced automatically
+   for stateless autoconfiguration and also offered via stateful DHCPv6.
+   If all prefixes are bigger than /64 all but the first /64 of these prefixes
+   is offered via DHCPv6-PD to downstream routers.
+
+2. If DNS servers should be announced (DHCPv6 server-mode) then a local DNS-
+   proxy (e.g. dnsmasq) needs to be run on the router itself because 6relayd
+   will always announce a local address as DNS-server (if not otherwise
+   configured).
+
+3. odhcpd is run with the appropriate configuration.
+
+
+** Relay Mode **
+
+0. Relay mode is used when a /64-bit IPv6-Prefix should be distributed over
+   several links / isolated layer 2 domains (e.g. if no prefix delegation
+   is available). In this mode NDP (namely Router Discovery and Neighbor
+   Discovery) messages and DHCPv6-messages are proxied. For DHCPv6 also
+   server mode can be used instead of relaying if desired.
+
+1. When starting 6relayd it is required that the master interface - where
+   IPv6-service is already provided - is configured and usable.
+   
+2. If the upstream router doesn't provide or announce a DNS-service that is
+   reachable in an at least site-local scope, a local DNS proxy (e.g. dnsmasq)
+   needs to be run and configued on the same router where 6relayd is running.
+   (This step can most likely be skipped in most environments.)
+   
+3. odhcpd is run with the appropriate configuration.