Merge pull request #10 from hamishcoleman/main

Documentation and example cli tool merging

Makefile

@@ -91,6 +91,7 @@ N2N_OBJS=\
 	src/sn_selection.o \
 	src/sn_utils.o \
 	src/speck.o \
+	src/test_hashing.o \
 	src/tf.o \
 	src/transform.o \
 	src/transform_aes.o \
@@ -133,6 +134,7 @@ BUILD_DEP:=\
 	shellcheck \
 	uncrustify \
 	yamllint \
+	jq \
 
 SUBDIRS+=tools
 SUBDIRS+=apps

README.md

@@ -1,18 +1,27 @@
-[![Build Status](https://travis-ci.org/ntop/n2n.png?branch=dev)](https://travis-ci.org/ntop/n2n)
 
+# n3n
 
-# n2n
+n3n is a light VPN software which makes it easy to create virtual networks
+bypassing intermediate firewalls.
 
-n2n is a light VPN software which makes it easy to create virtual networks bypassing intermediate firewalls.
+In order to start using n3n, two elements are required:
 
-In order to start using n2n, two elements are required:
-
-- A _supernode_: it allows edge nodes to announce and discover other nodes. It must have a port publicly accessible on internet.
+- A _supernode_: it allows edge nodes to announce and discover other nodes. It
+  must have a port publicly accessible on internet.
 - _edge_ nodes: the nodes which will be a part of the virtual networks
 
-A virtual network shared between multiple edge nodes in n2n is called a _community_. A single supernode can relay multiple communities and a single computer can be part of multiple communities at the same time. An encryption key can be used by the edge nodes to encrypt the packets within their community.
+A virtual network shared between multiple edge nodes in n3n is called a
+_community_. A single supernode can relay multiple communities and a single
+computer can be part of multiple communities at the same time. An encryption
+key can be used by the edge nodes to encrypt the packets within their
+community.
+
+n3n tries to establish a direct peer-to-peer connection via udp between the
+edge nodes when possible. When this is not possible (usually due to special NAT
+devices), the supernode is also used to relay the packets.
 
-n2n tries to establish a direct peer-to-peer connection via udp between the edge nodes when possible. When this is not possible (usually due to special NAT devices), the supernode is also used to relay the packets.
+n3n was originally based on an older n2n project and hopes to keep protocol
+compatiblilty with that.
 
 ## License
 
@@ -24,38 +33,51 @@ n2n tries to establish a direct peer-to-peer connection via udp between the edge
 
 ## Quick Setup
 
-Some Linux distributions already provide n2n as a package so a simple `sudo apt install n2n` will do the work. Alternatively, up-to-date packages for most distributions are available on [ntop repositories](http://packages.ntop.org/).
+Beward that while Debian (and those based on it) Linux distributions do appear
+to provide n2n as a package, it is based on an antique version and is not
+compatible with this.
+
+Alternatively, up-to-date packages for most distributions are available as
+part of the [latest release](https://github.com/n42n/n3n/releases/latest).
 
 On host1 run:
 
 ```sh
-$ sudo edge -c mynetwork -k mysecretpass -a 192.168.100.1 -f -l supernode.ntop.org:7777
+$ sudo edge -c mynetwork -k mysecretpass -a 192.168.100.1 -f -l supernode.ntop.org:7777 start
 ```
 
 On host2 run:
 
 ```sh
-$ sudo edge -c mynetwork -k mysecretpass -a 192.168.100.2 -f -l supernode.ntop.org:7777
+$ sudo edge -c mynetwork -k mysecretpass -a 192.168.100.2 -f -l supernode.ntop.org:7777 start
 ```
 
 Now the two hosts can ping each other.
 
-**IMPORTANT** It is strongly advised to choose a custom community name (`-c`) and a secret encryption key (`-k`) in order to prevent other users from connecting to your computer. For the privacy of your data sent and to reduce the server load of `supernode.ntop.org`, it is also suggested to set up a custom supernode as explained below.
+**IMPORTANT** It is strongly advised to choose a custom community name (`-c`)
+and a secret encryption key (`-k`) in order to prevent other users from
+connecting to your computer. For the privacy of your data sent and to reduce
+the server load of `supernode.ntop.org`, it is also suggested to set up a
+custom supernode as explained below.
 
 
 ## Setting up a Custom Supernode
 
-You can create your own infrastructure by setting up a supernode on a public server (e.g. a VPS). You just need to open a single port (1234 in the example below) on your firewall (usually `iptables`).
+You can create your own infrastructure by setting up a supernode on a public
+server (e.g. a VPS). You just need to open a single port (1234 in the example
+below) on your firewall (usually `iptables`).
 
-1. Install the n2n package
-2. Edit `/etc/n2n/supernode.conf` and add the following:
+1. Install the n3n package
+2. Edit `/etc/n3n/supernode.conf` and add the following:
    ```
    -p=1234
    ```
 3. Start the supernode service with `sudo systemctl start supernode`
 4. Optionally enable supernode start on boot: `sudo systemctl enable supernode`
 
-Now the supernode service should be up and running on port 1234. On your edge nodes you can now specify `-l your_supernode_ip:1234` to use it. All the edge nodes must use the same supernode.
+Now the supernode service should be up and running on port 1234. On your edge
+nodes you can now specify `-l your_supernode_ip:1234` to use it. All the edge
+nodes must use the same supernode.
 
 
 ## Manual Compilation
@@ -73,7 +95,13 @@ make install
 
 For Windows, MacOS, optimizations and general building options, please check out [Building documentation](doc/Building.md) for compilation and running.
 
-**IMPORTANT** It is generally recommended to use the [latest stable release](https://github.com/n42n/n3n/releases). Please note that the current _main_ branch usually is not guaranteed to be backward compatible neither with the latest stable release nor with previous _main_ states. On the other hand, if you dare to try bleeding edge features, you are encouraged to compile from _main_ – just keep track of sometimes rapidly occuring changes. Feedback in the _Issues_ section is appreciated.
+**IMPORTANT** It is generally recommended to use the [latest stable
+release](https://github.com/n42n/n3n/releases). Please note that the current
+_main_ branch usually is not guaranteed to be backward compatible neither with
+the latest stable release nor with previous _main_ states. On the other hand,
+if you dare to try bleeding edge features, you are encouraged to compile from
+_main_ – just keep track of sometimes rapidly occuring changes. Feedback in the
+_Issues_ section is appreciated.
 
 
 ## Security Considerations
@@ -87,8 +115,10 @@ AES encryption by default. Other ciphers can be chosen using the `-A_` option.
 
 A benchmark of the encryption methods is available when compiled from source with `tools/n2n-benchmark`.
 
-The header which contains some metadata like the virtual MAC address of the edge nodes, their IP address, their real 
-hostname and the community name optionally can be encrypted applying `-H` on the edges.
+The header which contains some metadata like the virtual MAC address of the
+edge nodes, their IP address, their real hostname and the community name
+optionally can be encrypted applying the `community.header_encryption=true`
+option to the edges.
 
 
 ## Advanced Configuration
@@ -116,4 +146,4 @@ Answers to frequently asked questions can be found in our [FAQ document](doc/Faq
 ---
 
 (C) 2007-22 - ntop.org and contributors
-Copyright (C) 2023 Hamish Coleman
+Copyright (C) 2023-24 Hamish Coleman