enoch/n2n
1
0
Fork 0
mirror of https://github.com/ntop/n2n.git synced 2024-09-19 16:41:11 +02:00
Code Issues Actions Packages Projects Releases 1 Wiki Activity

Move Build config docs into its own document (#928)

Browse Source
This commit is contained in:
Hamish Coleman 2022-01-10 22:23:37 +00:00 committed by GitHub
parent 4f568b03c1
commit 45520f3d24
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 148 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
doc/BuildConfig.md Normal file
View File

@ -0,0 +1,147 @@
# Configuration at Build time
There are a number of configuration options that are made only at build time.
In order to assist with cross compilation, minimising test cases, repeatable
builds and minimising externalities, the build options are generally defaulted
to off.
As part of simplifying cross compilation, the use of auto-detected
configuration settings are being removed.
## using Makefiles and Configure
### `--with-zstd`
Enable ZSTD compression
### `--with-openssl`
Use openssl instead of the built-int AES code
### `--with-edgex`
A legacy option intended to help cross compilation - if you use this option
please let us know as there are probably more modern options for
cross-compiling
### `--enable-pthread`
Enable threading using the pthread library
### `--enable-cap`
Use the libcap to provide reduction of the security privileges needed in the
running daemon
### `--enable-pcap`
If the pcap library is available then the `n2n-decode` tool can be compiled.
### `--enable-natpmp`
One of the two UPnP libraries, this one supports the NATPMP protocol.
See also the next option.
### `--enable-miniupnp`
Enables the other kind of UPnP port mapping protocol.
Turning on either of these two UPnP libraries will enable UPnP support within
the edge.
### Deprecation of --with options
Due to historical reasons, the autoconf system does not validate the syntax
of any `--with-X` style options, thus to provide the highest confidence in
the correctness of configuration and compilation, `--enable-X` style options
are preferred. As part of this, the older `--with-X` options will eventually
be migrated to use `--enable-X`
## CMake configuration
There are still some autodetected libraries in parts of the CMake build
system.
There are a number of OPTION statements in the CMakeLists.txt file that can
have their settings changed.
## Compiler Optimizations
The easiest way to boosting speed is by allowing the compiler to apply optimization 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 known risk in terms of instable code or so.
## Hardware Features
Some parts of the code significantly benefit from compiler optimizations (`-O3`) and platform features
such as NEON, SSE and AVX. It needs to be decided at compile-time. Hence if compiling for a specific
platform with known features (maybe the local one), it should be specified to the 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)
Random Numbers: RDSEED, RDRND (not faster but more random seed)
```
The compilations flags could easily be combined:
`./configure CFLAGS="-O3 -march=native"`.
There are reports of compile errors showing `n2n_seed': random_numbers.c:(.text+0x214): undefined reference to _rdseed64_step'` even though the CPU should support it, see #696. In this case, best solution found so far is to disable `RDSEED` support by adding `-U__RDSEED__` to the `CFLAGS`.
## OpenSSL Support
Some ciphers' speed can take advantage of OpenSSL support which is disabled by default as the built-in ciphers already prove reasonably fast in most cases. OpenSSL 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 commandline), n2n optionally supports [ZSTD](https://github.com/facebook/zstd). As of 2020, it is considered cutting edge and [praised](https://en.wikipedia.org/wiki/Zstandard) for reaching the currently technologically possible Pareto frontier in terms of CPU power versus compression ratio. ZSTD support can be configured using
`./configure --with-zstd`
which then will include ZSTD if found on the system. It will be available via `-z2` at the edges. Of course, it can be combined with the other features mentioned above:
`./configure --with-zstd --with-openssl CFLAGS="-O3 -march=native"`
Again, and this needs to be reiterated sufficiently often, please do no forget to `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 proved to be slower than the 64-bit scalar code on Raspberry Pi 3B+, see [here](https://github.com/ntop/n2n/issues/563).
Your specific ARM mileage may vary, so it can be enabled by configuring the definition of the `SPECK_ARM_NEON` macro:
`./configure CFLAGS="-DSPECK_ARM_NEON"`
Just make sure that the correct architecture is set, too. `-march=native` usually works quite well.
## Disable Multicast Local Peer Detection
For better local peer detection, the edges try to detect local peers by sending REGISTER
packets to a certain multicast address. Also, edges listen to this address to eventually
fetch such packets.
If these packets disturb network's peace or even get forwarded by (other) edges through the
n2n network, this behavior can be disabled, just add
`-DSKIP_MULTICAST_PEERS_DISCOVERY`
to your `CFLAGS` when configuring, e.g.
`./configure --with-zstd CFLAGS="-O3 -march=native -DSKIP_MULTICAST_PEERS_DISCOVERY"`

79
doc/Building.md
View File

@ -114,84 +114,7 @@ will be compatible.
# General Building Options
## Compiler Optimizations
The easiest way to boosting speed is by allowing the compiler to apply optimization 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 known risk in terms of instable code or so.
## Hardware Features
Some parts of the code significantly benefit from compiler optimizations (`-O3`) and platform features
such as NEON, SSE and AVX. It needs to be decided at compile-time. Hence if compiling for a specific
platform with known features (maybe the local one), it should be specified to the 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)
Random Numbers: RDSEED, RDRND (not faster but more random seed)
```
The compilations flags could easily be combined:
`./configure CFLAGS="-O3 -march=native"`.
There are reports of compile errors showing `n2n_seed': random_numbers.c:(.text+0x214): undefined reference to _rdseed64_step'` even though the CPU should support it, see #696. In this case, best solution found so far is to disable `RDSEED` support by adding `-U__RDSEED__` to the `CFLAGS`.
## OpenSSL Support
Some ciphers' speed can take advantage of OpenSSL support which is disabled by default as the built-in ciphers already prove reasonably fast in most cases. OpenSSL 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 commandline), n2n optionally supports [ZSTD](https://github.com/facebook/zstd). As of 2020, it is considered cutting edge and [praised](https://en.wikipedia.org/wiki/Zstandard) for reaching the currently technologically possible Pareto frontier in terms of CPU power versus compression ratio. ZSTD support can be configured using
`./configure --with-zstd`
which then will include ZSTD if found on the system. It will be available via `-z2` at the edges. Of course, it can be combined with the other features mentioned above:
`./configure --with-zstd --with-openssl CFLAGS="-O3 -march=native"`
Again, and this needs to be reiterated sufficiently often, please do no forget to `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 proved to be slower than the 64-bit scalar code on Raspberry Pi 3B+, see [here](https://github.com/ntop/n2n/issues/563).
Your specific ARM mileage may vary, so it can be enabled by configuring the definition of the `SPECK_ARM_NEON` macro:
`./configure CFLAGS="-DSPECK_ARM_NEON"`
Just make sure that the correct architecture is set, too. `-march=native` usually works quite well.
## Disable Multicast Local Peer Detection
For better local peer detection, the edges try to detect local peers by sending REGISTER
packets to a certain multicast address. Also, edges listen to this address to eventually
fetch such packets.
If these packets disturb network's peace or even get forwarded by (other) edges through the
n2n network, this behavior can be disabled, just add
`-DSKIP_MULTICAST_PEERS_DISCOVERY`
to your `CFLAGS` when configuring, e.g.
`./configure --with-zstd CFLAGS="-O3 -march=native -DSKIP_MULTICAST_PEERS_DISCOVERY"`
[Build time Configuration](BuildConfig.md)
# Cross compiling on Linux