[quagga-dev,16558] doc: add initial nhrpd documentation

Message ID 20170124144219.23073-1-timo.teras@iki.fi
State Under Review
Headers show

Commit Message

Timo Teräs Jan. 24, 2017, 2:42 p.m.
---
I started writing the quagga style documentation for nhrpd.
This is what I have currently. It's mostly based on the existing
readme files, but now included in the generated docs properly.

 doc/Makefile.am  |   6 ++-
 doc/bgpd.8       |   1 +
 doc/install.texi |   1 +
 doc/nhrpd.8      | 105 ++++++++++++++++++++++++++++++++++++++++
 doc/nhrpd.texi   | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/quagga.texi  |   2 +
 doc/zebra.8      |   1 +
 7 files changed, 258 insertions(+), 1 deletion(-)
 create mode 100644 doc/nhrpd.8
 create mode 100644 doc/nhrpd.texi

Patch hide | download patch | download mbox

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 00d404a7..be1ee1fb 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -95,6 +95,10 @@  if RIPNGD
 man_MANS += ripngd.8
 endif
 
+if NHRPD
+man_MANS += nhrpd.8
+endif
+
 if VTYSH
 man_MANS += vtysh.1
 endif
@@ -109,7 +113,7 @@  endif
 
 EXTRA_DIST = BGP-TypeCode draft-zebra-00.ms draft-zebra-00.txt \
 	bgpd.8 isisd.8 ospf6d.8 ospfclient.8 ospfd.8 ripd.8 \
-	ripngd.8 pimd.8 vtysh.1 watchquagga.8 zebra.8 \
+	ripngd.8 nhrpd.8 pimd.8 vtysh.1 watchquagga.8 zebra.8 \
 	mpls/ChangeLog.opaque.txt mpls/cli_summary.txt \
 	mpls/opaque_lsa.txt mpls/ospfd.conf \
 	$(figures_sources) $(figures_png) $(figures_txt) \
diff --git a/doc/bgpd.8 b/doc/bgpd.8
index 8daaefa2..e13ef18b 100644
--- a/doc/bgpd.8
+++ b/doc/bgpd.8
@@ -106,6 +106,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/install.texi b/doc/install.texi
index 7349e92c..f2bcf0a1 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -274,6 +274,7 @@  ospf6d        2606/tcp		  # OSPF6d vty
 ospfapi       2607/tcp		  # ospfapi
 isisd         2608/tcp		  # ISISd vty
 pimd          2611/tcp		  # PIMd vty
+nhrpd         2612/tcp		  # nhrpd vty
 @end example
 
 If you use a FreeBSD newer than 2.2.8, the above entries are already
diff --git a/doc/nhrpd.8 b/doc/nhrpd.8
new file mode 100644
index 00000000..e227c207
--- /dev/null
+++ b/doc/nhrpd.8
@@ -0,0 +1,105 @@ 
+.TH NHRP 8 "24 January 2017" "Quagga NHRP daemon" "Version 1.1"
+.SH NAME
+nhrpd \- a Next Hop Routing Protocol routing engine for use with Quagga routing software.
+.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 Quagga
+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/usr/local/etc/nhrpd.conf\fR.
+.TP
+\fB\-g\fR, \fB\-\-group \fR\fIgroup\fR
+Specify the group to run as. Default is \fIquagga\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/var/run/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
+2608, 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 \fIquagga\fR.
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Print the version and exit.
+.SH FILES
+.TP
+.BI /usr/local/sbin/nhrpd
+The default location of the
+.B nhrpd
+binary.
+.TP
+.BI /usr/local/etc/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 \fBQuagga\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 http://bugzilla.quagga.net
+.SH AUTHORS
+Timo Teräs <timo.teras@iki.fi>
diff --git a/doc/nhrpd.texi b/doc/nhrpd.texi
new file mode 100644
index 00000000..6caf5a62
--- /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 Quagga nrhpd
+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/quagga.texi b/doc/quagga.texi
index 65089621..9e533376 100644
--- a/doc/quagga.texi
+++ b/doc/quagga.texi
@@ -85,6 +85,7 @@  for @value{PACKAGE_STRING}. @uref{http://www.quagga.net,,Quagga} is a fork of
 * RIPng::
 * OSPFv2::
 * OSPFv3::
+* NHRP::
 * BGP::
 * Configuring Quagga as a Route Server::
 * VTY shell::
@@ -109,6 +110,7 @@  for @value{PACKAGE_STRING}. @uref{http://www.quagga.net,,Quagga} is a fork of
 @include ripngd.texi
 @include ospfd.texi
 @include ospf6d.texi
+@include nhrpd.texi
 @include bgpd.texi
 @include routeserver.texi
 @include vtysh.texi
diff --git a/doc/zebra.8 b/doc/zebra.8
index a40909a6..6f70389f 100644
--- a/doc/zebra.8
+++ b/doc/zebra.8
@@ -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