doc: add initial nhrpd documentation

[DL: resolved renaming & conflicts]
Signed-off-by: Timo Teräs <timo.teras@iki.fi>
Signed-off-by: David Lamparter <equinox@opensourcerouting.org>

7 files changed, 261 insertions, 1 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 04389c63a..d82a30730 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -59,7 +59,9 @@ frr.pdf: $(info_TEXINFOS) $(figures_pdf) $(frr_TEXINFOS)
 
 frr_TEXINFOS = appendix.texi basic.texi bgpd.texi isisd.texi filter.texi \
 	vnc.texi \
-	install.texi ipv6.texi kernel.texi main.texi ospf6d.texi ospfd.texi \
+	install.texi ipv6.texi kernel.texi main.texi \
+	nhrpd.texi \
+	ospf6d.texi ospfd.texi \
 	overview.texi protocol.texi ripd.texi ripngd.texi routemap.texi \
 	snmp.texi vtysh.texi routeserver.texi defines.texi $(figures_png) \
 	snmptrap.texi ospf_fundamentals.texi isisd.texi $(figures_txt)
@@ -111,6 +113,10 @@ if RIPNGD
 man_MANS += ripngd.8
 endif
 
+if NHRPD
+man_MANS += nhrpd.8
+endif
+
 if VTYSH
 man_MANS += vtysh.1
 endif
@@ -134,6 +140,7 @@ EXTRA_DIST = BGP-TypeCode draft-zebra-00.ms draft-zebra-00.txt \
 	ripd.8.in \
 	ripngd.8.in \
 	pimd.8.in \
+	nhrpd.8.in \
 	vtysh.1.in \
 	watchfrr.8.in \
 	zebra.8.in \
diff --git a/doc/bgpd.8.in b/doc/bgpd.8.in
index 704774463..9026f2cde 100644
--- a/doc/bgpd.8.in
+++ b/doc/bgpd.8.in
@@ -108,6 +108,7 @@ debugging options, see the Info file, or the source for details.
 .BR ospfd (8),
 .BR ospf6d (8),
 .BR isisd (8),
+.BR nhrpd (8),
 .BR zebra (8),
 .BR vtysh (1)
 .SH BUGS
diff --git a/doc/frr.texi b/doc/frr.texi
index d4a78b7b8..a64dc9e72 100644
--- a/doc/frr.texi
+++ b/doc/frr.texi
@@ -90,6 +90,7 @@ for @value{PACKAGE_STRING}. @uref{http://www.freerangerouting.org,,Frr} is a for
 * OSPFv2::
 * OSPFv3::
 * ISIS::
+* NHRP::
 * BGP::
 * Configuring Frr as a Route Server::
 * VNC and VNC-GW::
@@ -116,6 +117,7 @@ for @value{PACKAGE_STRING}. @uref{http://www.freerangerouting.org,,Frr} is a for
 @include ospfd.texi
 @include ospf6d.texi
 @include isisd.texi
+@include nhrpd.texi
 @include bgpd.texi
 @include routeserver.texi
 @include vnc.texi
diff --git a/doc/install.texi b/doc/install.texi
index 8c501ed45..b34f31684 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -267,6 +267,7 @@ bgpd          2605/tcp		  # BGPd vty
 ospf6d        2606/tcp		  # OSPF6d vty
 ospfapi       2607/tcp		  # ospfapi
 isisd         2608/tcp		  # ISISd vty
+nhrpd         2610/tcp		  # nhrpd vty
 pimd          2611/tcp		  # PIMd vty
 @end example
 
diff --git a/doc/nhrpd.8.in b/doc/nhrpd.8.in
new file mode 100644
index 000000000..c5e4f7e32
--- /dev/null
+++ b/doc/nhrpd.8.in
@@ -0,0 +1,105 @@
+.TH NHRP 8 "24 January 2017" "@PACKAGE_FULLNAME@ NHRP daemon" "Version @PACKAGE_VERSION@"
+.SH NAME
+nhrpd \- a Next Hop Routing Protocol routing engine for use with @PACKAGE_FULLNAME@.
+.SH SYNOPSIS
+.B nhrpd
+[
+.B \-dhv
+] [
+.B \-f
+.I config-file
+] [
+.B \-i
+.I pid-file
+] [
+.B \-P
+.I port-number
+] [
+.B \-A
+.I vty-address
+] [
+.B \-u
+.I user
+] [
+.B \-g
+.I group
+]
+.SH DESCRIPTION
+.B nhrpd
+is a routing component that works with the
+.B @PACKAGE_FULLNAME@
+routing engine.
+.SH OPTIONS
+Options available for the
+.B nhrpd
+command:
+.TP
+\fB\-d\fR, \fB\-\-daemon\fR
+Runs in daemon mode, forking and exiting from tty.
+.TP
+\fB\-f\fR, \fB\-\-config-file \fR\fIconfig-file\fR
+Specifies the config file to use for startup. If not specified this
+option will likely default to \fB\fI@CFG_SYSCONF@/nhrpd.conf\fR.
+.TP
+\fB\-g\fR, \fB\-\-group \fR\fIgroup\fR
+Specify the group to run as. Default is \fI@enable_group@\fR.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+A brief message.
+.TP
+\fB\-i\fR, \fB\-\-pid_file \fR\fIpid-file\fR
+When nhrpd starts its process identifier is written to
+\fB\fIpid-file\fR.  The init system uses the recorded PID to stop or
+restart nhrpd.  The likely default is \fB\fI@CFG_STATE@/nhrpd.pid\fR.
+.TP
+\fB\-P\fR, \fB\-\-vty_port \fR\fIport-number\fR
+Specify the port that the nhrpd VTY will listen on. This defaults to
+2610, as specified in \fB\fI/etc/services\fR.
+.TP
+\fB\-A\fR, \fB\-\-vty_addr \fR\fIvty-address\fR
+Specify the address that the nhrpd VTY will listen on. Default is all
+interfaces.
+.TP
+\fB\-u\fR, \fB\-\-user \fR\fIuser\fR
+Specify the user to run as. Default is \fI@enable_user@\fR.
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Print the version and exit.
+.SH FILES
+.TP
+.BI @CFG_SBIN@/nhrpd
+The default location of the
+.B nhrpd
+binary.
+.TP
+.BI @CFG_SYSCONF@/nhrpd.conf
+The default location of the
+.B nhrpd
+config file.
+.TP
+.BI $(PWD)/nhrpd.log
+If the
+.B nhrpd
+process is config'd to output logs to a file, then you will find this
+file in the directory where you started \fBnhrpd\fR.
+.SH WARNING
+This man page is intended to be a quick reference for command line
+options. The definitive document is the Info file \fB@PACKAGE_NAME@\fR.
+.SH DIAGNOSTICS
+The nhrpd process may log to standard output, to a VTY, to a log
+file, or through syslog to the system logs. \fBnhrpd\fR supports many
+debugging options, see the Info file, or the source for details.
+.SH "SEE ALSO"
+.BR bgpd (8),
+.BR ripd (8),
+.BR ripngd (8),
+.BR ospfd (8),
+.BR ospf6d (8),
+.BR zebra (8),
+.BR vtysh (1)
+
+.B nhrpd
+eats bugs for breakfast. If you have food for the maintainers try
+.BI @PACKAGE_BUGREPORT@
+.SH AUTHORS
+Timo Teräs <timo.teras@iki.fi>
diff --git a/doc/nhrpd.texi b/doc/nhrpd.texi
new file mode 100644
index 000000000..1820044ae
--- /dev/null
+++ b/doc/nhrpd.texi
@@ -0,0 +1,143 @@
+@cindex NHRP
+@node NHRP
+@chapter NHRP
+
+@command{nhrpd} is a daemon to support Next Hop Routing Protocol (NHRP).
+NHRP is described in RFC2332.
+
+NHRP is used to improve the efficiency of routing computer network
+traffic over Non-Broadcast, Multiple Access (NBMA) Networks. NHRP provides
+an ARP-like solution that allows a system to dynamically learn the NBMA
+address of the other systems that are part of that network, allowing
+these systems to directly communicate without requiring traffic to use
+an intermediate hop.
+
+Cisco Dynamic Multipoint VPN (DMVPN) is based on NHRP, and
+@value{PACKAGE_NAME} nhrpd implements this scenario.
+
+@menu
+* Routing Design::
+* Configuring NHRP::
+* Hub Functionality::
+* Integration with IKE::
+* NHRP Events::
+* Configuration Example::
+@end menu
+
+@node Routing Design
+@section Routing Design
+
+nhrpd never handles routing of prefixes itself. You need to run some
+real routing protocol (e.g. BGP) to advertise routes over the tunnels.
+What nhrpd does it establishes 'shortcut routes' that optimizes the
+routing protocol to avoid going through extra nodes in NBMA GRE mesh.
+
+nhrpd does route NHRP domain addresses individually using per-host prefixes.
+This is similar to Cisco FlexVPN; but in contrast to opennhrp which uses
+a generic subnet route.
+
+To create NBMA GRE tunnel you might use the following (linux terminal
+commands):
+@example
+@group
+ ip tunnel add gre1 mode gre key 42 ttl 64
+ ip addr add 10.255.255.2/32 dev gre1
+ ip link set gre1 up
+@end group
+@end example
+
+Note that the IP-address is assigned as host prefix to gre1. nhrpd will
+automatically create additional host routes pointing to gre1 when
+a connection with these hosts is established.
+
+The gre1 subnet prefix should be announced by routing protocol from the
+hub nodes (e.g. BGP 'network' announce). This allows the routing protocol
+to decide which is the closest hub and determine the relay hub on prefix
+basis when direct tunnel is not established.
+
+nhrpd will redistribute directly connected neighbors to zebra. Within
+hub nodes, these routes should be internally redistributed using some
+routing protocol (e.g. iBGP) to allow hubs to be able to relay all traffic.
+
+This can be achieved in hubs with the following bgp configuration (network
+command defines the GRE subnet):
+@example
+@group
+router bgp 65555
+   network 172.16.0.0/16
+   redistribute nhrp
+@end group
+@end example
+
+
+@node Configuring NHRP
+@section Configuring NHRP
+
+FIXME
+
+@node Hub Functionality
+@section Hub Functionality
+
+In addition to routing nhrp redistributed host prefixes, the hub nodes
+are also responsible to send NHRP Traffic Indication messages that
+trigger creation of the shortcut tunnels.
+
+nhrpd sends Traffic Indication messages based on network traffic captured
+using NFLOG. Typically you want to send Traffic Indications for network
+traffic that is routed from gre1 back to gre1 in rate limited manner.
+This can be achieved with the following iptables rule.
+
+@example
+@group
+iptables -A FORWARD -i gre1 -o gre1 \
+	-m hashlimit --hashlimit-upto 4/minute --hashlimit-burst 1 \
+	--hashlimit-mode srcip,dstip --hashlimit-srcmask 24 --hashlimit-dstmask 24 \
+	--hashlimit-name loglimit-0 -j NFLOG --nflog-group 1 --nflog-range 128
+@end group
+@end example
+
+You can fine tune the src/dstmask according to the prefix lengths you
+announce internal, add additional IP range matches, or rate limitation
+if needed. However, the above should be good in most cases.
+
+This kernel NFLOG target's nflog-group is configured in global nhrp config
+with:
+@example
+@group
+nhrp nflog-group 1
+@end group
+@end example
+
+To start sending these traffic notices out from hubs, use the nhrp
+per-interface directive:
+@example
+@group
+interface gre1
+ ip nhrp redirect
+@end group
+@end example
+
+@node Integration with IKE
+@section Integration with IKE
+
+nhrpd needs tight integration with IKE daemon for various reasons.
+Currently only strongSwan is supported as IKE daemon.
+
+nhrpd connects to strongSwan using VICI protocol based on UNIX socket
+(hardcoded now as /var/run/charon.vici).
+
+strongSwan currently needs few patches applied. Please check out the
+@uref{http://git.alpinelinux.org/cgit/user/tteras/strongswan/log/?h=tteras-release,release}
+and
+@uref{http://git.alpinelinux.org/cgit/user/tteras/strongswan/log/?h=tteras,working tree}
+git repositories for the patches.
+
+@node NHRP Events
+@section NHRP Events
+
+FIXME
+
+@node Configuration Example
+@section Configuration Example
+
+FIXME
diff --git a/doc/zebra.8.in b/doc/zebra.8.in
index e7d00e10a..4599a8563 100644
--- a/doc/zebra.8.in
+++ b/doc/zebra.8.in
@@ -119,6 +119,7 @@ debugging options, see the Info file, or the source for details.
 .BR ospfd (8),
 .BR ospf6d (8),
 .BR isisd (8),
+.BR nhrpd (8),
 .BR vtysh (1)
 .SH BUGS
 .B zebra