extern/netbird
1
0
Fork 0
mirror of https://github.com/netbirdio/netbird.git synced 2025-06-20 09:47:49 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README (#96)

Browse Source 
* docs: update README
This commit is contained in:
Mikhail Bragin 2021-08-25 15:40:51 +02:00 committed by GitHub
parent 49800a6d03
commit 737866c149
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 43 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
README.md
View File

@ -7,26 +7,31 @@ A WireGuard®-based mesh network that connects your devices into a single privat
### Why using Wiretrustee? ### Why using Wiretrustee?
* Connect multiple devices to each other via a secure peer-to-peer Wireguard VPN tunnel. At home, the office, or anywhere else. * Connect multiple devices to each other via a secure peer-to-peer Wireguard VPN tunnel. At home, the office, or anywhere else.
* No need to open ports and expose public IPs on the device. * No need to open ports and expose public IPs on the device, routers etc.
* Uses Kernel Wireguard module if available.
* Automatic network change detection. When a new peer joins the network others are notified and keys are exchanged automatically.
* Automatically reconnects in case of network failures or switches. * Automatically reconnects in case of network failures or switches.
* Automatic NAT traversal. * Automatic NAT traversal.
* Relay server fallback in case of an unsuccessful peer-to-peer connection. * Relay server fallback in case of an unsuccessful peer-to-peer connection.
* Private key never leaves your device. * Private key never leaves your device.
* Automatic IP address management.
* Intuitive UI Dashboard.
* Works on ARM devices (e.g. Raspberry Pi). * Works on ARM devices (e.g. Raspberry Pi).
* Open-source (including Management Service)
### Secure peer-to-peer VPN in minutes
![animation](media/peers.gif)
### A bit on Wiretrustee internals ### A bit on Wiretrustee internals
* Wiretrustee features a Management Service that offers peer IP management and network updates distribution (e.g. when new peer joins the network).
* Wiretrustee uses WebRTC ICE implemented in [pion/ice library](https://github.com/pion/ice) to discover connection candidates when establishing a peer-to-peer connection between devices. * Wiretrustee uses WebRTC ICE implemented in [pion/ice library](https://github.com/pion/ice) to discover connection candidates when establishing a peer-to-peer connection between devices.
* A connection session negotiation between peers is achieved with the Wiretrustee Signalling server [signal](signal/) * Peers negotiate connection through [Signal Service](signal/).
* Contents of the messages sent between peers through the signaling server are encrypted with Wireguard keys, making it impossible to inspect them. * Signal Service uses public Wireguard keys to route messages between peers.
The routing of the messages on a Signalling server is based on public Wireguard keys. Contents of the messages sent between peers through the signaling server are encrypted with Wireguard keys, making it impossible to inspect them.
* Occasionally, the NAT-traversal is unsuccessful due to strict NATs (e.g. mobile carrier-grade NAT). * Occasionally, the NAT-traversal is unsuccessful due to strict NATs (e.g. mobile carrier-grade NAT).
For that matter, there is support for a relay server fallback (TURN) and a secure Wireguard tunnel is established via TURN server. When this occurs the system falls back to relay server (TURN), and a secure Wireguard tunnel is established via TURN server.
[Coturn](https://github.com/coturn/coturn) is the one that has been successfully used for STUN and TURN in Wiretrustee setups. [Coturn](https://github.com/coturn/coturn) is the one that has been successfully used for STUN and TURN in Wiretrustee setups.
### What Wiretrustee is not doing:
* Wireguard key management. In consequence, you need to generate peer keys and specify them on Wiretrustee initialization step. This feature is on the roadmap.
* Peer address management. You have to specify a unique peer local address (e.g. 10.30.30.1/24) when configuring Wiretrustee. This feature is on the roadmap.
### Product Roadmap ### Product Roadmap
- [Public Roadmap](https://github.com/wiretrustee/wiretrustee/projects/2) - [Public Roadmap](https://github.com/wiretrustee/wiretrustee/projects/2)
- [Public Roadmap Progress Tracking](https://github.com/wiretrustee/wiretrustee/projects/1) - [Public Roadmap Progress Tracking](https://github.com/wiretrustee/wiretrustee/projects/1)
@ -88,50 +93,31 @@ cd C:\path\to\wiretrustee\bin
```` ````
### Client Configuration ### Client Configuration
1. Initialize Wiretrustee: 1. Login to the Management Service. You need to have a `setup key` in hand (see ).
For **Unix** systems: For **Unix** systems:
```shell ```shell
sudo wiretrustee init \ sudo wiretrustee login --setup-key <SETUP KEY>
--stunURLs stun:stun.wiretrustee.com:3468,stun:stun.l.google.com:19302 \
--turnURLs <TURN User>:<TURN password>@turn:stun.wiretrustee.com:3468 \
--signalAddr signal.wiretrustee.com:10000 \
--wgLocalAddr 10.30.30.1/24 \
--log-level info
``` ```
For **Windows** systems: For **Windows** systems:
```shell ```shell
.\wiretrustee.exe init ` .\wiretrustee.exe login --setup-key <SETUP KEY>
--stunURLs stun:stun.wiretrustee.com:3468,stun:stun.l.google.com:19302 `
--turnURLs <TURN User>:<TURN password>@turn:stun.wiretrustee.com:3468 `
--signalAddr signal.wiretrustee.com:10000 `
--wgLocalAddr 10.30.30.1/24 `
--log-level info
``` ```
It is important to mention that the ```wgLocalAddr``` parameter has to be unique across your network. Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
E.g. if you have Peer A with ```wgLocalAddr=10.30.30.1/24``` then another Peer B can have ```wgLocalAddr=10.30.30.2/24```
If for some reason, you already have a generated Wireguard key, you can specify it with the ```--wgKey``` parameter.
If not specified, then a new one will be generated, and its corresponding public key will be output to the log.
A new config will be generated and stored under ```/etc/wiretrustee/config.json```
2. Add a peer to connect to.
For **Unix** systems:
```shell ```shell
sudo wiretrustee add-peer --allowedIPs 10.30.30.2/32 --key '<REMOTE PEER WIREUARD PUBLIC KEY>' sudo wiretrustee login --setup-key <SETUP KEY> --management-url https://localhost:33073
``` ```
For **Windows** systems:
```shell You could also omit `--setup-key` property. In this case the tool will prompt it the key.
.\wiretrustee.exe add-peer --allowedIPs 10.30.30.2/32 --key '<REMOTE PEER WIREUARD PUBLIC KEY>'
``` 2. Start Wiretrustee:
3. Restart Wiretrustee to reload changes
For **MACOS** you will just start the service: For **MACOS** you will just start the service:
````shell ````shell
sudo wiretrustee up --log-level info sudo wiretrustee up
# or # or
sudo wiretrustee up --log-level info & # to run it in background sudo wiretrustee up & # to run it in background
```` ````
For **Linux** systems: For **Linux** systems:
```shell ```shell
@ -144,6 +130,22 @@ For **Windows** systems:
``` ```
> You may need to run Powershell as Administrator > You may need to run Powershell as Administrator
3. Check your IP:
For **MACOS** you will just start the service:
````shell
sudo ipconfig getifaddr utun100
````
For **Linux** systems:
```shell
ip addr show wt0
```
For **Windows** systems:
```shell
netsh interface ip show config name="wt0"
```
4. Repeat on other machines.
### Running Management, Signal and Coturn ### Running Management, Signal and Coturn
Under infrastructure_files we have a docker-compose example to run both, Wiretrustee Management and Signal services, plus an instance of [Coturn](https://github.com/coturn/coturn), it also provides a turnserver.conf file as a simple example of Coturn configuration. Under infrastructure_files we have a docker-compose example to run both, Wiretrustee Management and Signal services, plus an instance of [Coturn](https://github.com/coturn/coturn), it also provides a turnserver.conf file as a simple example of Coturn configuration.
You can edit the turnserver.conf file and change its Realm setting (defaults to wiretrustee.com) to your own domain and user setting (defaults to username1:password1) to **proper credentials**. You can edit the turnserver.conf file and change its Realm setting (defaults to wiretrustee.com) to your own domain and user setting (defaults to username1:password1) to **proper credentials**.

BIN
media/peers.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.9 MiB