updated documentation (#1010)

README.md

@@ -112,6 +112,7 @@ Here is a list of third-party projects connected to this repository:
 - n2n for Android: [hin2n](https://github.com/switch-iot/hin2n)
 - Docker images: [Docker Hub](https://hub.docker.com/r/supermock/supernode/)
 - Go bindings, management daemons and CLIs for n2n edges and supernodes, Docker, Kubernetes & Helm Charts: [pojntfx/gon2n](https://pojntfx.github.io/gon2n/)
+- Windows GUI (along with a custom version of n2n) but also working with regular n2n: [HappyNet](https://github.com/happynclient/happynwindows)
 
 ---
 

doc/Advanced.md

@@ -33,7 +33,7 @@ The [TAP Configuration Guide](TapConfiguration.md) contains hints on various set
 
 ## Routing the Traffic
 
-Reaching a remote network or tunneling all the internet traffic via n2n are two common tasks which require a proper routing setup. n2n supports routing needs providing options for packet forwarding (`-r`) including broadcasts (`-E`) as well as temporarily modifying the routing table (`tools/n2n-route`). Details can be found in the [Routing document](Routing.md).
+Reaching a remote network or tunneling all the internet traffic via n2n are two common tasks which require a proper routing setup. n2n supports routing needs by temporarily modifying the routing table (`tools/n2n-route`). Details can be found in the [Routing document](Routing.md).
 
 
 ## Traffic Restrictions

doc/BuildConfig.md

@@ -96,9 +96,7 @@ this is `apt-get install libnatpmp-dev`
 Enables the other kind of UPnP port mapping protocol.
 
 Turning on either of these two UPnP libraries will enable UPnP support within
-the edge.
+the n2n-portfwd tool.
-
-Both the natpmp and miniupnp depend on the pthread library being enabled.
 
 This option depends on the library being installed - on Debian and Ubuntu,
 this is `apt-get install libminiupnpc-dev`

doc/Routing.md

@@ -19,7 +19,7 @@ On the client side, the easiest way to configure routing is via the `tools/n2n-r
 
 10.0.0.1 is the IP address of the gateway to use to route the specified network. It should correspond to the IP address of the `server` within n2n. Multiple `-n` options can be specified.
 
-The utility connects to the local edge's management port to receive information about peers and supernodes. It currently works on Linux only.
+The utility connects to the local edge's management port to receive information about peers and supernodes. It currently works on Linux only but certainly can be ported to other OS (the route handling code is quite OS dependant).
 
 As an alternative to the `tools/n2n-route` utility, the `ip route` linux command can be manually used. See the [n2n-gateway.sh](scripts/n2n-gateway.sh) script for an example. See also the following description of other use cases and in depth explanation.
 

doc/Scratchpad.md

@@ -28,7 +28,8 @@ rpmbuild -bb ./n2n.spec
 ### New Features
 
 - Enhanced management port JSON interface to let n2n interact with external tools
-- Added UPnP and PMP support at edge
+- Added `n2n-route` tool (Linux only so far)
+- Introduced `n2n-portfwd` tool to support UPnP and PMP port forwarding
 - Furthered the build system
 
 ### Improvements

doc/Tools.md

@@ -0,0 +1,84 @@
+# Tools
+
+There are a number of handy tools coming with n2n extending fumction and
+user experience or just prove helpful during build and development.
+
+All tools can be found in the `tools` directory.
+
+## End User Tools
+
+### `n2n-benchmark`
+
+This C tool has n2n's basic transforms (the ciphers, compression, hash)
+crunch a test packet and outputs the measured throughput. You might observe
+differences depending on compiler optimizations or enabled hardware support,
+see [build configuration](BuildConfig.md).
+
+Example:
+- `tools/n2n-benchmark`
+
+### `n2n-route`
+
+This C tool sets new routes for all the traffic to be routed via a VPN gateway
+(another edge) and polls the management port of a local n2n edge for adding
+appropriate routes to supernodes and peers via the original default gateway.
+
+The tool can auto-detect the default gateway and also has options to only route
+traffic to specified networks through the VPN gateway.
+
+Make sure to run with sufficient rights to let the tool add and delete routes.
+
+More general information can be found in the [routing document](Routing.md)
+including hints how to setup the remote edge (IP routing, masquerading).
+
+Example:
+- `tools/n2n-route <remote edge address>`
+- `tools/n2n-route -n 10.10.10.0/24 <remote edge address>`
+- `tools/n2n-route -n 8.8.8.8/32 <remote edge address>`
+
+### `n2n-portfwd`
+
+This C tool uses UPnP and/or PMP to have a local router forward the edge port.
+The program polls a local edge's management port and takes apporpriate action.
+
+Note that n2n needs to be compiled with the corresponding options enabled, e.g.
+
+```
+./configure --enable-miniupnp --enable-natpmp
+```
+
+or
+
+```
+`cmake -DN2N_OPTION_USE_PORTMAPPING=ON`
+
+```
+
+Also see [build configuration](BuildConfig.md).
+
+Example:
+- `tools/n2n-portfwd`
+
+
+## Build and Development Tools
+
+### `tests-*`
+
+These C programs run certain parts of n2n with pre-defined data and output
+the results. The expected results can be found in the `tests/` directory
+following the `tests-*.expected` naming scheme.
+
+The `test_*` [scripts](Scripts.md) residing inside the `scripts/` directory
+compare test output and expected results to quickly show deviations, helpful
+when on bug hunt.
+
+Example:
+- `tools/tests-transforms`
+
+### `n2n-decode`
+
+This C tool intends to decrypt captured n2n traffic when all keys are provided.
+Its development unfortunately did not follow main n2n's pace after version 2.8 
+and thus is not up to date.
+
+Contributions to help lifting it to match version 3.x traffic are very welcome.