+ <p>EdgeVPN have a simplified model of a blockchain embedded. The model is actually simplified on purpose as the blockchain is used to store merely network and services metadata and not transaction, or content addressable network.</p>
+<p>The only data stored in the blockchain is:</p>
+<ul>
+<li>Network Peer IDs, Service IDs, File IDs</li>
+<li>Healthchecks, DNS records and IP allocation</li>
+</ul>
+<p>However, the ledger is freely accessible via API, allowing for external coordination to use the blockchain mechanism as a shared memory access (which can be optionally persisted on disk).</p>
+<p>EdgeVPN uses <a href="https://github.com/libp2p/go-libp2p">libp2p</a> to establish a decentralized, asymmetrically encrypted gossip network which propagate a (symmetrically encrypted) blockchain states between nodes.</p>
+<p>The blockchain is lightweight as:</p>
+<ul>
+<li>There is no PoW mechanism</li>
+<li>It is in memory only, no DAG, CARv2, or GraphSync protocol - the usage is restricted to hold metadata, and not real addressable content</li>
+</ul>
+<p>EdgeVPN uses the blockchain to store Services UUID, Files UUID, VPN and other metadata (such as DNS records, IP, etc.) and co-ordinate events between the nodes of the network. Besides, it is used as a mechanism of protection: if nodes are not part of the blockchain, they can&rsquo;t talk to each other.</p>
+<p>The blockchain is ephemeral and on-memory, optionally can be stored on disk.</p>
+<p>Each node keeps broadcasting it&rsquo;s state until it is reconciled in the blockchain. If the blockchain would get start from scratch, the hosts would re-announce and try to fill the blockchain with their data.</p>
+<ul>
+<li>Simple (KISS) interface to display network data from the blockchain</li>
+<li>asymmetric p2p encryption between peers with libp2p</li>
+<li>randezvous points dynamically generated from OTP keys</li>
+<li>extra AES symmetric encryption on top. In case randezvous point is compromised</li>
+<li>blockchain is used as a sealed encrypted store for the routing table</li>
+<li>connections are created host to host and encrypted asymmetrically</li>
+<p>In the first phase, nodes do discover each others via DHT and a randevouz secret which is automatically generated via OTP.</p>
+<p>Once peers know about each other a gossip network is established, where the nodes exchange a blockchain over an p2p e2e encrypted channel. The blockchain is sealed with a symmetric key which is rotated via OTP that is shared between the nodes.</p>
+<p>At that point a blockchain and an API is established between the nodes, and optionally start the VPN binding on the tun/tap device.</p>
+</code></pre><p>This will print out in screen a base64 token which is ready to be shared on nodes that you wish to join on the same network.</p>
+</span></code></pre></div><p>The values can be all tweaked to your needs.</p>
+<p>EdgeVPN uses an otp mechanism to decrypt blockchain messages between the nodes and to discover nodes from DHT, this is in order to prevent bruteforce attacks and avoid bad actors listening on the protocol.
+See <a href="">the Architecture section</a> for more information.</p>
+<ul>
+<li>The OTP keys (<code>otp.crypto.key</code>) rotates the cipher key used to encode/decode the blockchain messages. The interval of rotation can be set for both DHT and the Blockchain messages. The length is the cipher key length (AES-256 by default) used by the sealer to decrypt/encrypt messages.</li>
+<li>The DHT OTP keys (<code>otp.dht.key</code>) rotates the discovery key used during DHT node discovery. A key is generated and used with OTP at defined intervals to scramble potential listeners.</li>
+<li>The <code>room</code> is a unique ID which all the nodes will subscribe to. It is automatically generated</li>
+<li>Optionally the OTP mechanism can be disabled by commenting the <code>otp</code> block. In this case the static DHT rendezvous will be <code>rendezvous</code></li>
+<li>The <code>mdns</code> discovery doesn&rsquo;t have any OTP rotation, so a unique identifier must be provided.</li>
+<li>Here can be defined the max message size accepted for the blockchain messages with <code>max_message_size</code> (in bytes)</li>
+ <h2 id="forwarding-a-local-connection">Forwarding a local connection</h2>
+<p>EdgeVPN can also be used to expose local(or remote) services without establishing a VPN and allocating a local tun/tap device, similarly to <code>ngrok</code>.</p>
+<h3 id="exposing-a-service">Exposing a service</h3>
+<p>If you are used to how Local SSH forwarding works (e.g. <code>ssh -L 9090:something:remote &lt;my_node&gt;</code>), EdgeVPN takes a similar approach.</p>
+<p>A Service is a generalized TCP service running in a host (also outside the network). For example, let&rsquo;s say that we want to expose a SSH server inside a LAN.</p>
+<p>To expose a service to your EdgeVPN network then:</p>
+</code></pre></div><p>To reach the service, EdgeVPN will setup a local port and bind to it, it will tunnel the traffic to the service over the VPN, for e.g. to bind locally to <code>9090</code>:</p>
+</code></pre></div><p>with the example above, &lsquo;sshing into <code>9090</code> locally would forward to <code>22</code>.</p>
+</code></pre></div><p>&hellip; and that&rsquo;s it! the <code>--address</code> is a <em>virtual</em> unique IP for each node, and it is actually the ip where the node will be reachable to from the vpn. You can assign IPs freely to the nodes of the network, while you can override the default <code>edgevpn0</code> interface with <code>IFACE</code> (or <code>--interface</code>)</p>
+<p><em>Note</em>: It might take up time to build the connection between nodes. Wait at least 5 mins, it depends on the network behind the hosts.</p>
+<p>The VPN takes several options, below you will find a reference for the most important features:</p>
+<h2 id="generate-a-network-token">Generate a network token</h2>
+<p>EdgeVPN works by generating tokens (or network configuration files) that are shared between different machines.</p>
+<p>Every token is unique and identifies the network itself: there is no central server setup, and no IP address is specified in config files.</p>
+<p>To generate a new network token, just run <code>edgevpn -g -b</code>:</p>
+</code></pre></div><p>A network token needs to be specified for all later interactions with edgevpn, in order to connect and establish a network connection between peers.</p>
+<p>For example, to start <code>edgevpn</code> in API mode:</p>
+<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash">$ edgevpn api --token &lt;token&gt; <span style="color:#8f5902;font-style:italic"># or alternatively using $EDGEVPNTOKEN</span>
+ INFO edgevpn Copyright <span style="color:#ce5c00;font-weight:bold">(</span>C<span style="color:#ce5c00;font-weight:bold">)</span> 2021-2022 Ettore Di Giacinto
+ This program comes with ABSOLUTELY NO WARRANTY.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions.
+ INFO Version: v0.8.4 commit:
+ INFO Starting EdgeVPN network
+ INFO Node ID: 12D3KooWRW4RXSMAh7CTRsTjX7iEjU6DEU8QKJZvFjSosv7zCCeZ
+ INFO Node Addresses: <span style="color:#ce5c00;font-weight:bold">[</span>/ip6/::1/tcp/38637 /ip4/192.168.1.234/tcp/41607 /ip4/127.0.0.1/tcp/41607<span style="color:#ce5c00;font-weight:bold">]</span>
+ INFO Bootstrapping DHT
+⇨ http server started on <span style="color:#ce5c00;font-weight:bold">[</span>::<span style="color:#ce5c00;font-weight:bold">]</span>:8080
+</code></pre></div><p>Alternatively a network configuration file can be specified with <code>--config</code> or <code>EDGEVPNCONFIG</code>.</p>
+<p>As the token is a network configuration file encoded in base64, using a token or a config is equivalent:</p>
+<p>While starting in VPN mode, it is possible <em>also</em> to start in API mode by specifying <code>--api</code>.</p>
+<h2 id="dhcp">DHCP</h2>
+<p>Note: Experimental feature!</p>
+<p>Automatic IP negotiation is available since version <code>0.8.1</code>.</p>
+<p>DHCP can be enabled with <code>--dhcp</code> and <code>--address</code> can be omitted. If an IP is specfied with <code>--address</code> it will be the default IP.</p>
+<h2 id="mailbox-sending-and-receiving-files">:mailbox: Sending and receiving files</h2>
+<p>EdgeVPN can be used to send and receive files between hosts via p2p with the <code>file-send</code> and <code>file-receive</code> subcommand.</p>
+<p>Sending and receiving files, as services, don&rsquo;t establish a VPN connection.</p>
+ <p>A Desktop GUI application (alpha) for Linux is available <a href="https://github.com/mudler/edgevpn-gui">here</a>.</p>
+<p>Note the GUI doesn&rsquo;t require the CLI to be installed. It will automatically prompt to download the latest available version, and offer a version management option.</p>
+ <p>The API has a simple webUI embedded to display network informations.</p>
+<p>To access the web interface, run in the console:</p>
+<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash">$ edgevpn api
+</code></pre></div><p>with either a <code>EDGEVPNCONFIG</code> or <code>EDGEVPNTOKEN</code>.</p>
+<p>In API mode, EdgeVPN will connect to the network without routing any packet, and without setting up a VPN interface.</p>
+<p>By default edgevpn will listen on the <code>8080</code> port. See <code>edgevpn api --help</code> for the available options</p>
+<p>API can also be started together with the vpn with <code>--api</code>.</p>
+<p>Puts <code>:value</code> in the ledger inside the <code>:bucket</code> at given <code>:key</code></p>
+</code></pre></div><p>&hellip; and that&rsquo;s it! the <code>--address</code> is a <em>virtual</em> unique IP for each node, and it is actually the ip where the node will be reachable to from the vpn. You can assign IPs freely to the nodes of the network, while you can override the default <code>edgevpn0</code> interface with <code>IFACE</code> (or <code>--interface</code>)</p>
+<p><em>Note</em>: It might take up time to build the connection between nodes. Wait at least 5 mins, it depends on the network behind the hosts.</p>
+<p>The VPN takes several options, below you will find a reference for the most important features:</p>
+<h2 id="generate-a-network-token">Generate a network token</h2>
+<p>EdgeVPN works by generating tokens (or network configuration files) that are shared between different machines.</p>
+<p>Every token is unique and identifies the network itself: there is no central server setup, and no IP address is specified in config files.</p>
+<p>To generate a new network token, just run <code>edgevpn -g -b</code>:</p>
+</code></pre></div><p>A network token needs to be specified for all later interactions with edgevpn, in order to connect and establish a network connection between peers.</p>
+<p>For example, to start <code>edgevpn</code> in API mode:</p>
+<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash">$ edgevpn api --token &lt;token&gt; <span style="color:#8f5902;font-style:italic"># or alternatively using $EDGEVPNTOKEN</span>
+ INFO edgevpn Copyright <span style="color:#ce5c00;font-weight:bold">(</span>C<span style="color:#ce5c00;font-weight:bold">)</span> 2021-2022 Ettore Di Giacinto
+ This program comes with ABSOLUTELY NO WARRANTY.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions.
+ INFO Version: v0.8.4 commit:
+ INFO Starting EdgeVPN network
+ INFO Node ID: 12D3KooWRW4RXSMAh7CTRsTjX7iEjU6DEU8QKJZvFjSosv7zCCeZ
+ INFO Node Addresses: <span style="color:#ce5c00;font-weight:bold">[</span>/ip6/::1/tcp/38637 /ip4/192.168.1.234/tcp/41607 /ip4/127.0.0.1/tcp/41607<span style="color:#ce5c00;font-weight:bold">]</span>
+ INFO Bootstrapping DHT
+⇨ http server started on <span style="color:#ce5c00;font-weight:bold">[</span>::<span style="color:#ce5c00;font-weight:bold">]</span>:8080
+</code></pre></div><p>Alternatively a network configuration file can be specified with <code>--config</code> or <code>EDGEVPNCONFIG</code>.</p>
+<p>As the token is a network configuration file encoded in base64, using a token or a config is equivalent:</p>
+<p>While starting in VPN mode, it is possible <em>also</em> to start in API mode by specifying <code>--api</code>.</p>
+<h2 id="dhcp">DHCP</h2>
+<p>Note: Experimental feature!</p>
+<p>Automatic IP negotiation is available since version <code>0.8.1</code>.</p>
+<p>DHCP can be enabled with <code>--dhcp</code> and <code>--address</code> can be omitted. If an IP is specfied with <code>--address</code> it will be the default IP.</p>
+<h2 id="mailbox-sending-and-receiving-files">:mailbox: Sending and receiving files</h2>
+<p>EdgeVPN can be used to send and receive files between hosts via p2p with the <code>file-send</code> and <code>file-receive</code> subcommand.</p>
+<p>Sending and receiving files, as services, don&rsquo;t establish a VPN connection.</p>
+ <p>A Desktop GUI application (alpha) for Linux is available <a href="https://github.com/mudler/edgevpn-gui">here</a>.</p>
+<p>Note the GUI doesn&rsquo;t require the CLI to be installed. It will automatically prompt to download the latest available version, and offer a version management option.</p>
+ <h2 id="forwarding-a-local-connection">Forwarding a local connection</h2>
+<p>EdgeVPN can also be used to expose local(or remote) services without establishing a VPN and allocating a local tun/tap device, similarly to <code>ngrok</code>.</p>
+<h3 id="exposing-a-service">Exposing a service</h3>
+<p>If you are used to how Local SSH forwarding works (e.g. <code>ssh -L 9090:something:remote &lt;my_node&gt;</code>), EdgeVPN takes a similar approach.</p>
+<p>A Service is a generalized TCP service running in a host (also outside the network). For example, let&rsquo;s say that we want to expose a SSH server inside a LAN.</p>
+<p>To expose a service to your EdgeVPN network then:</p>
+</code></pre></div><p>To reach the service, EdgeVPN will setup a local port and bind to it, it will tunnel the traffic to the service over the VPN, for e.g. to bind locally to <code>9090</code>:</p>
+</code></pre></div><p>with the example above, &lsquo;sshing into <code>9090</code> locally would forward to <code>22</code>.</p>
+ <p>The API has a simple webUI embedded to display network informations.</p>
+<p>To access the web interface, run in the console:</p>
+<div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash">$ edgevpn api
+</code></pre></div><p>with either a <code>EDGEVPNCONFIG</code> or <code>EDGEVPNTOKEN</code>.</p>
+<p>In API mode, EdgeVPN will connect to the network without routing any packet, and without setting up a VPN interface.</p>
+<p>By default edgevpn will listen on the <code>8080</code> port. See <code>edgevpn api --help</code> for the available options</p>
+<p>API can also be started together with the vpn with <code>--api</code>.</p>
+<p>Puts <code>:value</code> in the ledger inside the <code>:bucket</code> at given <code>:key</code></p>
+<p>A DNS Server is available but disabled by default.</p>
+<p>The DNS server will resolve DNS queries using the blockchain as a record and will forward unknown domains by default.</p>
+<p>It can be enabled by specifying a listening address with <code>--dns</code>. For example, to bind to default <code>53</code> port locally, run in the console:</p>
+</code></pre></div><p>To turn off dns forwarding, specify <code>--dns-forwarder=false</code>. Optionally a list of DNS servers can be specified multiple times with <code>--dns-forward-server</code>.</p>
+<p>The dns subcommand has several options:</p>
+<pre tabindex="0"><code> --dns value DNS listening address. Empty to disable dns server [$DNSADDRESS]
+ --dns-forwarder Enables dns forwarding [$DNSFORWARD]
+ --dns-cache-size value DNS LRU cache size (default: 200) [$DNSCACHESIZE]
+ --dns-forward-server value List of DNS forward server (default: &quot;8.8.8.8:53&quot;, &quot;1.1.1.1:53&quot;) [$DNSFORWARDSERVER]
+</code></pre><p>Nodes of the VPN can start a local DNS server which will resolve the routes stored in the chain.</p>
+<p>For example, to add DNS records, use the API as such:</p>
+</code></pre></div><p>The <code>/api/dns</code> routes accepts <code>POST</code> requests as <code>JSON</code> of the following form:</p>
+</code></pre></div><p>Note, <code>Regex</code> accepts regexes which will match the DNS requests received and resolved to the specified entries.</p>
+ <h2 id="contributing-to-edgevpn">Contributing to EdgeVPN</h2>
+<p>Contribution guidelines for the EdgeVPN project are on the <a href="https://github.com/mudler/edgevpn/blob/master/CONTRIBUTING.md">Github repository</a>. Here you can find some heads up for contributing to the documentation website.</p>
+<h2 id="contributing-to-the-docs-website">Contributing to the Docs website</h2>
+<h3 id="we-develop-with-github">We Develop with Github</h3>
+<p>We use <a href="https://github.com/mudler/edgevpn">github to host code</a>, to track issues and feature requests, as well as accept pull requests.</p>
+<p>We use <a href="https://gohugo.io/">Hugo</a> to format and generate our website, the
+<a href="https://github.com/google/docsy">Docsy</a> theme for styling and site structure,
+and Github Actions to manage the deployment of the site.
+Hugo is an open-source static site generator that provides us with templates,
+content organisation in a standard directory structure, and a website generation
+engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.</p>
+<p>All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+<a href="https://help.github.com/articles/about-pull-requests/">GitHub Help</a> for more
+information on using pull requests.</p>
+<h3 id="any-contributions-you-make-will-be-under-the-software-license-of-the-repository">Any contributions you make will be under the Software License of the repository</h3>
+<p>In short, when you submit code changes, your submissions are understood to be under the same License that covers the project. Feel free to contact the maintainers if that&rsquo;s a concern.</p>
+<h3 id="updating-a-single-page">Updating a single page</h3>
+<p>If you&rsquo;ve just spotted something you&rsquo;d like to change while using the docs, Docsy has a shortcut for you:</p>
+<ol>
+<li>Click <strong>Edit this page</strong> in the top right hand corner of the page you want to modify.</li>
+<li>If you don&rsquo;t already have an up to date fork of the project repo, you are prompted to get one - click <strong>Fork this repository and propose changes</strong> or <strong>Update your Fork</strong> to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.</li>
+</ol>
+<h3 id="quick-start-with-a-local-checkout">Quick start with a local checkout</h3>
+<p>Here&rsquo;s a quick guide to updating the docs with a git local checkout. It assumes you&rsquo;re familiar with the
+GitHub workflow and you&rsquo;re happy to use the automated preview of your doc
+updates:</p>
+<ol>
+<li>Fork the <a href="https://github.com/mudler/edgevpn">the repo</a> on GitHub.</li>
+<li>Make your changes, if are related to docs
+to see the preview cd into <code>docs</code> and run <code>make serve</code>, then browse to <a href="http://localhost:1313">localhost:1313</a></li>
+<li>If you&rsquo;re not yet ready for a review, add &ldquo;WIP&rdquo; to the PR name to indicate
+it&rsquo;s a work in progress.</li>
+<li>Continue updating your doc and pushing your changes until you&rsquo;re happy with
+the content.</li>
+<li>When you&rsquo;re ready for a review, add a comment to the PR, and remove any
+&ldquo;WIP&rdquo; markers.</li>
+<li>When you are satisfied send a pull request (PR).</li>
+<p>A DNS Server is available but disabled by default.</p>
+<p>The DNS server will resolve DNS queries using the blockchain as a record and will forward unknown domains by default.</p>
+<p>It can be enabled by specifying a listening address with <code>--dns</code>. For example, to bind to default <code>53</code> port locally, run in the console:</p>
+</code></pre></div><p>To turn off dns forwarding, specify <code>--dns-forwarder=false</code>. Optionally a list of DNS servers can be specified multiple times with <code>--dns-forward-server</code>.</p>
+<p>The dns subcommand has several options:</p>
+<pre tabindex="0"><code> --dns value DNS listening address. Empty to disable dns server [$DNSADDRESS]
+ --dns-forwarder Enables dns forwarding [$DNSFORWARD]
+ --dns-cache-size value DNS LRU cache size (default: 200) [$DNSCACHESIZE]
+ --dns-forward-server value List of DNS forward server (default: &quot;8.8.8.8:53&quot;, &quot;1.1.1.1:53&quot;) [$DNSFORWARDSERVER]
+</code></pre><p>Nodes of the VPN can start a local DNS server which will resolve the routes stored in the chain.</p>
+<p>For example, to add DNS records, use the API as such:</p>
+</code></pre></div><p>The <code>/api/dns</code> routes accepts <code>POST</code> requests as <code>JSON</code> of the following form:</p>
+</code></pre></div><p>Note, <code>Regex</code> accepts regexes which will match the DNS requests received and resolved to the specified entries.</p>