[DOCs/operators]: Updates v2024.6-chomp and T&Cs (#4674)

* initialise updates and ToC * add toc flag * changelog and node black-xit improvement * add node-api-check option * syntax fix * syntax fix * change CI/CD with git reset * fix typo * add T&C AMA explanation link - ready for review * fix typo * resolve review comments * add ToC standalone page * minor edit - ready to go
nymtech · Jun 27, 2024 · 789914b · 789914b
1 parent fec5706
commit 789914b
Show file tree

Hide file tree

Showing 12 changed files with 382 additions and 56 deletions.
diff --git a/.github/workflows/cd-docs.yml b/.github/workflows/cd-docs.yml
@@ -41,8 +41,8 @@ jobs:
 # This is a workaround replacement which builds on the last working commit b332a6b55668f60988e36961f3f62a794ba82ddb and then on current branch
       - name: Save current branch to ~/current_branch
         run: git rev-parse --abbrev-ref HEAD > ~/current_branch
-      - name: Git pull & switch to b332a6b55668f60988e36961f3f62a794ba82ddb
-        run: git pull && git checkout b332a6b55668f60988e36961f3f62a794ba82ddb
+      - name: Git pull, reset & switch to b332a6b55668f60988e36961f3f62a794ba82ddb
+        run: git pull && git reset --hard && git checkout b332a6b55668f60988e36961f3f62a794ba82ddb
       - name: Build all projects in documentation/ & move to ~/dist/docs/ from b332a6b55668f60988e36961f3f62a794ba82ddb
         run: cd documentation && ./build_all_to_dist.sh
 

diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
@@ -46,8 +46,8 @@ jobs:
 # This is a workaround replacement which builds on the last working commit b332a6b55668f60988e36961f3f62a794ba82ddb and then on current branch
       - name: Save current branch to ~/current_branch
         run: git rev-parse --abbrev-ref HEAD > ~/current_branch
-      - name: Git pull & switch to b332a6b55668f60988e36961f3f62a794ba82ddb
-        run: git pull && git checkout b332a6b55668f60988e36961f3f62a794ba82ddb
+      - name: Git pull, reset & switch to b332a6b55668f60988e36961f3f62a794ba82ddb
+        run: git pull && git reset --hard && git checkout b332a6b55668f60988e36961f3f62a794ba82ddb
       - name: Build all projects in documentation/ & move to ~/dist/docs/ from b332a6b55668f60988e36961f3f62a794ba82ddb
         run: cd documentation && ./build_all_to_dist.sh
 

diff --git a/20240411-NymVPN-May 2024 Marseille meetup.pdf b/20240411-NymVPN-May 2024 Marseille meetup.pdf
diff --git a/documentation/operators/book.toml b/documentation/operators/book.toml
@@ -35,6 +35,7 @@ performance_validator = "http://validator.performance.nymte.ch/"
 performance_testing_release = "v2024.2-fast-and-furious-v2"
 # dependencies
 prometheus_latest_version = "v2.50.1"
+toc_page = "https://nymtech.net/terms-and-conditions/operators/v1.0.0"
 
 [preprocessor.last-changed]
 command = "mdbook-last-changed"

diff --git a/documentation/operators/src/SUMMARY.md b/documentation/operators/src/SUMMARY.md
@@ -84,5 +84,6 @@
 ---
 # Misc.
 - [Code of Conduct](coc.md)
+- [Terms & Conditions](toc.md)
 - [Licensing](licensing.md)
 ---
diff --git a/documentation/operators/src/changelog.md b/documentation/operators/src/changelog.md
diff --git a/documentation/operators/src/nodes/setup.md b/documentation/operators/src/nodes/setup.md
@@ -24,30 +24,36 @@ To run a new node, you can simply execute the `nym-node` command without any fla
 
 The most crucial aspect of running the node is specifying the `--mode`, which can be one of three: `mixnode`, `entry-gateway`, and `exit-gateway`.
 
-Currently `nym-node` binary enables to run only one `--mode` at a time. In the future the operators will be able to specify multiple modes within one `nym-node`. Our goal is to have as many nodes each running all the available modes enabled and let the Nym API to position the node acoording the network needs in the beginning of each epoch.
+Currently the `nym-node` binary can only be run in a single `--mode` at any one time. In the future however, operators will be able to specify multiple modes that a single `nym-node` binary can run. Our goal is to have as many nodes as possible enabling multiple modes, and allow the Nym API to position the node according the network's needs in the beginning of each epoch.
 
 Every `exit-gateway` mode is basically an `entry-gateway` with NR (Network Requester) and IPR (IP Packet Router) enabled. This means that every `exit-gateway` is automatically seen as an `entry-gateway` but not the opposite.
 
 Gateway operators can check out the node performance, connectivity and much more in our new tool [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/).
 
 To determine which mode your node is running, you can check the `:8080/api/v1/roles` endpoint. For example:
-```
+```sh
+# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
 # for http
-http://<IP_ADDRESS>:8080/api/v1/roles
+http://<NODE_IP_ADDRESS>:8080/api/v1/roles
+# or
+http://<NODE_IP_ADDRESS>/api/v1/roles
 
-# for https reversed proxy
-https://<DOMAIN>/api/v1/roles
+# for reversed proxy/WSS
+https://<NODE_DOMAIN>/api/v1/roles
 ```
 
 Everything necessary will exist on your node by default. For instance, if you're running a mixnode, you'll find that a NR (Network Requester) and IPR (IP Packet Router) address exist, but they will be ignored in `mixnode` mode.
 
 For more information about available endpoints and their status, you can refer to:
-```
+```sh
+# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
 # for http
-http://<IP>:8080/api/v1/swagger/#/
+http://<NODE_IP_ADDRESS>:8080/api/v1/swagger/#/
+# or
+http://<NODE_IP_ADDRESS>/api/v1/swagger/#/
 
-# for https reversed proxy
-https://<DOMAIN>/api/v1/swagger/#/
+# for reversed proxy/WSS
+https://<NODE_DOMAIN>/api/v1/swagger/#/
 ```
 
 ## Usage
@@ -88,6 +94,7 @@ Some of the most useful flags and their explanation:
 
 ~~~admonish example collapsible=true title="Flags explanation:"
 - `--id <YOUR_ID>`: Local identifier of your node. This `<ID>` determines your config path located at `~/.nym/nym-nodes/<ID>/config/config.toml`, default value is `default-nym-node`
+- `--accept-operator-terms-and-conditions`:  Explicitly specify whether you agree with the terms and conditions of a nym node operator as defined at [nymtech.net/terms-and-conditions/operators/v1.0.0]({{toc_page}})
 - `--config-file <PATH>`: Used for the migrate command to indicate the location of the existing node config file. Default path is `~/.nym/nym-nodes/default-nym-node/config/config.toml`
 - `--deny-init`: Use this flag to prevent a new node from being initialized. It's recommended to use this after the first run to avoid accidental spinning up of a second node.
 - `--init-only`: Use this flag if you want to set up a node without starting it.
@@ -99,10 +106,46 @@ Some of the most useful flags and their explanation:
 - `--expose-crypto-hardware <true/false>`: Sets your crypto hardware info visibility on the network.
 ~~~
 
+### Terms & Conditions
+
+```admonish info
+From `nym-node` version `1.1.3` onward is required to accept [**Operators Terms & Conditions**]({{toc_page}}) in order to be part of the active set. Make sure to read them before you add the flag.
+```
+
+There has been a long ongoing discussion whether and how to apply Terms and Conditions for Nym network operators, with an aim to stay aligned with the philosophy of Free Software and provide legal defense for both node operators and Nym developers. To understand better the reasoning behind this decision, you can listen to the first [Nym Operator Town Hall](https://www.youtube.com/live/7hwb8bAZIuc?si=3mQ2ed7AyUA1SsCp&t=915) introducing the T&Cs or to [Operator AMA with CEO Harry Halpin](https://www.youtube.com/watch?v=yIN-zYQw0I0) from June 4th, 2024, explaining pros and cons of T&Cs implementation.
+
+Accepting T&Cs is done via an explicit flag `--accept-operator-terms-and-conditions` added to `nym-node run` command.
+
+To check whether any node has T&Cs accepted or not can be done by querying Swagger API endpoint `/auxiliary_details` via one of these ports (depending on node setup):
+```sh
+# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
+http://<NODE_IP_ADDRESS>:8080/api/v1/auxiliary_details
+https://<NODE_DOMAIN>/api/v1/auxiliary_details
+http://<NODE_IP_ADDRESS>/api/v1/auxiliary_details
+```
+
+~~~admonish example collapsible=true title="Example of `/auxiliary_details` query"
+```sh
+# substitude <NODE_IP_ADDRESS> with a real one
+curl -X 'GET' \
+  'http://<NODE_IP_ADDRESS>:8080/api/v1/auxiliary-details' \
+  -H 'accept: application/json'
+
+{
+  "location": "Kurdistan",
+  "accepted_operator_terms_and_conditions": true
+}
+```
+~~~
+
 ### Commands & Examples
 
 **`nym-node` introduces a default human readible ID (local only) `default-nym-node`, which is used if there is not an explicit custom `--id <ID>` specified. All configuration is stored in `~/.nym/nym-nodes/default-nym-node/config/config.toml` or `~/.nym/nym-nodes/<ID>/config/config.toml` respectively.**
 
+```admonish info
+All commands with more options listed below include `--accept-operator-terms-and-conditions` flag, read [Terms & Conditions](#terms--conditions) chapter above before executing these commands.
+```
+
 ### Initialise & Run
 
 When we use `run` command the node will do `init` as well, unless we specify with a flag `--deny-init`. Below are some examples of initialising and running `nym-node` with different modes (`--mode`) like `mixnode`, `entry-gateway`, `exit-gateway`.
@@ -121,15 +164,13 @@ To prevent over-flooding of our documentation we cannot provide with every singl
 
 #### Mode: `exit-gateway`
 
-As part of the transition, `allowed.list` on Exit Gateway embedded Network Requester was depreciated.
-
 **Initialise and run** in one command:
 ```sh
 # simple default
 ./nym-node  run  --mode exit-gateway
 
 # with other options
-./nym-node run --id <ID> --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <COUNTRY_FULL_NAME> --wireguard-enabled false
+./nym-node run --id <ID> --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <COUNTRY_FULL_NAME> --accept-operator-terms-and-conditions --wireguard-enabled false
 
 # <YOUR_DOMAIN> is in format without 'https://' prefix
 # <COUNTRY_FULL_NAME> is format like 'Jamaica',  or two-letter alpha2 (e.g. 'JM'), three-letter alpha3 (e.g. 'JAM') or three-digit numeric-3 (e.g. '388') can be provided.
@@ -143,7 +184,7 @@ As part of the transition, `allowed.list` on Exit Gateway embedded Network Reque
 ./nym-node run --init-only --mode exit-gateway
 
 # with a custom `--id` and other options
-./nym-node run --id <ID> --init-only --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <COUNTRY_FULL_NAME> --wireguard-enabled false
+./nym-node run --id <ID> --init-only --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <COUNTRY_FULL_NAME> --accept-operator-terms-and-conditions --wireguard-enabled false
 
 # <YOUR_DOMAIN> is in format without 'https://' prefix
 # <COUNTRY_FULL_NAME> is format like 'Jamaica',  or two-letter alpha2 (e.g. 'JM'), three-letter alpha3 (e.g. 'JAM') or three-digit numeric-3 (e.g. '388') can be provided.
@@ -152,7 +193,7 @@ As part of the transition, `allowed.list` on Exit Gateway embedded Network Reque
 
 Run the node with custom `--id` without initialising, using `--deny-init` command
 ```sh
-./nym-node run --id <ID> --deny-init --mode exit-gateway
+./nym-node run --id <ID> --deny-init --mode exit-gateway --accept-operator-terms-and-conditions
 ```
 
 #### Mode: `entry-gateway`
@@ -164,12 +205,12 @@ Run the node with custom `--id` without initialising, using `--deny-init` comman
 
 Initialise only with a custom `--id` and `--init-only` command:
 ```sh
-./nym-node run --id <ID> --init-only --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789
+./nym-node run --id <ID> --init-only --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --accept-operator-terms-and-conditions
 ```
 
 Run the node with custom `--id` without initialising:
 ```sh
-./nym-node run --id <ID> --deny-init --mode entry-gateway
+./nym-node run --id <ID> --deny-init --mode entry-gateway --accept-operator-terms-and-conditions
 ```
 
 #### Mode: `mixnode`
@@ -181,17 +222,17 @@ Run the node with custom `--id` without initialising:
 
 Initialise only with a custom `--id` and `--init-only` command:
 ```sh
-./nym-node run --id <ID> --init-only --mode mixnode --verloc-bind-address 0.0.0.0:1790 --public-ips "$(curl -4 https://ifconfig.me)"
+./nym-node run --id <ID> --init-only --mode mixnode --verloc-bind-address 0.0.0.0:1790 --public-ips "$(curl -4 https://ifconfig.me)" --accept-operator-terms-and-conditions
 ```
 
 Run the node with custom `--id` without initialising:
 ```sh
-./nym-node run --id <ID> --deny-init --mode mixnode
+./nym-node run --id <ID> --deny-init --mode mixnode --accept-operator-terms-and-conditions
 ```
 
 Run the node with custom `--id` without initialising:
 ```sh
-./nym-node run --id <ID> --deny-init --mode entry-gateway
+./nym-node run --id <ID> --deny-init --mode entry-gateway --accept-operator-terms-and-conditions
 ```
 
 ### Migrate
@@ -212,16 +253,19 @@ Make sure to use `--deny-init` flag to prevent initialisation of a new node.
 ./nym-node migrate --config-file ~/.nym/mixnodes/<MIXNODE_ID>/config/config.toml mixnode
 
 # initialise with the new nym-node config
-./nym-node run --mode mixnode --id <NYM-NODE_ID> --deny-init
+./nym-node run --mode mixnode --id <NYM-NODE_ID> --accept-operator-terms-and-conditions
 ```
 
 #### Mode: `entry-gateway` and `exit-gateway`
 ```sh
 # move relevant infor from config.toml
 ./nym-node migrate --config-file ~/.nym/gateways/<GATEWAY_ID>/config/config.toml gateway
 
-# initialise with the new nym-node config
-./nym-node run --mode exit-gateway --id <NYM-NODE_ID> --deny-init # or change to entry-gateway
+# initialise with the new nym-node config - entry-gateway
+./nym-node run --mode entry-gateway --id <NYM-NODE_ID> --accept-operator-terms-and-conditions
+
+# or as exit-gateway
+./nym-node run --id <NYM-NODE_ID> --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<YOUR_DOMAIN>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <COUNTRY_FULL_NAME> --accept-operator-terms-and-conditions --wireguard-enabled false
 ```
 
 ### Next steps

diff --git a/documentation/operators/src/sandbox.md b/documentation/operators/src/sandbox.md
@@ -8,7 +8,7 @@ Below are steps to [setup your environment](#sandbox-environment-setup) and an i
 This page is for Nym node operators. If you want to run NymVPN CLI over Sandbox testnet, visit our [developers portal](https://nymtech.net/developers/nymvpn/cli.html#testnet-environment).
 ```
 
-## Sanbox Environment Setup
+## Sandbox Environment Setup
 
 > Any syntax in `<>` brackets is a user's unique variable. Exchange with a corresponding name without the `<>` brackets.
 
@@ -40,9 +40,9 @@ curl -o sandbox.env -L https://raw.githubusercontent.com/nymtech/nym/develop/env
 ![](images/sandbox.png)
 
 ~~~admonish tip
-1. If you [built Nym from source](building-nym.md), you already have `sanbox.env` as a part of the monorepo (`nym/envs/sandbox.env`). Giving that you are likely to run `nym-node` from `nym/target/release`, the flag will look like this `--config-env-file ../../envs/sandbox.env`
+1. If you [built Nym from source](building-nym.md), you already have `sandbox.env` as a part of the monorepo (`nym/envs/sandbox.env`). Giving that you are likely to run `nym-node` from `nym/target/release`, the flag will look like this `--config-env-file ../../envs/sandbox.env`
 
-2. You can export the path to `sanbox.env` to your enviromental variables:
+2. You can export the path to `sandbox.env` to your enviromental variables:
 ```sh
 export NYMNODE_CONFIG_ENV_FILE_ARG=<PATH/TO/sandbox.env>
 ```

diff --git a/documentation/operators/src/testing/node-api-check.md b/documentation/operators/src/testing/node-api-check.md
@@ -12,26 +12,32 @@ Besides that, Gateway operators can check out their node performance, connectivi
 ### Basic API usage
 
 For information about available endpoints and their status, you can refer to:
-```
+```sh
+# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
 # for http
-http://<IP>:8080/api/v1/swagger/#/
+http://<NODE_IP_ADDRESS>:8080/api/v1/swagger/#/
+# or
+http://<NODE_IP_ADDRESS>/api/v1/swagger/#/
 
-# for https reversed proxy
-https://<DOMAIN>/api/v1/swagger/#/
+# for reversed proxy/WSS
+https://<NODE_DOMAIN>/api/v1/swagger/#/
 ```
 
 For example to determine which mode your node is running, you can check `:8080/api/v1/roles` endpoint:
-```
+```sh
+# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
 # for http
-http://<IP_ADDRESS>:8080/api/v1/roles
+http://<NODE_IP_ADDRESS>:8080/api/v1/roles
+# or
+http://<NODE_IP_ADDRESS>/api/v1/roles
 
-# for https reversed proxy
-https://<DOMAIN>/api/v1/roles
+# for reversed proxy/WSS
+https://<NODE_DOMAIN>/api/v1/roles
 ```
 
 ## `node_api_check.py`
 
-To make this a bit easier, we made a CLI tool quering all vailable API endpoints based on node `Identity Key` (further denoted as `<ID_KEY>`) called `node_api_check.py`. To diagnose your node performance, whether by yourself or by sharing an output in our [operator channel](https://matrix.to/#/#operators:nymtech.chat), this tool provides you with a quick overview of live data. We recommend to run this checker alongside [`nym_gateway_probe`](gateway-probe.md) to triage both performance and an actual routing.
+To make this a bit easier, we made a CLI tool querying all available API endpoints based on node `Identity Key` (further denoted as `<ID_KEY>`) called `node_api_check.py`. To diagnose your node performance, whether by yourself or by sharing an output in our [operator channel](https://matrix.to/#/#operators:nymtech.chat), this tool provides you with a quick overview of live data. We recommend to run this checker alongside [`nym_gateway_probe`](gateway-probe.md) to triage both performance and an actual routing.
 
 Besides querying any bonded node APIs, `nym_api_check` has a function counting all existing nodes in provided version.
 
@@ -43,7 +49,7 @@ Besides querying any bonded node APIs, `nym_api_check` has a function counting a
 
 1. Start with installing Python3:
 ```sh
-sudo apt install Python3
+sudo apt install python3
 ```
 
 2. Make sure Python3 is your default Python version:
@@ -52,6 +58,7 @@ update-alternatives --install  /usr/bin/python python /usr/bin/python3 1
 
 # controll
 python --version
+
 # should return higher than 3
 ```
 
@@ -100,14 +107,14 @@ When you want to see all the options connected to a command, add a `--help` flag
 ```
 ~~~
 
-The most common usage may be `./node_api_check.py query_stats <ID_KEY>` where `<ID_KEY>` is required, sustitute it with node Identity Key.
+The most common usage may be `./node_api_check.py query_stats <ID_KEY>` where `<ID_KEY>` is required, substitute it with node Identity Key.
 
 **Optional arguments**
 
 | Flag                   | Shortcut | Description                                                 |
 | :---                   |     :---      | :---                                                        |
 | `--markdown`           |     `-m`      | returns output in markdown format                           |
-| `--no_routing_history` |     `-n`      | returns output without routing history which can be lenghty |
+| `--no_routing_history` |     `-n`      | returns output without routing history which can be lengthy |
 | `--output`             |     `-o`      | exports output to a file, possible to add a target path     |
 
 #### `version_count`

diff --git a/documentation/operators/src/toc.md b/documentation/operators/src/toc.md
@@ -0,0 +1,9 @@
+# Terms and Conditions
+
+With `nym-node` version `1.1.3`, NymTech SA introduced [**Operators Terms & Conditions**]({{toc_page}}) for operators who want their nodes to become a part of the active set of Nym Mixnet.
+
+There has been a long ongoing discussion whether and how to apply Terms and Conditions for Nym network operators, with an aim to stay aligned with the philosophy of Free Software and provide legal defense for both node operators and Nym developers. To understand better the reasoning behind this decision, you can listen to the first [Nym Operator Town Hall](https://www.youtube.com/live/7hwb8bAZIuc?si=3mQ2ed7AyUA1SsCp&t=915) introducing the T&Cs or to [Operator AMA with CEO Harry Halpin](https://www.youtube.com/watch?v=yIN-zYQw0I0) from June 4th, 2024, explaining pros and cons of T&Cs implementation.
+
+Accepting T&Cs is done via an explicit flag `--accept-operator-terms-and-conditions` added to `nym-node run` command.
+
+More information on how to setup your node or check whether any node has T&C accepted can be found in [`nym-node` setup guide](nodes/setup.md#terms--conditions).