Simplify README and improve build docs

.github/workflows/tests.yml

@@ -355,6 +355,7 @@
   package_ipk:
     name: Package for OpenWrt
     runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
 
     strategy:
       fail-fast: true
@@ -362,13 +363,13 @@
         include:
           - name: mips_24kc
             sdk_ver: 22.03.3
             sdk: https://downloads.openwrt.org/releases/22.03.3/targets/lantiq/xrx200/openwrt-sdk-22.03.3-lantiq-xrx200_gcc-11.2.0_musl.Linux-x86_64.tar.xz
           - name: i386_pentium4
             sdk_ver: 22.03.3
             sdk: https://downloads.openwrt.org/releases/22.03.3/targets/x86/generic/openwrt-sdk-22.03.3-x86-generic_gcc-11.2.0_musl.Linux-x86_64.tar.xz
           - name: x86_64
             sdk_ver: 22.03.3
             sdk: https://downloads.openwrt.org/releases/22.03.3/targets/x86/64/openwrt-sdk-22.03.3-x86-64_gcc-11.2.0_musl.Linux-x86_64.tar.xz
 
     defaults:
       run:
@@ -401,6 +402,14 @@
           git fetch --force --tags
         working-directory: n3n
 
+      - name: Set environment for OpenWRT
+        run: |
+          echo "BUILD_VERSION=$(scripts/version.sh)" >> "$GITHUB_ENV"
+          echo "BUILD_SOURCE_URL=https://github.com/${{github.repository}}" >> "$GITHUB_ENV"
+          echo "BUILD_SOURCE_REF=$GITHUB_REF" >> "$GITHUB_ENV"
+          cat "$GITHUB_ENV"
+        working-directory: n3n
+
       - name: Copy package definition into openwrt
         run: |
           cp -r n3n/packages/openwrt openwrt/package/n3n
@@ -412,10 +421,8 @@
 
       - name: Build openwrt packages
         run: |
-          export BUILD_VERSION=$(../n3n/scripts/version.sh)
-          export BUILD_SOURCE_URL=https://github.com/${{github.repository}}
-          export BUILD_SOURCE_REF=$GITHUB_REF
-          echo "Build for $PKG_VERSION"
+          echo "Build for $BUILD_VERSION"
+          export
           make package/n3n/clean V=s
           make package/n3n/prepare USE_SOURCE_DIR=$GITHUB_WORKSPACE/n3n V=s
           make package/n3n/compile V=s

Makefile

@@ -353,9 +353,14 @@ distclean:
 
 # A quick way to generate a dpkg from a checkout.
 #
+[email protected]
+DEBFULLNAME?="Auto Build"
+export DEBEMAIL
+export DEBFULLNAME
 .PHONY: dpkg
 dpkg:
-	[email protected] dch -v ${VERSION}-1 --no-auto-nmu local package Auto Build
+	rm -f debian/changelog
+	dch --create --empty --package n3n -v ${VERSION}-1 --no-auto-nmu local package Auto Build
 	env -u CFLAGS dpkg-buildpackage -rfakeroot -d -us -uc --host-type ${CONFIG_HOST}
 
 .PHONY: install.bin

README.md

@@ -1,8 +1,7 @@
 
 # n3n
 
-n3n is a light VPN software which makes it easy to create virtual networks
-bypassing intermediate firewalls.
+n3n is a lightweight Peer-to-Peer VPN that creates virtual networks.
 
 In order to start using n3n, two elements are required:
 
@@ -12,9 +11,9 @@ In order to start using n3n, two elements are required:
 
 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.
+computer can be part of multiple communities at the same time (by running
+multiple _edge_ daemons). 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
@@ -23,6 +22,12 @@ 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.
 
+Note that some distributions have very old versions of n2n packaged that are
+incompatible with the protocol used by n3n.  At the least, Debian has a n2n
+version 1.3.1 which uses a protocol from 2008 and has not been compatible with
+the stable releases of n2n for many years - thus will definitely not
+interoperate with n3n)
+
 ## License
 
 - Any new self-contained tools or modules are licensed GPL-2.0-only.
@@ -31,124 +36,41 @@ compatiblilty with that.
 - There is no Contributor Licence Agreement and thus there is no single body
   that can take ownership of the code and/or change the licensing.
 
-## Quick Setup
+## Quick Start
 
-Up-to-date binaries and packages for most distributions are available as
-part of the [latest stable release](https://github.com/n42n/n3n/releases/latest).
+For Debian, Ubuntu or similar dpkg based systems:
 
-(Since the n3n is protocol compatible with the older n2n, you might be tempted
-to try and install a package provided by your distribution.  At the least
-Debian has a package called `n2n`, however it is based on the antique 1.2
-version from 2008 and that has not been compatible with n2n for many years, and
-thus is also not able to interoperate with n3n.)
+- Download the package from the [latest stable release](https://github.com/n42n/n3n/releases/latest).
 
-On host1 run:
+- Install the package
 
-```sh
-$ sudo edge start \
-    -c mynetwork \
-    -k mysecretpass \
-    -a 192.168.100.1 \
-    -l supernode.ntop.org:7777
-```
+- Create a config file - `/etc/n3n/mynetwork.conf` containing
+  ```
+  [community]
+  name=mynetwork
+  key=mypassword
+  supernode=supernode.ntop.org:7777
+  ```
 
-On host2 run:
+- Start the service: `sudo systemctl start n3n-edge@mynetwork`
 
-```sh
-$ sudo edge start \
-    -c mynetwork \
-    -k mysecretpass \
-    -a 192.168.100.2 \
-    -l supernode.ntop.org:7777
-```
+- Check the connection: `sudo n3nctl -s mynetwork supernodes`
 
-Now the two hosts can ping each other.  For a longer-term setup, we suggest
-you use a config file with the settings.
+- List other nodes found: `sudo n3nctl -s mynetwork edges`
 
-**IMPORTANT** It is strongly advised to choose a custom community name (the
+**IMPORTANT:** It is strongly advised to choose a custom community name (the
 `community.name` option) and a secret encryption key (the `community.key`
-option) 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`).
-
-1. Install the n3n package
-2. Edit `/etc/n3n/supernode.conf` and add the following:
-   ```
-   [connection]
-   bind=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 (or be part of the same
-[supernode federation](doc/Federation.md))
-
-
-## Manual Compilation
-
-On Linux, compilation from source is straight forward:
-
-```sh
-./autogen.sh
-./configure
-make
-
-# optionally install
-make install
-```
-
-For compiling under Windows or MacOS, enabling various optimizations and
-generally other options available to build, please check the [Building
-documentation](doc/Building.md)
+option) in order to prevent other users from connecting to your computer.
 
-The project _main_ branch is used for development work and reflects the code
-that is expected to go into the next release - it is thus possible that it
-has not been fully tested and may contain bugs or partially implemented
-features.  If you wish to help with testing or to implement a new feature, you
-are encouraged to compile from _main_.  Feedback in the _issues_ tracker is
-appreciated.
+It is also suggested that you setup your own [supernode](doc/Supernode.md)
 
-Once a release is stable, it will be tagged - and if a bug fix needs to be
-backported to a stable release a branch will be created for the patch releases
-containing these backported patches.
-
-
-## Security Considerations
-
-When payload encryption is enabled (provide a key using `community.key`), the
-supernode will not be able to decrypt the traffic exchanged between two edge
-nodes but it will know that edge A is talking with edge B.
-
-There are multiple encryption options to choose from. Please have a look at
-[Crypto description](doc/Crypto.md) for a quick comparison chart to help make a
-choice. n3n edge nodes use AES encryption by default. Other ciphers can be
-chosen using the `community.cipher` option.
-
-A benchmark of the encryption methods is available when compiled from source
-with `tools/n3n-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 the `community.header_encryption=true`
-option to the edges.
-
-
-## Advanced Configuration
-
-More information about communities, support for multiple supernodes, routing,
-traffic restrictions and on how to run an edge as a service is available in the
-[more detailed documentation](doc/Advanced.md).
+# See Also
 
+- [Build from Source](doc/Building.md) document.
+- [Security Considerations](doc/Security.md) document.
+- [Advanced Configuration](doc/Advanced.md) document.
+- Answers to [frequently asked questions](doc/Faq.md) (FAQ).
+- Details about the internals in the [Hacking guide](doc/Hacking.md).
 
 ## Contribution
 
@@ -160,14 +82,6 @@ You can contribute to n3n in various ways:
 - Improve the documentation
 - Provide pull requests with enhancements
 
-For details about the internals of n3n check out the [Hacking
-guide](doc/Hacking.md).
-
-
-## Further Readings and Related Projects
-
-Answers to frequently asked questions can be found in our [FAQ
-document](doc/Faq.md).
 
 ---
 

doc/Advanced.md

@@ -1,5 +1,7 @@
 # Advanced Configuration
 
+This document describes information about communities, support for multiple
+supernodes, routing, traffic restrictions and how to run an edge as a service.
 
 ## Configuration Files
 

doc/Building.md

@@ -10,6 +10,17 @@ which are documented in the [Build time Configuration](BuildConfig.md) page.
 Also of use are the steps used for the automated Continuous Integration
 process, which can be found in the [Github actions config file](../.github/workflows/tests.yml)
 
+The project _main_ branch is used for development work and reflects the code
+that is expected to go into the next release - it is thus possible that it
+has not been fully tested and may contain bugs or partially implemented
+features.  If you wish to help with testing or to implement a new feature, you
+are encouraged to compile from _main_.  Feedback in the _issues_ tracker is
+appreciated.
+
+Once a release is stable, it will be tagged - and if a bug fix needs to be
+backported to a stable release a branch will be created for the patch releases
+containing these backported patches.
+
 # Git submodules
 
 If you are compiling with the UPnP features enabled, it is possible that your
@@ -33,16 +44,38 @@ libraries.  Additionally, upstream changes are needed to libpmp to allow
 it to build properly with GCC on Windows at all.  These are issues that
 should be fixed in a future release.
 
-So the very first time after cloning the n3n git repo, you should run
-this command in the n3n directory to fetch the submodules:
+If you will be using these features, the simplest thing to do is the very first
+time after cloning the n3n git repo, you should run this command in the n3n
+directory to fetch the submodules:
 
 ```bash
 git submodule update --init --recursive
 ```
 
+# Build on Linux / Generic build instructions
+
+On a system with standard posix tools and development libraries, the
+compilation from source is straight forward:
+
+```sh
+./autogen.sh
+./configure
+make
+
+# optionally install
+make install
+```
+
 # Build on macOS
 
-In order to use n3n on macOS, you first need to install support for TUN/TAP interfaces:
+The macOS build essentially can use the generic build instructions (Above),
+but first needs a couple of other packages installed:
+
+```bash
+brew install automake
+```
+
+Then install support for TUN/TAP interfaces:
 
 ```bash
 brew tap homebrew/cask
@@ -58,6 +91,46 @@ increasing security restrictions in the OS that make installing the TUN/TAP
 kernel extension difficult.  Alternative software implementations to avoid
 these difficulties are being discussed for future n3n versions.
 
+# Build on BSD
+
+## FreeBSD
+
+This essentially is using the generic build instructions (Above), with a
+couple of required packages installed:
+
+```bash
+sudo pkg install -y \
+  autoconf \
+  automake \
+  git-tiny \
+  gmake \
+  python3 \
+  jq \
+  bash
+./autogen.sh
+./configure CC=clang
+gmake all
+```
+
+## OpenBSD
+
+Again, this is basically the generic build instructions, with some extra
+OS packages:
+
+```bash
+sudo pkg_add \
+  autoconf-2.71 \
+  automake-1.16.5 \
+  git \
+  gmake \
+  python3 \
+  jq \
+  bash
+AUTOCONF_VERSION=2.71 AUTOMAKE_VERSION=1.16 ./autogen.sh
+./configure CC=clang
+gmake all
+```
+
 # Build on Windows
 
 The following document one possible windows compile recipe.  The reason
@@ -134,7 +207,7 @@ running it on the destination.
 This is not a good way to produce binaries for embedded environments (like OpenWRT)
 as they will often use a different libc environment.
 
-# N2N Packages
+# Building N3N Packages
 
 There are also some example package build recipes included with the source.
 

doc/Faq.md

@@ -5,7 +5,15 @@
 
 ### Where can I find binaries for Windows?
 
-We do not explicitly release Windows binaries, but the automated test workflow creates them. You can find the the most current binaries at the _Actions_ tab, at the _Testing_ workflow, select the newest run, scroll down to the _Artifacts_ sections where the _binaries_ file contains the Windows binaries in its `/x86_64-pc-mingw64/usr/sbin/` folder.
+We do not have a Windows package, but EXE files for modern Windows can be
+found as part of the latest release.
+
+If you want to use with Windows XP - eg, for retro gaming - those binaries
+are not part of the standard release package.  The automated test workflow
+does create them and they can be downloaded from the _Actions_ tab, at the
+_Testing_ workflow, select the newest run, scroll down to the _Artifacts_
+sections where the _binaries_ file contains the Windows binaries in its
+`i686-w64-mingw32/usr/local/sbin/` folder.
 
 ## Supernode