From 09916efcf0fdd17df1aac5e83033467028bb6348 Mon Sep 17 00:00:00 2001 From: TC Johnson Date: Mon, 18 Sep 2023 08:57:26 -0500 Subject: [PATCH 1/5] Add bootstrap setup instructions Guide to setting up bootstrap servers --- # Starting a Bootstrap.md | 76 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100755 # Starting a Bootstrap.md diff --git a/# Starting a Bootstrap.md b/# Starting a Bootstrap.md new file mode 100755 index 00000000..f4dd3b5f --- /dev/null +++ b/# Starting a Bootstrap.md @@ -0,0 +1,76 @@ +# Starting a Veilid Bootstrap Server +## Instance Recommended Setup +CPU: Single +RAM: 1GB +Storage: 25GB +IP: Static v4 & v6 +Firewall: 5150/TCP/UDP inbound allow all + +## Install Veilid +**As root** + + ```shell +wget -O- https://packages.veilid.net/keys/veilid-packages-key.public | gpg --dearmor -o /usr/share/keyrings/veilid-packages-keyring.gpg +``` +```shell +echo "deb [arch=amd64 signed-by=/usr/share/keyrings/veilid-packages-keyring.gpg] https://packages.veilid.net/repos stable main" > /etc/apt/sources.list.d/veilid.list +``` +```shell +apt update && apt install veilid-server veilid-cli +``` + +## Configure Veilid +**As root** + +### Stop the Veilid service +```shell +systemctl stop veilid-server.service +``` + +### Setup the config +In _/etc/veilid-server/veilid-server.conf`_ ensure _bootstrap: ['bootstrap.veilid.net']_ in the _routing_table:_ section + +**Switch to veilid user** +```shell +sudo -u veilid /bin/bash +``` + +### Generate a new keypair +Copy the output to secure storage. +```shell +veilid-server --generate-key-pair +``` + +### Create new node ID and flush existing route table +Include the brackets [] when pasting the keys. Use the public key in the command. Secret key will be request interacitvly and will not echo when pasted. +```shell +veilid-server --set-node-id [PUBLIC_KEY] --delete-table-store +``` +### Generate the DNS TXT record +Copy the output to secure storage. +```shell +veilid-server --dump-txt-record +``` + +**Switch back to root** +### Start the Veilid service +```shell +systemctl start veilid-server.service +``` + +_REPEAT FOR EACH BOOTSTRAP SERVER_ + +## Enter DNS Records +Create the following DNS Records for your domain: + +(This example assumes two bootstrap serves are being created) + +| Record | Value | Record Type | +|-----------|-----------------------------|-------------| +|bootstrap | 1,2 | TXT | +|1.bootstrap| IPv4 | A | +|1.bootstrap| IPv6 | AAAA | +|1.bootstrap| output of --dump-txt-record | TXT | +|2.bootstrap| IPv4 | A | +|2.bootstrap| IPv6 | AAAA | +|2.bootstrap| output of --dump-txt-record | TXT | From 9f92d486b85477d02445a2f5b727dfa3e6804050 Mon Sep 17 00:00:00 2001 From: TC Johnson Date: Mon, 18 Sep 2023 09:00:30 -0500 Subject: [PATCH 2/5] Rename bootstrap setup file Renamed to match other docs format --- # Starting a Bootstrap.md => BOOTSTRAP-SETUP.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename # Starting a Bootstrap.md => BOOTSTRAP-SETUP.md (100%) diff --git a/# Starting a Bootstrap.md b/BOOTSTRAP-SETUP.md similarity index 100% rename from # Starting a Bootstrap.md rename to BOOTSTRAP-SETUP.md From 1e27df2aee49a19f0b2c492d74ed0821f94aee7f Mon Sep 17 00:00:00 2001 From: TC Date: Mon, 18 Sep 2023 14:10:19 +0000 Subject: [PATCH 3/5] Update BOOTSTRAP-SETUP.md --- BOOTSTRAP-SETUP.md | 142 +++++++++++++++++++++------------------------ 1 file changed, 66 insertions(+), 76 deletions(-) diff --git a/BOOTSTRAP-SETUP.md b/BOOTSTRAP-SETUP.md index f4dd3b5f..4aa08c0d 100755 --- a/BOOTSTRAP-SETUP.md +++ b/BOOTSTRAP-SETUP.md @@ -1,76 +1,66 @@ -# Starting a Veilid Bootstrap Server -## Instance Recommended Setup -CPU: Single -RAM: 1GB -Storage: 25GB -IP: Static v4 & v6 -Firewall: 5150/TCP/UDP inbound allow all - -## Install Veilid -**As root** - - ```shell -wget -O- https://packages.veilid.net/keys/veilid-packages-key.public | gpg --dearmor -o /usr/share/keyrings/veilid-packages-keyring.gpg -``` -```shell -echo "deb [arch=amd64 signed-by=/usr/share/keyrings/veilid-packages-keyring.gpg] https://packages.veilid.net/repos stable main" > /etc/apt/sources.list.d/veilid.list -``` -```shell -apt update && apt install veilid-server veilid-cli -``` - -## Configure Veilid -**As root** - -### Stop the Veilid service -```shell -systemctl stop veilid-server.service -``` - -### Setup the config -In _/etc/veilid-server/veilid-server.conf`_ ensure _bootstrap: ['bootstrap.veilid.net']_ in the _routing_table:_ section - -**Switch to veilid user** -```shell -sudo -u veilid /bin/bash -``` - -### Generate a new keypair -Copy the output to secure storage. -```shell -veilid-server --generate-key-pair -``` - -### Create new node ID and flush existing route table -Include the brackets [] when pasting the keys. Use the public key in the command. Secret key will be request interacitvly and will not echo when pasted. -```shell -veilid-server --set-node-id [PUBLIC_KEY] --delete-table-store -``` -### Generate the DNS TXT record -Copy the output to secure storage. -```shell -veilid-server --dump-txt-record -``` - -**Switch back to root** -### Start the Veilid service -```shell -systemctl start veilid-server.service -``` - -_REPEAT FOR EACH BOOTSTRAP SERVER_ - -## Enter DNS Records -Create the following DNS Records for your domain: - -(This example assumes two bootstrap serves are being created) - -| Record | Value | Record Type | -|-----------|-----------------------------|-------------| -|bootstrap | 1,2 | TXT | -|1.bootstrap| IPv4 | A | -|1.bootstrap| IPv6 | AAAA | -|1.bootstrap| output of --dump-txt-record | TXT | -|2.bootstrap| IPv4 | A | -|2.bootstrap| IPv6 | AAAA | -|2.bootstrap| output of --dump-txt-record | TXT | +# Starting a Veilid Bootstrap Server +## Instance Recommended Setup +CPU: Single +RAM: 1GB +Storage: 25GB +IP: Static v4 & v6 +Firewall: 5150/TCP/UDP inbound allow all + +## Install Veilid +Follow instructions in [INSTALL.md](./INSTALL.md) + +## Configure Veilid +**As root** + +### Stop the Veilid service +```shell +systemctl stop veilid-server.service +``` + +### Setup the config +In _/etc/veilid-server/veilid-server.conf`_ ensure _bootstrap: ['bootstrap.']_ in the _routing_table:_ section + +**Switch to veilid user** +```shell +sudo -u veilid /bin/bash +``` + +### Generate a new keypair +Copy the output to secure storage. +```shell +veilid-server --generate-key-pair +``` + +### Create new node ID and flush existing route table +Include the brackets [] when pasting the keys. Use the public key in the command. Secret key will be request interacitvly and will not echo when pasted. +```shell +veilid-server --set-node-id [PUBLIC_KEY] --delete-table-store +``` +### Generate the DNS TXT record +Copy the output to secure storage. +```shell +veilid-server --dump-txt-record +``` + +**Switch back to root** +### Start the Veilid service +```shell +systemctl start veilid-server.service +``` + +_REPEAT FOR EACH BOOTSTRAP SERVER_ + +## Enter DNS Records +Create the following DNS Records for your domain: + +(This example assumes two bootstrap serves are being created) + +| Record | Value | Record Type | +|-----------|-----------------------------|-------------| +|bootstrap | 1,2 | TXT | +|1.bootstrap| IPv4 | A | +|1.bootstrap| IPv6 | AAAA | +|1.bootstrap| output of --dump-txt-record | TXT | +|2.bootstrap| IPv4 | A | +|2.bootstrap| IPv6 | AAAA | +|2.bootstrap| output of --dump-txt-record | TXT | From 6e9610ecd230d92a6fcc7f51a3011fe35f9595cf Mon Sep 17 00:00:00 2001 From: TC Johnson Date: Mon, 18 Sep 2023 21:28:56 -0500 Subject: [PATCH 4/5] Dev network setup docs Added guilds for setting up a public bootstrap, a dev network, and config templates for dev nodes. Added link in the contribution guide to dev network setup guide. --- BOOTSTRAP-SETUP.md | 33 ++++++++++++++---- CONTRIBUTING.md | 2 +- dev-setup/dev-network-setup.md | 42 +++++++++++++++++++++++ doc/config/veilid-bootstrap-config.md | 33 ++++++++++++++++++ doc/config/veilid-dev-bootstrap-config.md | 34 ++++++++++++++++++ doc/config/veilid-dev-node-config.md | 34 ++++++++++++++++++ doc/guide/guide.html | 1 - doc/guide/guide.md | 4 --- 8 files changed, 171 insertions(+), 12 deletions(-) create mode 100644 dev-setup/dev-network-setup.md create mode 100644 doc/config/veilid-bootstrap-config.md create mode 100644 doc/config/veilid-dev-bootstrap-config.md create mode 100644 doc/config/veilid-dev-node-config.md diff --git a/BOOTSTRAP-SETUP.md b/BOOTSTRAP-SETUP.md index 4aa08c0d..1aeb6343 100755 --- a/BOOTSTRAP-SETUP.md +++ b/BOOTSTRAP-SETUP.md @@ -1,5 +1,7 @@ -# Starting a Veilid Bootstrap Server +# Starting a Generic/Public Veilid Bootstrap Server + ## Instance Recommended Setup + CPU: Single RAM: 1GB Storage: 25GB @@ -7,50 +9,69 @@ IP: Static v4 & v6 Firewall: 5150/TCP/UDP inbound allow all ## Install Veilid + Follow instructions in [INSTALL.md](./INSTALL.md) -## Configure Veilid +## Configure Veilid as Bootstrap + **As root** -### Stop the Veilid service -```shell +### Stop the Veilid service + +```shell systemctl stop veilid-server.service ``` ### Setup the config + In _/etc/veilid-server/veilid-server.conf`_ ensure _bootstrap: ['bootstrap.']_ in the _routing_table:_ section +If you came here from the [dev network setup](./dev-setup/dev-network-setup.md) guide, this is when you set the network key. + **Switch to veilid user** + ```shell sudo -u veilid /bin/bash ``` ### Generate a new keypair + Copy the output to secure storage. + ```shell veilid-server --generate-key-pair ``` ### Create new node ID and flush existing route table + Include the brackets [] when pasting the keys. Use the public key in the command. Secret key will be request interacitvly and will not echo when pasted. + ```shell veilid-server --set-node-id [PUBLIC_KEY] --delete-table-store ``` + ### Generate the DNS TXT record + Copy the output to secure storage. + ```shell veilid-server --dump-txt-record ``` **Switch back to root** -### Start the Veilid service -```shell + +### Start the Veilid service + +```shell systemctl start veilid-server.service ``` +Optionally configure the service to start at boot `sudo systemctl enable veilid-server.service` + _REPEAT FOR EACH BOOTSTRAP SERVER_ ## Enter DNS Records + Create the following DNS Records for your domain: (This example assumes two bootstrap serves are being created) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d8e949e..6f621442 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Before you get started, please review our [Code of Conduct](./code_of_conduct.md To begin crafting code to contribute to the Veilid project, first set up a [development environment](./DEVELOPMENT.md). [Fork] and clone the project into your workspace; check out a new local branch and name it in a way that describes the work being done. This is referred to as a [feature branch]. -Some contributions might introduce changes that are incompatible with other existing nodes. In this case it is recommended to also set a development network *Guide Coming Soon*. +Some contributions might introduce changes that are incompatible with other existing nodes. In this case it is recommended to also setup a [development network](./dev-setup/dev-network-setup.md). Once you have added your new function or addressed a bug, test it locally to ensure it's working as expected. If needed, test your work in a development network with more than one node based on your code. Once you're satisfied your code works as intended and does not introduce negative results or new bugs, follow the merge requests section below to submit your work for maintainer review. diff --git a/dev-setup/dev-network-setup.md b/dev-setup/dev-network-setup.md new file mode 100644 index 00000000..aac705c4 --- /dev/null +++ b/dev-setup/dev-network-setup.md @@ -0,0 +1,42 @@ +# Dev Network Setup + +## Purpose + +There will be times when a contibutor wishes to dynamically test their work on live nodes. Doing so on the actual Veilid network would likely not yield productive test outcomes and so setting up an independent network for testing purposes is warranted. + +This document outlines the process of using the steps found in [INSTALL.md](../INSTALL.md) and [BOOTSTRAP-SETUP.md](../BOOTSTRAP-SETUP.md) with some modifications which results in a reasonably isolated and independent network of Veilid development nodes which do not communicate with nodes on the actual Veilid network. + +The minimum topology of a dev network is 1 bootstrap server and 4 nodes, all with public IP addresses with port 5150/TCP open. This allows enabling public address detection and private routing. The minimum specifications are 1 vCPU, 1GB RAM, and 25 GB storage. + +## Quick Start + +### The Network Key + +This acts as a passphase to allow nodes to join the network. It is the mechanism that makes your dev network isolated and independent. Create a passphrase and protect/store it as you would any other a password. + +### Dev Bootstrap Server + +Follow the steps detailed in [BOOTSTRAP-SETUP.md](../BOOTSTRAP-SETUP.md) using the dev bootstrap example [config](../doc/config/veilid-dev-bootstrap-config.md) for the *Setup the config* section. Set your network key on line 28. + +### Dev Nodes + +1. Follow the steps detailed in [INSTALL.md](../INSTALL.md) *DO NOT START THE SYSTEMD SERVICE* +2. Replace the default veilid-server config using the dev node example [config](../doc/config/veilid-dev-server-config.md) as a template. Enter your information on lines 27 and 28 to match what was entered in the dev bootstrap server's config. +3. Start the node with fresh data + + ```shell + sudo -u veilid veilid-server --delete-protected-store --delete-block-store --delete-table-store` + ``` + +4. `ctrl-c` to stop the above process +5. Start the dev node service + + ```shell + sudo systemctl start veilid-server.service + ``` + +6. (Optionally) configure the service to start at boot + + ```shell + sudo systemctl enable veilid-server.service + ``` diff --git a/doc/config/veilid-bootstrap-config.md b/doc/config/veilid-bootstrap-config.md new file mode 100644 index 00000000..7988de7c --- /dev/null +++ b/doc/config/veilid-bootstrap-config.md @@ -0,0 +1,33 @@ +# Veilid Server +# ============= +# +# Public Bootstrap Server Configuration +# +# ----------------------------------------------------------- + +--- +logging: + system: + enabled: true + level: debug + api: + enabled: true + level: debug + terminal: + enabled: false +core: + capabilities: + disable: ['TUNL','SGNL','RLAY','DIAL','DHTV','APPM'] + network: + upnp: false + dht: + min_peer_count: 2 + detect_address_changes: false + routing_table: + bootstrap: ['bootstrap.'] + protected_store: + insecure_fallback_directory: '/var/db/veilid-server/protected_store' + table_store: + directory: '/var/db/veilid-server/table_store' + block_store: + directory: '/var/db/veilid-server/block_store' \ No newline at end of file diff --git a/doc/config/veilid-dev-bootstrap-config.md b/doc/config/veilid-dev-bootstrap-config.md new file mode 100644 index 00000000..4cf4072e --- /dev/null +++ b/doc/config/veilid-dev-bootstrap-config.md @@ -0,0 +1,34 @@ +# Veilid Server +# ============= +# +# Private Development Bootstrap Server Configuration +# +# ----------------------------------------------------------- + +--- +logging: + system: + enabled: true + level: debug + api: + enabled: true + level: debug + terminal: + enabled: false +core: + capabilities: + disable: ['TUNL','SGNL','RLAY','DIAL','DHTV','APPM'] + network: + upnp: false + dht: + min_peer_count: 2 + detect_address_changes: false + routing_table: + bootstrap: ['bootstrap.'] + network_key_password: '' + protected_store: + insecure_fallback_directory: '/var/db/veilid-server/protected_store' + table_store: + directory: '/var/db/veilid-server/table_store' + block_store: + directory: '/var/db/veilid-server/block_store' \ No newline at end of file diff --git a/doc/config/veilid-dev-node-config.md b/doc/config/veilid-dev-node-config.md new file mode 100644 index 00000000..a77b135a --- /dev/null +++ b/doc/config/veilid-dev-node-config.md @@ -0,0 +1,34 @@ +# Veilid Server +# ============= +# +# Dev Node Configuration +# +# ----------------------------------------------------------- + +--- +logging: + system: + enabled: true + level: debug + api: + enabled: true + level: debug + terminal: + enabled: false +core: + capabilities: + disable: ['APPM'] + network: + upnp: false + dht: + min_peer_count: 10 + detect_address_changes: false + routing_table: + bootstrap: ['bootstrap.'] + network_key_password: '' + protected_store: + insecure_fallback_directory: '/var/db/veilid-server/protected_store' + table_store: + directory: '/var/db/veilid-server/table_store' + block_store: + directory: '/var/db/veilid-server/block_store' \ No newline at end of file diff --git a/doc/guide/guide.html b/doc/guide/guide.html index b2f641b2..7ec8bf31 100644 --- a/doc/guide/guide.html +++ b/doc/guide/guide.html @@ -14,7 +14,6 @@
early α docs
- please don't share publicly

Veilid Architecture Guide

diff --git a/doc/guide/guide.md b/doc/guide/guide.md index 6c5d63b8..58e57229 100644 --- a/doc/guide/guide.md +++ b/doc/guide/guide.md @@ -1,7 +1,3 @@ -# early α docs - -# please don't share publicly - # Veilid Architecture Guide - [From Orbit](#from-orbit) From 618b092e8b6640ab346a2caf002b4e740a613a4b Mon Sep 17 00:00:00 2001 From: TC Johnson Date: Thu, 21 Sep 2023 08:24:09 -0500 Subject: [PATCH 5/5] Add private or dev network setup docs Guides and config templates for use in setting up private Veilid networks for independent or development needs. --- BOOTSTRAP-SETUP.md | 20 ++++++++++--------- dev-setup/dev-network-setup.md | 2 +- ...trap-config.md => veilid-bootstrap-config} | 0 ...-config.md => veilid-dev-bootstrap-config} | 5 +++++ ...-node-config.md => veilid-dev-node-config} | 6 +++++- 5 files changed, 22 insertions(+), 11 deletions(-) rename doc/config/{veilid-bootstrap-config.md => veilid-bootstrap-config} (100%) rename doc/config/{veilid-dev-bootstrap-config.md => veilid-dev-bootstrap-config} (67%) rename doc/config/{veilid-dev-node-config.md => veilid-dev-node-config} (69%) diff --git a/BOOTSTRAP-SETUP.md b/BOOTSTRAP-SETUP.md index 1aeb6343..1f2ca219 100755 --- a/BOOTSTRAP-SETUP.md +++ b/BOOTSTRAP-SETUP.md @@ -14,12 +14,10 @@ Follow instructions in [INSTALL.md](./INSTALL.md) ## Configure Veilid as Bootstrap -**As root** - ### Stop the Veilid service ```shell -systemctl stop veilid-server.service +sudo systemctl stop veilid-server.service ``` ### Setup the config @@ -36,7 +34,7 @@ sudo -u veilid /bin/bash ### Generate a new keypair -Copy the output to secure storage. +Copy the output to secure storage such as a password manager. This information will be used in the next step and can be used for node recovery, moving to a different server, etc. ```shell veilid-server --generate-key-pair @@ -44,7 +42,7 @@ veilid-server --generate-key-pair ### Create new node ID and flush existing route table -Include the brackets [] when pasting the keys. Use the public key in the command. Secret key will be request interacitvly and will not echo when pasted. +Include the brackets [] when pasting the keys. Use the public key in the command. Secret key will be requested interactively and will not echo when pasted. ```shell veilid-server --set-node-id [PUBLIC_KEY] --delete-table-store @@ -52,18 +50,22 @@ veilid-server --set-node-id [PUBLIC_KEY] --delete-table-store ### Generate the DNS TXT record -Copy the output to secure storage. +Copy the output to secure storage. This information will be use to setup DNS records. ```shell veilid-server --dump-txt-record ``` -**Switch back to root** - ### Start the Veilid service +Disconnect from the Veilid user and start veilid-server.service. + ```shell -systemctl start veilid-server.service +exit +``` + +```shell +sudo systemctl start veilid-server.service ``` Optionally configure the service to start at boot `sudo systemctl enable veilid-server.service` diff --git a/dev-setup/dev-network-setup.md b/dev-setup/dev-network-setup.md index aac705c4..e5e822bb 100644 --- a/dev-setup/dev-network-setup.md +++ b/dev-setup/dev-network-setup.md @@ -16,7 +16,7 @@ This acts as a passphase to allow nodes to join the network. It is the mechanism ### Dev Bootstrap Server -Follow the steps detailed in [BOOTSTRAP-SETUP.md](../BOOTSTRAP-SETUP.md) using the dev bootstrap example [config](../doc/config/veilid-dev-bootstrap-config.md) for the *Setup the config* section. Set your network key on line 28. +Follow the steps detailed in [BOOTSTRAP-SETUP.md](../BOOTSTRAP-SETUP.md) using the dev bootstrap example [config](../doc/config/veilid-dev-bootstrap-config.md) for the *Setup the config* section. Set a _network_key_password_ in the config file. ### Dev Nodes diff --git a/doc/config/veilid-bootstrap-config.md b/doc/config/veilid-bootstrap-config similarity index 100% rename from doc/config/veilid-bootstrap-config.md rename to doc/config/veilid-bootstrap-config diff --git a/doc/config/veilid-dev-bootstrap-config.md b/doc/config/veilid-dev-bootstrap-config similarity index 67% rename from doc/config/veilid-dev-bootstrap-config.md rename to doc/config/veilid-dev-bootstrap-config index 4cf4072e..936effb3 100644 --- a/doc/config/veilid-dev-bootstrap-config.md +++ b/doc/config/veilid-dev-bootstrap-config @@ -3,6 +3,11 @@ # # Private Development Bootstrap Server Configuration # +# This config is templated to setup a bootstrap server with +# a network_key_password. Set the network key to whatever you +# like. Treat it like a password. Use the same network key in +# the config files for at least four nodes to establish an +# independent Veilid network for private or development uses. # ----------------------------------------------------------- --- diff --git a/doc/config/veilid-dev-node-config.md b/doc/config/veilid-dev-node-config similarity index 69% rename from doc/config/veilid-dev-node-config.md rename to doc/config/veilid-dev-node-config index a77b135a..f2bf161d 100644 --- a/doc/config/veilid-dev-node-config.md +++ b/doc/config/veilid-dev-node-config @@ -1,8 +1,12 @@ # Veilid Server # ============= # -# Dev Node Configuration +# Private Development Node Configuration # +# This config is templated to setup a Velid node with a +# network_key_password. Set the network key to whatever you +# set within your private bootstrap server's config. Treat it +# like a password. # ----------------------------------------------------------- ---