hnetd - a home network configuration daemon


** Abstract **

hnetd is a networking daemon to automatically manage address assignment,
routing, DNS, SD and border firewalling in home networks running it.
It implements the Home Networking Control protocol as specified in
http://tools.ietf.org/html/draft-ietf-homenet-hncp

hnetd is designed to run on generic Linux-based routers.


** License **

This project was originally licensed under the GNU General Public
License 2. With the agreement of all copyright holders responsible for
contributions in this branch, the license was changed to Apache 2.0
effective April 3rd 2016.

** Features **

1. State synchronization between routers
	a) link-local multicast transmission
	b) unicast fallback for bulk synchronization
	c) collision and conflict detection and resolving

2. Prefix distribution and allocation
	a) IPv6 prefix delegation
	b) IPv4 prefix allocation

3. Routing setup
	a) selection of a shared routing protocol
	b) fallback mechanism to setup routes autonomously

4. Dynamic border-detection for IPv4 and IPv6
	a) on-demand firewall reconfiguration
	b) on-demand RA/DHCP/DHCPv6 server configuration
	c) integration of fixed external connections (e.g. PPP, 6rd, ...)

5. Sharing of DNS and Service Discovery configuration
	a) Local DNS configuration
	b) mDNS / DNS-SD hybrid proxy configuration


** Compiling **

hnetd depends on the following libraries:
* json-c: https://github.com/json-c/json-c
* libubox: https://git.openwrt.org/project/libubox.git
* libubus (OpenWrt only): https://git.openwrt.org/project/ubus.git

hnetd uses the following auxiliary tools (replacable):
* odhcp6c (DHCPv6 client): https://github.com/sbyx/odhcp6c
* odhcpd (RA/DHCP/DHCPv6 server): https://github.com/sbyx/odhcpd
* ohybridproxy (mDNS proxy, optional): https://github.com/sbyx/ohybridproxy
* minimalist-pcproxy (PCP proxy, optional): https://github.com/fingon/minimalist-pcproxy
* udhcpc (DHCP client): http://busybox.net

hnetd uses cmake:
* To prepare a Makefile use:  "cmake . -DCMAKE_INSTALL_PREFIX=/usr"
* To build / install use: "make" / "make install" afterwards.
* To build DEB or RPM packages use: "make package" afterwards.

Note: The script "build-generic.sh" can aid in building hnet and its
dependencies and tools on Debian/Ubuntu/Mint and related Linux distributions.


** OpenWrt Firmware Integration **

hnetd and ohybridproxy can be built from the openwrt-routing feed.
Use:
	./scripts/feeds update
	./scripts/feeds install hnetd ohybridproxy

and select both packets in "make menuconfig" under "Network" and the submenu
"IP Addresses and Names". Snapshot packages might be available in the OpenWrt
daily snapshots folder: http://downloads.openwrt.org/snapshots/trunk/

To use hnetd on an interface add a config section in /etc/config/network, e.g.

config interface homenet0
	option ifname eth0
	option proto hnet

or select the protocol "Automatic Homenet (HNCP)" in the web interface.

IMPORTANT: Remove or comment out other config sections running DHCP or DHCPv6
clients on the interfaces your run hnet on. Additional static configuration
section may be kept for debugging purposes.

WARNING: Do NOT set the proto of either the “lan”, “wan” or “wan6” interface
to hnet directly. Always rename your interfaces to a different name,
e.g. homenet0 or homenet1.


** Generic Firmware Integration **

hnetd can be integrated into generic Linux router firmwares with recent 3.10.x
or later kernels. The scripts that need to be adapted for the integration can
be found in the folder "generic".

Copy the scripts hnet-backend and hnetd-routing to /usr/sbin/ and adapt
them if needed. The symlinks hnet-client, hnet-ifup and hnet-ifdown should be
preserved as well.

Copy the scripts dhcp.script and dhcpv6.script to /usr/share/hnetd and
adapt them if needed.

If you are using odhcpd as DHCP/DHCPv6/RA server start it as a daemon.
Afterwards run hnetd with appropriate parameters.

Once both services are running, you can use the hnet CLI tools:

hnet-ifup [-c category] [-a] [-d] [-u] [-p prefix] [-l id[/idmask]]
	[-i id/idmask [filter-prefix]] [-m ip6_plen] [-k trickle_k]
	[-P ping_interval] [-4 global-IPv4-address] [-6 delegated prefix]
	[-D dns-server] <interfacename>
adds the network interface <interfacename> (e.g. eth0) to the homenet.
-c is an optional parameter declaring the interface category
   (see https://tools.ietf.org/html/draft-ietf-homenet-hncp-04#page-5)
	auto: auto-detect if interface is internal or external (default)
	external: interface is always external / towards an ISP
	static: like external, but does not run a DHCP or DHCPv6 client
	internal: interface is always internal / towards interior nodes
	leaf: like internal but connects to clients-only (no routers)
	guest: like leaf, but clients should only reach the Internet
	hybrid: like internal, but connected to trusted, legacy CPE (experimental)
	adhoc: like internal, but link is non-transitive (e.g. mesh) (experimental)
static:
-4 is an optional parameter indicating the public IPv4 address of the interface
-6 is an optional parameter indicating an IPv6-prefix delegated to the interface
-D is an optional parameter indicating a public recursive DNS server
internal / leaf / guest / hybrid / adhoc:
-p is an optional parameter indicating one or more static prefixes.
-l is an optional parameter setting the link-id and id-mask.
-i is an optional parameter indicating one or more iface ids.
-m is an optional parameter overriding the default prefix length when
	generating an IPv6 assignment.
-d is an optional parameter indicating prefix assignment must be disabled.
-u is an optional parameter indicating that an IPv6 default route should be
	announced even when there is only a ULA-prefix present.
-k is an optional parameter indicating the interface's trickle K parameter.
-P is an optional parameter indicating the dead-peer-detection interval value in ms.

hnet-ifdown <interfacename> removes an interface from hnet again.

hnet-dump dumps you (most of) the current state of the network as JSON.