"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/Building.md" between
n2n-3.0.tar.gz and n2n-3.1.1.tar.gz

About: n2n is a layer-two peer-to-peer virtual private network (VPN) which allows bypassing intermediate firewalls.
Pre-release.

Building.md  (n2n-3.0)	:	Building.md  (n2n-3.1.1)
# n2n on macOS		This document describes the process for compiling n2n in several different
		scenarios.
		There are some configuration options available during the build process,
		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/workf
		lows/tests.yml)
		# Git submodules
		If you are compiling with the UPnP libraries, it is possible that your
		operating system or your build system do not include binaries for the
		required libraries.
		Using these libraries can cause issues with some build systems, so be
		aware that not all combinations are supportable.
		To make this scenario simpler, the required source code has been added
		to this repository as git `submodules` which require one extra step to
		complete their checkout.
		So the very first time after cloning the n2n git repo, you should run
		this command in the n2n directory to fetch the submodules:
		```bash
		git submodule update --init --recursive
		```
		# Build on macOS
In order to use n2n on macOS, you first need to install support for TUN/TAP inte rfaces:		In order to use n2n on macOS, you first need to install support for TUN/TAP inte rfaces:
```bash		```bash
brew tap homebrew/cask		brew tap homebrew/cask
brew cask install tuntap		brew cask install tuntap
```		```
If you are on a modern version of macOS (i.e. Catalina), the commands above will ask you to enable the TUN/TAP kernel extension in System Preferences → Security & Privacy → General.		If you are on a modern version of macOS (i.e. Catalina), the commands above will ask you to enable the TUN/TAP kernel extension in System Preferences → Security & Privacy → General.
For more information refer to vendor documentation or the [Apple Technical Note] (https://developer.apple.com/library/content/technotes/tn2459/_index.html).		For more information refer to vendor documentation or the [Apple Technical Note] (https://developer.apple.com/library/content/technotes/tn2459/_index.html).
# Build on Windows (Visual Studio)		Note that on the newest MacOS versions and on Apple Silicon, there may be
		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 n2n versions.
## Requirements		# Build on Windows
In order to build on Windows the following tools should be installed:		The following document some possible windows compile recipes. Of them, the
		MinGW build process is more tested as it is more friendly to open source
		development.
- Visual Studio. For a minimal install, the command line only build tools can be		## Visual Studio
downloaded and installed from https://visualstudio.microsoft.com/downloads/#bu
ild-tools-for-visual-studio-2017.
- CMake		### Requirements
		In order to build with Vidual Studio on Windows the following tools should be in
		stalled:
- (optional) The OpenSSL library. Prebuild binaries can be downloaded from https		- Visual Studio. For a minimal install, the command line only build tools can be
://slproweb.com/products/Win32OpenSSL.html.		downloaded and installed from https://visualstudio.microsoft.com/downloads/#bu
The full version is required, i.e. not the "Light" version. The Win32 version		ild-tools-for-visual-studio-2017.
of it is usually required for a standard build.
> NOTE: In order to skip OpenSSL compilation, edit `CMakeLists.txt` and replace
**– is this still valid?**
>
> ```plaintext
> OPTION(N2N_OPTION_AES "USE AES" ON)
> with
> OPTION(N2N_OPTION_AES "USE AES" OFF)
> ```
NOTE: To statically link OpenSSL, add the `-DOPENSSL_USE_STATIC_LIBS=true` opt ion to the `cmake` command below.		- CMake (From https://cmake.org/download/)
- If compilation throws a "config.h: No such file or directory" error, an `inclu		NOTE: You should always use the official cmake stable release as otherwise
de/config.h` file needs to be obtained from an already configured Linux compilat		you may have issues finding libraries (e.g: the installed OpenSSL library).
ion and put into the `include/` directory as discussed [here](https://github.com		If you still have problems, you can try invoking it with `C:\Program Files\CMa
/ntop/n2n/issues/366).		ke\bin\cmake`.
In order to run n2n, you will need the following:		- (optional) The OpenSSL library. This optional library can be enabled as
		per the steps in the [Build time Configuration](BuildConfig.md)
- The TAP drivers should be installed into the system. They can be installed fro		Pre-built OpenSSL binaries can be downloaded from
m		https://slproweb.com/products/Win32OpenSSL.html.
http://build.openvpn.net/downloads/releases, search for "tap-windows".		The full version is required, i.e. not the "Light" version. The Win32
		version of it is usually required for a standard build.
- If OpenSSL has been linked dynamically, the corresponding `.dll` file should b		### CLI steps
e available
onto the target computer.
NOTE: Sticking to this tool chain has historically meant that resulting		In order to build from the command line, open a terminal window change to
executables are more likely to be able to communicate with Linux or other		the directory where the git checkout of this repository is and run the
OS builds, however efforts are being made to address this concern.		following commands:
## Build (CLI)		Building using `cmake` works as follows:
In order to build from the command line, open a terminal window and run the foll
owing commands:
```batch		```batch
md build		cmake -E make_directory build
cd build		cd build
		rem Append any options to the next line
cmake ..		cmake ..
MSBuild.exe edge.vcxproj /t:Build /p:Configuration=Release		cmake --build . --config Release
MSBuild.exe supernode.vcxproj /t:Build /p:Configuration=Release
MSBuild.exe n2n-benchmark.vcxproj /t:Build /p:Configuration=Release
```		```
NOTE: If CMake has problems finding the installed OpenSSL library, try to downlo
ad the official cmake and invoke it with
`C:\Program Files\CMake\bin\cmake`.
NOTE: Visual Studio might not add `MSBuild.exe`'s path to the environment variab
le %PATH% so you might have difficulties finding and executing it without giving
the full path. Regular installations seem to have it reside at `"C:\Program Fil
es (x86)\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin\MSBuild.exe
"`
The compiled `.exe` files should now be available in the `build\Release` directo ry.		The compiled `.exe` files should now be available in the `build\Release` directo ry.
## Run		## MinGW
The `edge.exe` program reads the `edge.conf` file located into the current direc
tory if no option is provided.
Here is an example `edge.conf` file:
```plaintext
-c=mycommunity
-k=mysecretpass
# supernode IP address
-l=1.2.3.4:5678
# edge IP address
-a=192.168.100.1
```
The `supernode.exe` program reads the `supernode.conf` file located into the cur
rent directory if no option is provided.
Here is an example `supernode.conf` file:
```plaintext
-p=5678
```
See `edge.exe --help` and `supernode.exe --help` for a full list of supported op
tions.
# Build on Windows (MinGW)
These steps were tested on a fresh install of Windows 10 Pro with all patches		These steps were tested on a fresh install of Windows 10 Pro with all patches
applied as of 2021-09-29.		applied as of 2021-09-29.
- Install Chocolatey (Following instructions on https://chocolatey.org/install)		- Install Chocolatey (Following instructions on https://chocolatey.org/install)
- from an admin cmd prompt		- from an admin cmd prompt
- choco install git mingw make		- `choco install git mingw make`
- All the remaining commands must be run from inside a bash shell ("C:\Program F iles\Git\usr\bin\bash.exe")		- All the remaining commands must be run from inside a bash shell ("C:\Program F iles\Git\usr\bin\bash.exe")
- git clone $THIS_REPO		- `git clone $THIS_REPO`
- cd n2n		- `cd n2n`
- ./scripts/hack_fakeautoconf.sh		- `./scripts/hack_fakeautoconf.sh`
- make		- `make`
- make test		- `make test`
		Due to limitations in the Windows environment, the normal autotools steps have
		been emulated by the `hack_fakeautoconf` - This currently results in the
		version number reported by the compiled software being inaccurate.
Due to the hack used to replace autotools on windows, any build created this		Note: MinGW builds have had a history of incompatibility reports with other OS
way will currently have inaccurate build version numbers.		builds (for example [#617](https://github.com/ntop/n2n/issues/617) and [#642](ht
		tps://github.com/ntop/n2n/issues/642))
Note: MinGW builds have a history of incompatibility reports with other OS
builds, please see [#617](https://github.com/ntop/n2n/issues/617) and [#642](htt
ps://github.com/ntop/n2n/issues/642).
However, if the tests pass, you should have a high confidence that your build		However, if the tests pass, you should have a high confidence that your build
will be compatible.		will be compatible.
# General Building Options		## Run on Windows
## Compiler Optimizations
The easiest way to boosting speed is by allowing the compiler to apply optimizat
ion to the code. To let the compiler know, the configuration process can take in
the optionally specified compiler flag `-O3`:
`./configure CFLAGS="-O3"`
The `tools/n2n-benchmark` tool reports speed-ups of 200% or more! There is no kn
own risk in terms of instable code or so.
## Hardware Features
Some parts of the code can be compiled to benefit from available hardware accele
ration. It needs to be decided at compile-time. So, if compiling for a specific
platform with known features (maybe the local one), it should be specified to th
e compiler, for example through the `-march=sandybridge` (you name it) or just `
-march=native` for local use.
So far, the following portions of n2n's code benefit from hardware features:
```
AES: AES-NI
ChaCha20: SSE2, SSSE3
SPECK: SSE2, SSSE3, AVX2, AVX512, (NEON)
Pearson Hashing: AES-NI
Random Numbers: RDSEED, RDRND (not faster but more random seed)
```
The compilations flags could easily be combined:
`./configure CFLAGS="-O3 -march=native"`.
## OpenSSL Support
Some ciphers' speed can take advantage of OpenSSL support which is disabled by d
efault as the built-in ciphers already prove reasonably fast in most cases. Open
SSL support can be configured using
`./configure --with-openssl`
which then will include OpenSSL 1.1 if found on the system. This can be combined
with the hardware support and compiler optimizations such as
`./configure --with-openssl CFLAGS="-O3 -march=native"`
Please do no forget to `make clean` after (re-)configuration and before building
(again) using `make`.
## ZSTD Compression Support
In addition to the built-in LZO1x for payload compression (`-z1` at the edge's c ommandline), n2n optionally supports [ZSTD](https://github.com/facebook/zstd). A s of 2020, it is considered cutting edge and [praised](https://en.wikipedia.org/ wiki/Zstandard) for reaching the currently technologically possible Pareto front ier in terms of CPU power versus compression ratio. ZSTD support can be configur ed using		In order to run n2n on Windows, you will need the following:
`./configure --with-zstd`		- The TAP drivers should be installed into the system. They can be installed fro
		m
which then will include ZSTD if found on the system. It will be available via `-		http://build.openvpn.net/downloads/releases, search for "tap-windows".
z2` at the edges. Of course, it can be combined with the other features mentione
d above:
`./configure --with-zstd --with-openssl CFLAGS="-O3 -march=native"`
Again, and this needs to be reiterated sufficiently often, please do no forget t
o `make clean` after (re-)configuration and before building (again) using `make`
.
## SPECK – ARM NEON Hardware Acceleration
By default, SPECK does not take advantage of ARM NEON hardware acceleration even
if compiled with `-march=native`. The reason is that the NEON implementation pr
oved to be slower than the 64-bit scalar code on Raspberry Pi 3B+, see [here](ht
tps://github.com/ntop/n2n/issues/563).
Your specific ARM mileage may vary, so it can be enabled by configuring the defi
nition of the `SPECK_ARM_NEON` macro:
`./configure CFLAGS="-DSPECK_ARM_NEON"`
Just make sure that the correct architecture is set, too. `-march=native` usuall
y works quite well.
## Disable Multicast Local Peer Detection
For better local peer detection, the edges try to detect local peers by sending		- If OpenSSL has been linked dynamically, the corresponding `.dll` file should b
REGISTER		e available
packets to a certain multicast address. Also, edges listen to this address to ev		onto the target computer.
entually
fetch such packets.
If these packets disturb network's peace or even get forwarded by (other) edges		The `edge.exe` program reads the `edge.conf` file located into the current direc
through the		tory if no option is provided.
n2n network, this behavior can be disabled, just add
`-DSKIP_MULTICAST_PEERS_DISCOVERY`		The `supernode.exe` program reads the `supernode.conf` file located into the cur rent directory if no option is provided.
to your `CFLAGS` when configuring, e.g.		Example [edge.conf](../packages/etc/n2n/edge.conf.sample)
		and [supernode.conf](../packages/etc/n2n/supernode.conf.sample) are available.
`./configure --with-zstd CFLAGS="-O3 -march=native -DSKIP_MULTICAST_PEERS_DISCOV ERY"`		See `edge.exe --help` and `supernode.exe --help` for a full list of supported op tions.
# Cross compiling on Linux		# Cross compiling on Linux
## Using the Makefiles and Autoconf		## Using the Makefiles and Autoconf
The Makefiles are all setup to allow cross compiling of this code. You		The Makefiles are all setup to allow cross compiling of this code. You
will need to have the cross compiler, binutils and any additional libraries		will need to have the cross compiler, binutils and any additional libraries
desired installed for the target architecture. Then you can run the `./configur e`		desired installed for the target architecture. Then you can run the `./configur e`
with the appropriate CC and AR environment and the right `--host` option.		with the appropriate CC and AR environment and the right `--host` option.
skipping to change at line 227		skipping to change at line 166
./configure --host $HOST_TRIPLET		./configure --host $HOST_TRIPLET
make		make
```		```
A good starting point to determine the host triplet for your destination platfor m		A good starting point to determine the host triplet for your destination platfor m
can be found by copying the `./config.guess` script to it and running it on the		can be found by copying the `./config.guess` script to it and running it on the
destination.		destination.
This is not a good way to produce binaries for embedded environments (like OpenW RT)		This is not a good way to produce binaries for embedded environments (like OpenW RT)
as they will often use a different libc environment.		as they will often use a different libc environment.
		# N2N Packages
		There are also some example package build recipes included with the source.
		- [Debian](../packages/debian/README)
		- [RPM](../packages/rpm)
		- [OpenWRT](../packages/openwrt/README.md)
End of changes. 31 change blocks.
189 lines changed or deleted		94 lines changed or added

---