n2n/README.md

129 lines
6.3 KiB
Markdown
Raw Normal View History

2020-07-29 11:07:57 +02:00
# n2n
2020-08-02 23:46:28 +02:00
n2n is a light VPN software which makes it easy to create virtual networks bypassing intermediate firewalls.
2019-06-21 01:37:57 +02:00
2020-07-29 11:07:57 +02:00
In order to start using n2n, two elements are required:
2016-10-23 10:46:15 +02:00
- A _supernode_: it allows edge nodes to announce and discover other nodes. It must have a port publicly accessible on internet.
2020-08-02 23:46:28 +02:00
- _edge_ nodes: the nodes which will be a part of the virtual networks
2016-10-23 10:46:15 +02:00
2020-08-02 23:46:28 +02:00
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.
2020-08-03 09:17:47 +02:00
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.
## Quick Setup
2019-06-21 01:37:57 +02:00
2020-08-02 23:46:28 +02:00
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/).
2016-10-23 10:46:15 +02:00
2019-06-21 00:40:49 +02:00
On host1 run:
2019-03-01 20:16:24 +01:00
2019-06-21 00:40:49 +02:00
```sh
$ sudo edge -c mynetwork -k mysecretpass -a 192.168.100.1 -f -l supernode.ntop.org:7777
```
2019-03-01 20:16:24 +01:00
2019-06-21 00:40:49 +02:00
On host2 run:
2016-10-25 16:30:04 +02:00
2019-06-21 00:40:49 +02:00
```sh
$ sudo edge -c mynetwork -k mysecretpass -a 192.168.100.2 -f -l supernode.ntop.org:7777
```
2016-10-23 10:46:15 +02:00
2019-06-21 00:40:49 +02:00
Now the two hosts can ping each other.
2016-10-23 10:46:15 +02:00
2020-08-03 09:17:47 +02:00
**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.
2016-10-25 16:30:04 +02:00
2020-07-29 11:07:57 +02:00
## 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 n2n package
2. Edit `/etc/n2n/supernode.conf` and add the following:
```
-l=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.
## Manual Compilation
2016-10-23 10:46:15 +02:00
2019-06-21 00:40:49 +02:00
On linux, compilation from source is straight forward:
2016-10-23 10:46:15 +02:00
2019-06-21 00:40:49 +02:00
```sh
./autogen.sh
./configure
make
2016-10-23 10:46:15 +02:00
2019-06-21 00:40:49 +02:00
# optionally install
make install
```
2016-10-23 10:46:15 +02:00
2020-08-02 23:46:28 +02:00
Some parts of the code significantly benefit from compiler optimizations and platform features such as NEON, SSE and AVX. To enable, use `./configure CFLAGS="-O3 -march=native"` for configuration instead of `./configure`.
2020-06-24 12:32:25 +02:00
2020-08-15 22:04:49 +02:00
For Windows, MacOS and general building options, please check out [Building.md](doc/Building.md) for compilation and running.
2016-10-23 10:46:15 +02:00
2020-08-19 16:42:13 +02:00
**IMPORTANT** It is generally recommended to use the [latest stable release](https://github.com/ntop/n2n/releases). Please note that the current _dev_ branch usually is not guaranteed to be backward compatible neither with the latest stable release nor with previous _dev_ states. On the other hand, if you dare to try the bleeding edge features, you are encouraged to compile from _dev_ just keep track of sometimes rapidly occuring changes. Feedback in the _Issues_ section is appreciated.
2020-07-29 11:07:57 +02:00
## Running edge as a Service
2016-10-23 10:46:15 +02:00
edge can also be run as a service instead of cli:
2016-10-23 10:46:15 +02:00
2019-08-08 18:10:37 +02:00
1. Edit `/etc/n2n/edge.conf` with your custom options. See `/etc/n2n/edge.conf.sample`.
2. Start the service: `sudo systemctl start edge`
3. Optionally enable edge start on boot: `sudo systemctl enable edge`
2016-10-23 10:46:15 +02:00
2019-08-08 18:10:37 +02:00
You can run multiple edge service instances by creating `/etc/n2n/edge-instance1.conf` and
starting it with `sudo systemctl start edge@instance1`.
2016-10-23 10:46:15 +02:00
2020-07-29 11:07:57 +02:00
## Security Considerations
2019-06-21 01:37:57 +02:00
2020-07-29 11:07:57 +02:00
When payload encryption is enabled (provide a key using `-k`), the supernode will not be able to decrypt
2020-08-02 23:46:28 +02:00
the traffic exchanged between two edge nodes but it will know that edge A is talking with edge B.
2019-06-21 01:37:57 +02:00
2020-07-29 11:07:57 +02:00
The choice of encryption schemes that can be applied to payload has recently been enhanced. Please have
2020-08-02 23:46:28 +02:00
a look at [Crypto.md](doc/Crypto.md) for a quick comparison chart to help make a choice. n2n edge nodes use
2020-07-29 11:07:57 +02:00
Twofish encryption by default for compatibility reasons with existing versions. Other ciphers can be chosen
using the `-A_` option.
2016-10-23 10:46:15 +02:00
2019-09-21 16:12:43 +02:00
A benchmark of the encryption methods is available when compiled from source with `tools/n2n-benchmark`.
2016-10-23 10:46:15 +02:00
2020-07-29 11:07:57 +02:00
The header which contains some metadata like the virtual MAC address of the edge nodes, their IP address
and the community name optionally can be encrypted applying `-H` on the edges.
2020-06-24 12:25:00 +02:00
2020-07-29 11:19:12 +02:00
## Routing the Traffic
2020-07-29 14:16:46 +02:00
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 (`-n`). Details can be found in the [Routing.md](doc/Routing.md) document.
2020-07-29 11:19:12 +02:00
## IPv6 Support
n2n can tunnel IPv6 traffic into the virtual network but does not support
IPv6 for edge-to-supernode communication yet.
2020-08-02 23:46:28 +02:00
Have a look at [IPv6.md](https://github.com/ntop/n2n/blob/dev/doc/IPv6.md) for more information.
2020-07-29 11:19:12 +02:00
## Contribution
2016-10-23 10:46:15 +02:00
You can contribute to n2n in various ways:
- Update an [open issue](https://github.com/ntop/n2n/issues) or create a new one with detailed information
- Propose new features
- Improve the documentation
- Provide pull requests with enhancements
2019-06-21 00:40:49 +02:00
For details about the internals of n2n check out [Hacking guide](https://github.com/ntop/n2n/blob/dev/doc/Hacking.md).
2016-10-23 10:48:17 +02:00
2020-08-27 14:40:49 +02:00
## Further Readings and Related Projects
2020-08-27 14:42:21 +02:00
Answers to frequently asked questions can be found in our [FAQ document](https://github.com/ntop/n2n/blob/dev/doc/Faq.md).
2020-08-27 14:40:49 +02:00
Here is a list of third-party projects connected to this repository:
- Collection of pre-built binaries for Windows: [lucktu](https://github.com/lucktu/n2n)
- 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/)
---
2020-06-24 12:25:00 +02:00
(C) 2007-2020 - ntop.org and contributors