Browse Source

:ledger: Update docs

Ettore Di Giacinto 3 years ago
parent
commit
316c96dd2c

+ 1 - 0
README.md

@@ -32,6 +32,7 @@ It can:
 - **Create a VPN** :  Secure VPN between p2p peers
 - **Create a VPN** :  Secure VPN between p2p peers
   - Automatically assign IPs to nodes
   - Automatically assign IPs to nodes
   - Embedded tiny DNS server to resolve internal/external IPs
   - Embedded tiny DNS server to resolve internal/external IPs
+  - Create trusted zones to prevent network access if token is leaked
 
 
 - **Act as a reverse Proxy** : Share a tcp service like you would do with `ngrok`. EdgeVPN let expose TCP services to the p2p network nodes without establishing a VPN connection: creates reverse proxy and tunnels traffic into the p2p network.
 - **Act as a reverse Proxy** : Share a tcp service like you would do with `ngrok`. EdgeVPN let expose TCP services to the p2p network nodes without establishing a VPN connection: creates reverse proxy and tunnels traffic into the p2p network.
 
 

+ 2 - 2
docs/content/en/_index.html

@@ -56,7 +56,7 @@ Expose and route TCP services over the p2p network also without the VPN
 {{% /blocks/feature %}}
 {{% /blocks/feature %}}
 
 
 
 
-{{% blocks/feature icon="fa-cogs" title="API" %}}
+{{% blocks/feature icon="fa-eye" title="API" %}}
 Simple REST API with an embedded and simple UI with batteries included to operate the network Blockchain.
 Simple REST API with an embedded and simple UI with batteries included to operate the network Blockchain.
 {{% /blocks/feature %}}
 {{% /blocks/feature %}}
 
 
@@ -77,7 +77,7 @@ Simple REST API with an embedded and simple UI with batteries included to operat
 	 <a class="btn btn-md btn-primary mr-3 mb-4" href="{{< relref "/docs">}}/getting-started/gui/">GUI
 	 <a class="btn btn-md btn-primary mr-3 mb-4" href="{{< relref "/docs">}}/getting-started/gui/">GUI
 		<i class="fab fa-desktop ml-2 "></i></a><br>
 		<i class="fab fa-desktop ml-2 "></i></a><br>
 	Keep an eye on your network with the Web UI. <br>
 	Keep an eye on your network with the Web UI. <br>
-	Connect easily from your workstation with the frontend GUI app
+	Connect easily from your workstation with the frontend GUI app.
 </center>
 </center>
 </div>
 </div>
 <div class="col">
 <div class="col">

+ 1 - 1
docs/content/en/docs/Concepts/Architecture/_index.md

@@ -3,7 +3,7 @@ title: "Architecture"
 linkTitle: "Architecture"
 linkTitle: "Architecture"
 weight: 2
 weight: 2
 description: >
 description: >
-  EdgeVPN overview
+  EdgeVPN internal architecture
 resources:
 resources:
 - src: "**edgevpn_*.png"
 - src: "**edgevpn_*.png"
 ---
 ---

+ 4 - 2
docs/content/en/docs/Concepts/Overview/dns.md

@@ -7,9 +7,11 @@ description: >
   Embedded DNS server documentation
   Embedded DNS server documentation
 ---
 ---
 
 
-## DNS Server
+{{% pageinfo color="warning"%}}
+Experimental feature!
+{{% /pageinfo %}}
 
 
-Note: Experimental feature!
+## DNS Server
 
 
 A DNS Server is available but disabled by default. 
 A DNS Server is available but disabled by default. 
 
 

+ 97 - 0
docs/content/en/docs/Concepts/Overview/peerguardian.md

@@ -0,0 +1,97 @@
+---
+title: "Peerguardian"
+linkTitle: "Peerguardian"
+weight: 25
+date: 2022-01-05
+description: >
+  Prevent unauthorized access to the network if tokens are leaked
+---
+
+{{% pageinfo color="warning"%}}
+Experimental feature!
+{{% /pageinfo %}}
+
+## Peerguardian
+
+PeerGuardian is a mechanism to prevent unauthorized access to the network if tokens are leaked or either revoke network access.
+
+In order to enable it, start edgevpn nodes adding the `--peerguradian` flag.
+
+```bash
+edgevpn --peerguardian
+```
+
+To turn on peer gating, specify also `--peergate`. 
+
+Peerguardian and peergating has several options:
+
+```
+   --peerguard                                   Enable peerguard. (Experimental) [$PEERGUARD]
+   --peergate                                    Enable peergating. (Experimental) [$PEERGATE]
+   --peergate-autoclean                          Enable peergating autoclean. (Experimental) [$PEERGATE_AUTOCLEAN]
+   --peergate-relaxed                            Enable peergating relaxation. (Experimental) [$PEERGATE_RELAXED]
+   --peergate-auth value                         Peergate auth [$PEERGATE_AUTH]
+   --peergate-interval value                     Peergater interval time (default: 120) [$EDGEVPNPEERGATEINTERVAL]
+```
+
+When the PeerGuardian and Peergater are enabled, a VPN node will only accepts blocks from authorized nodes.
+
+Peerguardian is extensible to support different mechanisms of authentication, we will see below specific implementations.
+
+## ECDSA auth
+
+The ECDSA authentication mechanism is used to verify peers in the blockchain using ECDSA keys.
+
+To generate a new ECDSA keypair use `edgevpn peergater ecdsa-genkey`:
+
+```bash
+$ edgevpn peergater ecdsa-genkey
+Private key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1JSGNBZ0VCQkVJQkhUZnRSTVZSRmlvaWZrdllhZEE2NXVRQXlSZTJSZHM0MW1UTGZlNlRIT3FBTTdkZW9sak0KZXVPbTk2V0hacEpzNlJiVU1tL3BCWnZZcElSZ0UwZDJjdUdnQndZRks0RUVBQ09oZ1lrRGdZWUFCQUdVWStMNQptUzcvVWVoSjg0b3JieGo3ZmZUMHBYZ09MSzNZWEZLMWVrSTlEWnR6YnZWOUdwMHl6OTB3aVZxajdpMDFVRnhVCnRKbU1lWURIRzBTQkNuVWpDZ0FGT3ByUURpTXBFR2xYTmZ4LzIvdEVySDIzZDNwSytraFdJbUIza01QL2tRNEIKZzJmYnk2cXJpY1dHd3B4TXBXNWxKZVZXUGlkeWJmMSs0cVhPTWdQbmRnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
+Public key: LS0tLS1CRUdJTiBFQyBQVUJMSUMgS0VZLS0tLS0KTUlHYk1CQUdCeXFHU000OUFnRUdCU3VCQkFBakE0R0dBQVFCbEdQaStaa3UvMUhvU2ZPS0syOFkrMzMwOUtWNApEaXl0MkZ4U3RYcENQUTJiYzI3MWZScWRNcy9kTUlsYW8rNHROVkJjVkxTWmpIbUF4eHRFZ1FwMUl3b0FCVHFhCjBBNGpLUkJwVnpYOGY5djdSS3g5dDNkNlN2cElWaUpnZDVERC81RU9BWU5uMjh1cXE0bkZoc0tjVEtWdVpTWGwKVmo0bmNtMzlmdUtsempJRDUzWT0KLS0tLS1FTkQgRUMgUFVCTElDIEtFWS0tLS0tCg==
+```
+
+For example, to add a ECDSA public key, use the API as such from a node which is already trusted by PeerGuardian:
+
+```bash
+$ curl -X PUT 'http://localhost:8080/api/ledger/trustzoneAuth/ecdsa_1/LS0tLS1CRUdJTiBFQyBQVUJMSUMgS0VZLS0tLS0KTUlHYk1CQUdCeXFHU000OUFnRUdCU3VCQkFBakE0R0dBQVFBL09TTjhsUU9Wa3FHOHNHbGJiellWamZkdVVvUAplMEpsWUVzOFAyU3o1TDlzVUtDYi9kQWkrVFVONXU0ZVk2REpGeU50dWZjK2p0THNVTTlPb0xXVnBXb0E0eEVDCk9VdDFmRVNaRzUxckc4MEdFVjBuQTlBRGFvOW1XK3p4dmkvQnd0ZFVvSTNjTDB0VTdlUGEvSGM4Z1FLMmVOdE0KeDdBSmNYcWpPNXZXWGxZZ2NkOD0KLS0tLS1FTkQgRUMgUFVCTElDIEtFWS0tLS0tCg=='
+```
+
+Now the private key can be used while starting new nodes:
+
+```bash
+PEERGATE_AUTH="{ 'ecdsa' : { 'private_key': 'LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1JSGNBZ0VCQkVJQkhUZnRSTVZSRmlvaWZrdllhZEE2NXVRQXlSZTJSZHM0MW1UTGZlNlRIT3FBTTdkZW9sak0KZXVPbTk2V0hacEpzNlJiVU1tL3BCWnZZcElSZ0UwZDJjdUdnQndZRks0RUVBQ09oZ1lrRGdZWUFCQUdVWStMNQptUzcvVWVoSjg0b3JieGo3ZmZUMHBYZ09MSzNZWEZLMWVrSTlEWnR6YnZWOUdwMHl6OTB3aVZxajdpMDFVRnhVCnRKbU1lWURIRzBTQkNuVWpDZ0FGT3ByUURpTXBFR2xYTmZ4LzIvdEVySDIzZDNwSytraFdJbUIza01QL2tRNEIKZzJmYnk2cXJpY1dHd3B4TXBXNWxKZVZXUGlkeWJmMSs0cVhPTWdQbmRnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=' } }"
+$ edgevpn --peerguardian --peergate
+```
+
+## Enabling/Disabling peergating in runtime
+
+Peergating can be disabled in runtime by leveraging the api:
+
+### Query status
+
+```bash
+$ curl -X GET 'http://localhost:8080/api/peergate'
+```
+
+### Enable peergating
+```bash
+$ curl -X PUT 'http://localhost:8080/api/peergate/enable'
+```
+
+### Disable peergating
+```bash
+$ curl -X PUT 'http://localhost:8080/api/peergate/disable'
+```
+
+## Starting a new network
+
+To init a new Trusted network, start nodes with `--peergate-relaxed` and add the neccessary auth keys:
+
+```bash
+$ edgevpn --peerguardian --peergate --peergate-relaxed
+$ curl -X PUT 'http://localhost:8080/api/ledger/trustzoneAuth/keytype_1/XXX'
+```
+
+{{% alert title="Note" %}}
+It is strongly suggested to use a local store for the blockchain with PeerGuardian. In this way nodes persist locally auth keys and you can avoid starting nodes with `--peergate-relaxed'
+{{% /alert %}}

+ 2 - 0
docs/content/en/docs/Concepts/_index.md

@@ -2,4 +2,6 @@
 title: "Concepts"
 title: "Concepts"
 linkTitle: "Concepts"
 linkTitle: "Concepts"
 weight: 20
 weight: 20
+description: >
+  Expore EdgeVPN functionalities by looking at practical use-cases
 ---
 ---

+ 31 - 2
docs/content/en/docs/Getting started/api.md

@@ -1,6 +1,6 @@
 ---
 ---
-title: "webUI and API"
-linkTitle: "webUI and API"
+title: "WebUI and API"
+linkTitle: "WebUI and API"
 weight: 1
 weight: 1
 description: >
 description: >
   Query the network status and operate the ledger with the built-in API
   Query the network status and operate the ledger with the built-in API
@@ -72,12 +72,27 @@ Returns the current data in the ledger inside the `:bucket`
 
 
 Returns the current data in the ledger inside the `:bucket` at given `:key`
 Returns the current data in the ledger inside the `:bucket` at given `:key`
 
 
+#### `/api/peergate`
+
+Returns peergater status
+
 ### PUT
 ### PUT
 
 
 #### `/api/ledger/:bucket/:key/:value`
 #### `/api/ledger/:bucket/:key/:value`
 
 
 Puts `:value` in the ledger inside the `:bucket` at given `:key`
 Puts `:value` in the ledger inside the `:bucket` at given `:key`
 
 
+#### `/api/peergate/:state`
+
+Enables/disables peergating:
+
+```bash
+# enable
+$ curl -X PUT 'http://localhost:8080/api/peergate/enable'
+# disable
+$ curl -X PUT 'http://localhost:8080/api/peergate/disable'
+```
+
 ### POST
 ### POST
 
 
 #### `/api/dns`
 #### `/api/dns`
@@ -112,3 +127,17 @@ Deletes the `:key` into `:bucket` inside the ledger
 #### `/api/ledger/:bucket`
 #### `/api/ledger/:bucket`
 
 
 Deletes the `:bucket` from the ledger
 Deletes the `:bucket` from the ledger
+
+## Binding to a socket
+
+The API can also be bound to a socket, for instance:
+
+```bash
+$ edgevpn api --listen "unix://<path/to/socket>"
+```
+
+or as well while running the vpn:
+
+```bash
+$ edgevpn api --api-listen "unix://<path/to/socket>"
+```

+ 1 - 1
docs/content/en/docs/_index.md

@@ -30,6 +30,6 @@ It can:
 Check out the docs below for further example and reference, have a look at our [getting started guide]({{< relref "/docs">}}/getting-started), the [cli interface]({{< relref "/docs">}}/getting-started/cli), [gui desktop app]({{< relref "/docs">}}/getting-started/gui), and the embedde [WebUI/API]({{< relref "/docs">}}/getting-started/api/).
 Check out the docs below for further example and reference, have a look at our [getting started guide]({{< relref "/docs">}}/getting-started), the [cli interface]({{< relref "/docs">}}/getting-started/cli), [gui desktop app]({{< relref "/docs">}}/getting-started/gui), and the embedde [WebUI/API]({{< relref "/docs">}}/getting-started/api/).
 
 
 
 
-| WebUI            | [Desktop](https://github.com/mudler/edgevpn-gui)                                          |
+| [WebUI]({{< relref "/docs">}}/getting-started/api)            | [Desktop](https://github.com/mudler/edgevpn-gui)                                          |
 | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | ![img](https://user-images.githubusercontent.com/2420543/163020448-8e9238c1-3b6d-435d-9b25-7729d8779ebd.png) | ![](https://user-images.githubusercontent.com/2420543/147854909-a223a7c1-5caa-4e90-b0ac-0ae04dc0949d.png) |
 | ![img](https://user-images.githubusercontent.com/2420543/163020448-8e9238c1-3b6d-435d-9b25-7729d8779ebd.png) | ![](https://user-images.githubusercontent.com/2420543/147854909-a223a7c1-5caa-4e90-b0ac-0ae04dc0949d.png) |

+ 3 - 2
docs/content/en/docs/contribution-guidelines.md

@@ -3,7 +3,8 @@
 title: "Contributing"
 title: "Contributing"
 linkTitle: "Contribution guidelines"
 linkTitle: "Contribution guidelines"
 weight: 159
 weight: 159
-
+description: >
+  See how to contribute to EdgeVPN
 ---
 ---
 
 
 ## Contributing to EdgeVPN
 ## Contributing to EdgeVPN
@@ -45,7 +46,7 @@ updates:
 
 
 1. Fork the [the repo](https://github.com/mudler/edgevpn) on GitHub.
 1. Fork the [the repo](https://github.com/mudler/edgevpn) on GitHub.
 2. Make your changes, if are related to docs
 2. Make your changes, if are related to docs
-   to see the preview cd into `docs` and run `make serve`, then browse to [localhost:1313](http://localhost:1313)
+   to see the preview run `make serve` from the `docs` dir, then browse to [localhost:1313](http://localhost:1313)
 3. If you're not yet ready for a review, add "WIP" to the PR name to indicate 
 3. If you're not yet ready for a review, add "WIP" to the PR name to indicate 
   it's a work in progress.
   it's a work in progress.
 4. Continue updating your doc and pushing your changes until you're happy with 
 4. Continue updating your doc and pushing your changes until you're happy with