5 files changed, 623 insertions, 0 deletions
diff --git a/man/Makefile b/man/Makefile
new file mode 100644
index 0000000..c3027f9
--- /dev/null
+++ b/man/Makefile
@@ -0,0 +1,7 @@
+MAN5PAGES = opennhrp.conf.5
+MAN8PAGES = opennhrp.8 opennhrpctl.8 opennhrp-script.8
+
+install:
+	$(INSTALLDIR) $(DESTDIR)$(MANDIR)/man5 $(DESTDIR)$(MANDIR)/man8
+	$(INSTALL) $(addprefix $(src)/,$(MAN5PAGES)) $(DESTDIR)$(MANDIR)/man5
+	$(INSTALL) $(addprefix $(src)/,$(MAN8PAGES)) $(DESTDIR)$(MANDIR)/man8
diff --git a/man/opennhrp-script.8 b/man/opennhrp-script.8
new file mode 100644
index 0000000..0af32b1
--- /dev/null
+++ b/man/opennhrp-script.8
@@ -0,0 +1,146 @@
+.TH OPENNHRP-SCRIPT 8 "20 May 2009" "" "OpenNHRP Documentation"
+
+.SH NAME
+opennhrp-script \- NHRP peer configuration script
+
+.SH DESCRIPTION
+NHRP peer configuration script is used invoked by
+.BR opennhrp (8).
+.PP
+This script can be used to establish a direct NBMA peer to peer connection
+after NHRP Resolution Reply has been received, but prior to injecting the
+peer address to kernel neighbor table. This could be to insert firewall rules
+allowing the traffic and/or establishing an IPsec connection (or some other
+secure communication channel). The script is also called when the cached peer
+information expires.
+
+.SH OPERATION
+When
+.B opennhrp
+needs to invoke the peer configuration script, it defines a set of variables
+in the environment and then executes the script with exactly one argument.
+The argument is set to the name of the reason why the script has been invoked.
+The following reasons are currently defined:
+.BR "interface-up" , " peer-register" , " peer-up" , " peer-down" ,
+.BR " nhs-up" , " nhs-down" , " route-up" " and " route-down .
+
+.SH INTERFACE-UP
+Interface has been just discovered, or it is has changed state from down
+to up. This is the place to clean up old routes if needed.
+
+.SH PEER-REGISTER
+A peer registration request has been received. The script is run before the
+internal peer cache is altered and this allows the script to reject
+registration without it deleting old peers. This could be used to check that
+IPsec connection is up or one might encode allowed protocol-addresses in the
+certificate and it could be enforced here. This hook is executed synchronously
+so it should be fast.
+
+.SH PEER-UP
+A peer has been discovered (either by means of static configuration, dynamic
+client registration or resolution reply arrival to initiate shortcut).
+This hook is invoked right after the peer's NBMA address is available. For all
+other than dynamic-map entries the protocol address is available too.
+The information will not be injected to the kernel ARP cache until the script
+has returned zero. If non-zero return value is returned, the peer entry is
+marked as invalid and negative cached for a short period of time.
+
+.SH PEER-DOWN
+A peer connection is about to be cleared. This can happend for dynamic client
+registrations or cached information. Dynamic client registrations are teared
+down when registration holding time expires (and no re-registration has
+occured) or if it explicitely removed using Purge Request. Cached entries are
+removed when holding time expires (and there has been no traffic to trigger
+renewal of the peer address information) or when it is explicitely removed
+with Purge Request.
+
+.SH NHS-UP
+This is called for NHS right after the first succesful Registration Reply
+is received.
+This can be used to update application level configuration about which
+servers to use.
+
+.SH NHS-DOWN
+Informs that the specified NHS is no longer available.
+
+.SH ROUTE-UP
+In reply to resolution request we have received a shortcut route with
+destination off the NBMA subnetwork. The script should insert appropriate
+entry to kernel routing table.
+
+.SH ROUTE-DOWN
+The associated shortcut route information is no longer valid and should be
+removed from kernel routing table.
+
+.SH ENVIRONMENT
+.B NHRP_TYPE
+.RS
+For peer-up and peer-down reasons this can be:
+\fBstatic\fR (configured information),
+\fBdynamic-nhs\fR (configured NHS with only NBMA address known),
+\fBdynamic\fR (client registered) or
+\fBcached\fR (resolved since we had packets going there).
+
+The nhs-up and nhs-down reasons are called for \fBstatic\fR entries with
+register keyword and \fBdynamic-nhs\fR entries.
+
+For peer-register this is always \fBdynamic\fR.
+
+For route-up and route-down reasons this is always defined as \fBroute\fR.
+
+For interface-up reason this is irrelevant, but always defined as
+\fBinterface\fR.
+.RE
+
+.B NHRP_INTERFACE
+.RS
+The network interface to which this event is related to.
+.RE
+
+.B NHRP_GRE_KEY
+.RS
+The GRE key assigned to the related network interface.
+.RE
+
+.B NHRP_DESTADDR
+.RS
+Destination protocol address. E.g. for NBMA GRE tunnels this is the IP address
+assigned to the tunnel interface being used.
+.RE
+
+.B NHRP_DESTPREFIX
+.RS
+Subnet prefix length for destination protocol address.
+.RE
+
+.B NHRP_DESTNBMA
+.RS
+Defined only for \fBpeer-up\fR and \fBpeer-down\fR reasons. This contains the
+NBMA address of the destination. E.g. for NBMA GRE this contains the public IP
+of the peer.
+.RE
+
+.B NHRP_DESTMTU
+.RS
+Defined only for \fBpeer-up\fR reasons. This contains the MTU for NBMA
+address of the destination.
+.RE
+
+.B NHRP_NEXTHOP
+.RS
+Defined only for \fBroute-up\fR and \fBroute-down\fR reasons. This is the
+protocol address of the next hop to be used in routing.
+.RE
+
+.B NHRP_PEER_DOWN_REASON
+.RS
+Defined only for \fBpeer-down\fR reason. This describes why the peer has
+been deleted. Currently it is one of \fBexpired\fR, \fBuser-request\fR or
+\fBlower-down\fR.
+.RE
+
+.SH "SEE ALSO"
+.BR opennhrp (8)
+
+.SH AUTHORS
+Timo Teras <timo.teras@iki.fi>
diff --git a/man/opennhrp.8 b/man/opennhrp.8
new file mode 100644
index 0000000..b83b94b
--- /dev/null
+++ b/man/opennhrp.8
@@ -0,0 +1,119 @@
+.TH OPENNHRP 8 "16 November 2007" "" "OpenNHRP Documentation"
+
+.SH NAME
+opennhrp \- daemon to resolve next hop address in NBMA network
+
+.SH SYNOPSIS
+.BI "opennhrp [" "option" "]..."
+
+.SH DESCRIPTION
+.B opennhrp
+implements the Next Hop Resolution Protocol (NHRP) which is used to
+improve the efficiency of routing computer network traffic over
+Non-Broadcast, Multiple Access (NBMA) Networks.
+.PP
+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.
+.PP
+.B opennhrp
+implementation is based on RFC2332, but contains some modifications and
+extensions to be compatible with Cisco NHRP/DMVPN implementation.
+Modifications have been made for authentication extension, Cisco NAT
+address extension and shortcut switching enhancements support.
+
+.SH OPTIONS
+The following options are recognized:
+
+.IP "\fB\-a \fIadmin\-socket"
+Specify management interface socket as
+.IR admin\-socket .
+The default is
+.IR /var/run/opennhrp.socket .
+
+.IP "\fB\-c \fIconfig\-file"
+Use
+.I config\-file
+instead of
+.I /etc/opennhrp/opennhrp.conf
+for configuration.
+
+.IP "\fB\-s \fIscript\-file"
+Execute
+.I script\-file
+instead of
+.I /etc/opennhrp/opennhrp\-script
+on important events.
+
+.IP "\fB\-p \fIpid\-file"
+Store process id in
+.I pid\-file
+instead of
+.IR /var/run/opennhrp.pid .
+This file is also used to detect if opennhrp daemon is already running.
+Pid-file is not created unless
+.B -d
+is specified too.
+
+.IP "\fB-d"
+Run in daemon mode, forking to background after initialization.
+
+.IP "\fB-v"
+Verbose. Print more log messages.
+
+.IP "\fB-V"
+Print version and exit.
+
+.SH SIGNALS
+.IP \fBSIGHUP
+Forget all cached information about other system addresses.
+.IP \fBSIGUSR1
+Dump NHRP peer database to system log.
+
+.SH FILES
+.I /etc/opennhrp/opennhrp.conf
+.RS
+The system wide configuration file. See
+.BR opennhrp.conf (5)
+for further details.
+.RE
+
+.I /etc/opennhrp/opennhrp\-script
+.RS
+Script executed by
+.B opennhrp
+on important events. See
+.BR opennhrp\-script (8)
+for more information how the script is executed.
+.RE
+
+.I /var/run/opennhrp.socket
+.RS
+.BR opennhrp "(8) control socket"
+.RE
+
+.SH BUGS
+Currently only IPv4 over IPv4 networks using NBMA GRE tunnels is
+supported (you need Linux kernel 2.6.24-rc2 or later).
+.PP
+Replying with cached information to non-authorative resolution
+requests is not implemented.
+.PP
+Please send bug reports to OpenNHRP issue tracker in SourceForge.
+
+.SH "SEE ALSO"
+.BR opennhrp.conf (5),
+.BR opennhrpctl (8),
+.BR opennhrp\-script (8)
+.br
+http://sourceforge.net/projects/opennhrp
+.PP
+For more information about the protocol see:
+.br
+RFC2332 NBMA Next Hop Resolution Protocol (NHRP)
+.br
+RFC2333 NHRP Protocol Applicability Statement
+
+.SH AUTHORS
+Timo Teras <timo.teras@iki.fi>
diff --git a/man/opennhrp.conf.5 b/man/opennhrp.conf.5
new file mode 100644
index 0000000..aacec80
--- /dev/null
+++ b/man/opennhrp.conf.5
@@ -0,0 +1,227 @@
+.TH OPENNHRP.CONF 5 "27 Oct 2010" "" "OpenNHRP Documentation"
+
+.SH NAME
+opennhrp.conf \- NHRP daemon configuration file
+
+.SH DESCRIPTION
+The
+.I opennhrp.conf
+file contains information for the
+.BR opennhrp .
+.PP
+This configuration file is a free-form ASCII text file. It is parsed by the
+word-by-word parser built into
+.BR opennhrp .
+The file may contain extra whitespace, tabs and newline for formatting
+purposes. Keywords and contents are case-sensitive. Comments can be marked
+with a hash sign
+.RB ( # )
+and everything following it until newline is ignored.
+
+.SH "DIRECTIVES"
+Directives are keywords that can appear in any context of the configuration
+file and they select a new context.
+
+.PP
+.BI "interface " interface-name
+.RS
+Marks the start of configuration for network interface
+.IR interface-name .
+Even if no interface specific configuration is required, the
+.B interface
+directive must be present to enable NHRP on that interface.
+.RE
+
+.SH "INTERFACE CONTEXT"
+These configuration keywords can appear only in the interface context.
+
+.PP
+.BI "map " protocol-address[/prefix] " " nbma-address " [register] [cisco]"
+.RS
+Creates static peer mapping of
+.I protocol-address
+to
+.IR nbma-address .
+.PP
+If the
+.I prefix
+parameter is present, it directs
+.B opennhrp
+to use this peer as a next hop server when sending Resolution Requests
+matching this subnet.
+.PP
+The optional parameter
+.I register
+specifies that Registration Request should be sent to this peer on
+startup.
+.PP
+If the statically mapped peer is running Cisco IOS, specify the
+.B cisco
+keyword. It is used to fix statically the Registration Request ID
+so that a matching Purge Request can be sent if NBMA address has changed.
+This is to work around broken IOS which requires Purge Request ID to
+match the original Registration Request ID.
+.RE
+
+.BI "dynamic-map " protocol-address/prefix " " nbma-domain-name
+.RS
+Specifies that the NBMA addresses of the next hop servers are defined in the
+domain name
+.IR nbma-domain-name .
+For each A record opennhrp creates a dynamic NHS entry.
+
+Each dynamic NHS will get a peer entry with the configured network address
+and the discovered NBMA address.
+
+The first registration request is sent to the protocol broadcast address,
+and the server's real protocol address is dynamically detected from the first
+registration reply (requires opennhrp 0.11 or newer).
+
+Alternatively, if
+.BR peer-up
+script hook can determine the protocol address from the NBMA address (e.g.
+by doing an additional DNS lookup or by parsing the IPsec certificate) it can
+inform this mapping via
+.BR opennhrpctl "(8) " "update nbma " command.
+.RE
+
+.PP
+.BI "shortcut-target " protocol-address/prefix " [holding-time " holdtime "]"
+.RS
+Defines an off-NBMA network prefix for which the GRE interface will act
+as a gateway. This an alternative to defining local interfaces with
+shortcut-destination flag.
+.RE
+
+.BR multicast " " dynamic "|" nhs
+.br
+.BI "multicast " protocol-address
+.RS
+Determines how opennhrp daemon should soft switch the multicast traffic.
+Currently, multicast traffic is captured by opennhrp daemon using a packet
+socket, and resent back to proper destinations. This means that multicast
+packet sending is CPU intensive.
+
+Specfying
+.B nhs
+makes all multicast packets to be repeated to each statically configured
+next hop.
+.B dynamic
+instructs to forward to all peers which we have a direct connection with.
+Alternatively, you can specify the directive multiple times for each
+.I protocol-address
+the multicast traffic should be sent to.
+
+.B "WARNING:"
+It is very easy to misconfigure multicast repeating if you have multiple
+NHS:es.
+.RE
+
+.BI "holding-time " holdtime
+.RS
+Specifies the holding time for NHRP Registration Requests and
+Resolution Replies sent from this interface or shortcut-target.
+The
+.I holdtime
+is specified in seconds and defaults to two hours.
+.RE
+
+.BI "route-table " routetable
+.RS
+Specifies the kernel routing table to be monitored for outgoing routes
+to this interface. This is required to do routing lookups excluding
+active shortcut routes (for existing shortcut route renewal). The
+default is main table.
+
+If you use
+.B table
+directive in
+.B zebra.conf
+to put Quagga routes in alternate table, this should match with it.
+.RE
+
+.BI "cisco-authentication " secret
+.RS
+Enables Cisco style authentication on NHRP packets. This embeds the
+.I secret
+plaintext password to the outgoing NHRP packets. Incoming NHRP packets
+on this interface are discarded unless the
+.I secret
+password is present. Maximum length of the
+.I secret
+is 8 characters.
+.RE
+
+.B redirect
+.RS
+Enable sending of Cisco style NHRP Traffic Indication packets. If
+this is enabled and
+.B opennhrp
+detects a forwarded packet, it will send a message to the original sender
+of the packet instructing it to create a direct connection with the
+destination. This is basically a protocol independent equivalent of ICMP
+redirect.
+.RE
+
+.B shortcut
+.RS
+Enable creation of shortcut routes. A received NHRP Traffic Indication
+will trigger the resolution and establishment of a shortcut route.
+.PP
+.B IMPORTANT:
+You still need to run some routing protocol or have static routes
+to some hub node in your NBMA network. NHRP does not advertise routes;
+it can create shortcut route only for an already routable subnet.
+.RE
+
+.B non-caching
+.RS
+Disables caching of peer information from forwarded NHRP Resolution
+Reply packets. This can be used to reduce memory consumption on big
+NBMA subnets.
+.PP
+NOTE: currently does not do much as caching is not implemented.
+.RE
+
+.B shortcut-destination
+.RS
+This instructs
+.B opennhrp
+to reply with authorative answers on NHRP Resolution Requests destinied
+to addresses in this interface (instead of forwarding the packets). This
+effectively allows the creation of shortcut routes to subnets located
+on the interface.
+.PP
+When specified, this should be the only keyword for the interface.
+.RE
+
+.SH EXAMPLE
+The following configuration file was used for testing OpenNHRP on a machine
+with two ethernet network interfaces. GRE tunnel was configured with tunnel
+IP 10.255.255.2/24. Configuration enables registration to hub node at
+10.255.255.1 and resolution of other nodes in the subnet using that hub.
+.PP
+It also enables creation of shortcut routes to networks behind other
+hosts (with holding-time override for the defined shortcut-target)
+in our NBMA network and allows incoming shortcut routes.
+.PP
+.nf
+interface gre1
+  holding-time 3600
+  map 10.255.255.1/24 192.168.200.1 register
+  shortcut-target 172.16.0.0/16 holding-time 1800
+  cisco-authentication secret
+  shortcut
+  redirect
+  non-caching
+
+interface eth1
+  shortcut-destination
+
+.fi
+
+.SH "SEE ALSO"
+.BR opennhrp (8)
+
+.SH AUTHORS
+Timo Teras <timo.teras@iki.fi>
diff --git a/man/opennhrpctl.8 b/man/opennhrpctl.8
new file mode 100644
index 0000000..611c6f7
--- /dev/null
+++ b/man/opennhrpctl.8
@@ -0,0 +1,124 @@
+.TH OPENNHRP 8 "20 May 2009" "" "OpenNHRP Documentation"
+
+.SH NAME
+opennhrpctl \- opennhrp administrative control tool
+
+.SH SYNOPSIS
+.B opennhrpctl
+.BI "[\-a " admin\-socket "]" " command " "[" "arguments" "]..."
+
+.SH DESCRIPTION
+.B opennhrpctl
+is an utility to control
+.BR opennhrp (8)
+daemon operation. A UNIX socket is used for communication between
+.B opennhrpctl
+and
+.BR opennhrp (8).
+Administration priviledges for a non-root user can be granted by modifying
+the permissions and ownership of the socket.
+
+The following commands are available:
+
+.BI "[cache] show [" selector "]..."
+.RS
+Show contents of next hop cache (configured and resolved entries).
+.RE
+
+.BI "[cache] flush [" selector "]..."
+.RS
+Clear all non-permanent entries which match the selector specifiers.
+.RE
+
+.BI "[cache] purge [" selector "]..."
+.RS
+Purge entries from NHRP cache: cached entries are removed and permanent
+entries are forced down, up and finally reregistered.
+.RE
+
+.BI "[cache] lowerdown [" selector "]..."
+.RS
+Purge entries from NHRP cache with indication that lower layer failed:
+e.g. IPsec daemon detected dead-peer or received INITIIAL-CONTACT
+notification.
+.RE
+
+.BI "route show [" selector "]..."
+.RS
+Show the contents of locally cached kernel routing information
+(outbound routing base to do route lookups excluding active shortcut
+routes).
+.RE
+
+.B "interface show"
+.RS
+Show the contents of interface configuration table, and the cached information
+from kernel (like protocol and NBMA IP addresses in use currently).
+.RE
+
+.BI "redirect purge [" protocol-address "/" prefix-length "]"
+.RS
+Clear redirection cache from all entries matching the specified address.
+.RE
+
+.BI "update nbma " nbma-address " " protocol-address
+.RS
+This command can be used from
+.BR opennhrp-script "(8)"
+to inform
+.BR opennhrp
+daemon of the real
+.IR protocol-address
+of dynamically discovered NHS.
+.RE
+
+The following selectors can be used to limit which cache entries will
+be effected:
+
+.BI nbma " nbma-address"
+.RS
+Matches entries where the remote has NBMA address
+.IR nbma-address .
+.RE
+
+.BI protocol " protocol-address" "[/" "prefix-length" "]"
+.RS
+Matches entries where the remote has protocol address
+.IR protocol-address " with at least prefix length " prefix-length .
+.RE
+
+.BI local-nbma " nbma-address"
+.RS
+Matches entries from local interface which owns the NBMA address
+.IR nbma-address .
+.RE
+
+.BI local-protocol " protocol-address"
+.RS
+Matches entries only from local interface which owns the protocol address
+.IR protocol-address .
+.RE
+
+.BI interface " interface-name"
+.br
+.BI iface " interface-name"
+.br
+.BI dev " interface-name"
+.RS
+Search entries only from local interface with name
+.IR interface-name .
+.RE
+
+.RE
+
+.SH FILES
+.I /var/run/opennhrp.socket
+.RS
+.BR opennhrp "(8) control socket"
+.RE
+
+.SH "SEE ALSO"
+.BR opennhrp (8)
+
+.SH AUTHORS
+Timo Teras <timo.teras@iki.fi>