import this
daa680d6b8
* initialise tokenomics graph * generate reward version config graph * update tokenomics * edit typo * initialise release crunch release notes * operators update * add points to changelog * update version graph and selection * update iptables configuration * add features to changelog * comment redundant * address review comments * PR finish
189 lines
11 KiB
Plaintext
189 lines
11 KiB
Plaintext
import { Callout } from 'nextra/components';
|
||
import { Tabs } from 'nextra/components';
|
||
import { RunTabs } from 'components/operators/nodes/node-run-command-tabs';
|
||
import { VarInfo } from 'components/variable-info.tsx';
|
||
import { MigrateTabs } from 'components/operators/nodes/node-migrate-command-tabs';
|
||
import BuildInfo from 'components/outputs/command-outputs/nym-node-build-info.md';
|
||
import NymNodeHelp from 'components/outputs/command-outputs/nym-node-help.md';
|
||
import NymNodeRunHelp from 'components/outputs/command-outputs/nym-node-run-help.md';
|
||
import { AccordionTemplate } from 'components/accordion-template.tsx';
|
||
|
||
# Nym Node Setup & Run
|
||
|
||
This documentation page provides a guide on how to set up and run a [NYM NODE](../nym-node.mdx), along with explanations of available flags, commands, and examples.
|
||
|
||
## Current version
|
||
|
||
```sh
|
||
nym-node
|
||
Binary Name: nym-node
|
||
Build Timestamp: 2024-12-11T13:49:11.974104790Z
|
||
Build Version: 1.2.0
|
||
Commit SHA: a491e6a71a8cf862d77defd740a4ee8d65d8292a
|
||
Commit Date: 2024-12-11T10:28:47.000000000+01:00
|
||
Commit Branch: HEAD
|
||
rustc Version: 1.83.0
|
||
rustc Channel: stable
|
||
cargo Profile: release
|
||
```
|
||
|
||
{/* COMMENTING THIS OUT ASS WE HAVE TO FIGURE OUT HOW TO SHOW THE LATEST VERSION FROM MASTER BRANCH
|
||
<BuildInfo />
|
||
*/}
|
||
|
||
## Summary
|
||
|
||
|
||
<VarInfo/ >
|
||
|
||
To run a new node, you can simply execute the `nym-node` command without any flags. By default, the node will set necessary configurations. If you later decide to change a setting, you can use the `-w` flag.
|
||
|
||
The most crucial aspect of running the node is specifying the `--mode`. At the moment it can be only one of three: `mixnode`, `entry-gateway`, and `exit-gateway`.
|
||
|
||
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 <IPv4_ADDRESS> or <HOSTNAME> with the one corresponding to your node
|
||
# for http
|
||
http://<IPv4_ADDRESS>:8080/api/v1/roles
|
||
# or
|
||
http://<IPv4_ADDRESS>/api/v1/roles
|
||
|
||
# for reversed proxy/WSS
|
||
https://<HOSTNAME>/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 <IPv4_ADDRESS> or <HOSTNAME> with the one corresponding to your node
|
||
# for http
|
||
http://<IPv4_ADDRESS>:8080/api/v1/swagger/#/
|
||
# or
|
||
http://<IPv4_ADDRESS>/api/v1/swagger/#/
|
||
|
||
# for reversed proxy/WSS
|
||
https://<HOSTNAME>/api/v1/swagger/#/
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Help Command
|
||
|
||
There are a few changes from the individual binaries used in the past. For example by default `run` command does `init` function as well, local node `--id` will be set by default unless specified otherwise etcetera.
|
||
|
||
<Callout type="info" emoji="ℹ️">
|
||
You can always use `--help` flag to see the commands or arguments associated with a given command.
|
||
</Callout>
|
||
|
||
Run `./nym-node --help` to see all available commands:
|
||
|
||
<NymNodeHelp />
|
||
|
||
To list all available flags for each command, run `./nym-node <COMMAND> --help` for example `./nym-node run --help`:
|
||
|
||
<AccordionTemplate name="Command output">
|
||
<NymNodeRunHelp />
|
||
</AccordionTemplate>
|
||
|
||
<Callout type="warning" emoji="⚠️">
|
||
The Wireguard flags currently have limited functionality. From version `1.1.6` ([`v2024.9-topdeck`](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2024.9-topdeck)) wireguard is available and recommended to be switched on for nodes running as Gateways. Keep in mind that this option needs a bit of a special [configuration](configuration.md#wireguard-setup).
|
||
</Callout>
|
||
|
||
### Terms & Conditions
|
||
|
||
<Callout type="info" emoji="ℹ️">
|
||
From `nym-node` version `1.1.3` onward is required to accept [**Operators Terms & Conditions**](https://nymtech.net/terms-and-conditions/operators/v1.0.0) in order to be part of the active set. Make sure to read them before you add the flag.
|
||
</Callout>
|
||
|
||
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 a flag `--accept-operator-terms-and-conditions` added explicitly to `nym-node run` command every time. If you use [systemd](configuration.md#systemd) automation, add the flag to your service file's `ExecStart` line.
|
||
|
||
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
|
||
```
|
||
|
||
```sh
|
||
# substitude <PUBLIC_IP> 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.**
|
||
|
||
<Callout type="info" emoji="ℹ️">
|
||
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.
|
||
</Callout>
|
||
|
||
#### Essential Parameters & Variables
|
||
|
||
Running a `nym-node` in a `mixnode` mode requires less configuration than a full `exit-gateway` setup, we recommend operators to still follow through with all documented [configuration](configuration.md). Before you scroll down to syntax examples for the mode of your choice please familiarise yourself with the essential [paramters and variables](../../variables.mdx) convention we use in the guide.
|
||
|
||
<Callout>
|
||
To prevent over-flooding of our documentation we cannot provide with every single command syntax as there is a large combination of possibilities. Please read the [variables and parameters page](../../variables.mdx), use the explanation in `--help` option and common sence.
|
||
</Callout>
|
||
|
||
|
||
### 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`.
|
||
|
||
Please keep in mind that currently you can run only one functionality (`--mode`) per a `nym-node` instance. We are yet to finalise implement the multi-functionality solution under one node bonded to one Nyx account. Every `exit-gateway` can function as `entry-gateway` by default, not vice versa.
|
||
|
||
There is a simple default command to initialise and run your node: `./nym-node run --mode <MODE>`, however there quite a few parameters to be configured. When `nym-node` gets to be `run`, these parameters are read by the binary from the configuration file located at `.nym/nym-nodes/<ID>/config/config.toml`.
|
||
|
||
If an operator specifies any paramteres with optional flags alongside `run` command, these parameters passed in the option will take place over the ones in `config.toml` but they will not overwrite them by default. To overwrite them with the values passed with `run` command, a flag `-w` (`--write-changes`) must be added.
|
||
|
||
Alternatively operators can just open a text editor and change these values manually. After saving the file,don't forget to restart the node or reload and restart the service. If all values are setup correctly in `config.toml`, then operator can use as simple command as `nym-node run --mode <MODE> --accept-operators-terms-and-conditions`, or alternatively paste this command with a correct path to your binary to your `ExecStart` line into a [systemd `nym-node.service`](configuration.md#systemd) config file.
|
||
|
||
**Below is a step by step guide how to initialise and run `nym-node`. Each tab represents one functionality.**
|
||
|
||
<RunTabs />
|
||
|
||
<Callout>
|
||
**We recommend operators to setup an [automation](configuration.md#systemd) flow for their nodes, using systemd!**
|
||
|
||
In such case, you can `run` a node to initalise it or try if everything works, but then stop the proces and paste your entire `run` command syntax (below) to the `ExecStart` line of your `/etc/systemd/system/nym-node.service` and start the node as a [service](configuration.md#following-steps-for-nym-nodes-running-as-systemd-service).
|
||
</Callout>
|
||
|
||
### Migrate
|
||
|
||
<Callout type="warning">
|
||
Migration is a must for all deprecated nodes (`nym-mixnode`, `nym-gateway`). These binaries from version 1.1.35 (`nym-gateway`) and 1.1.37 (`nym-mixnode`) onwards will no longer have `init` command and `nym-node` is the only binary to use for `gateway` or `mixnode` fucntionalities.
|
||
|
||
**Nym cannot promise 100% serialisation for operators migrating from long outdated versions to the newest ones. If you are about to migrate, start with [`nym-node v1.1.0`](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2024.3-eclipse) and keep upgrading version by version all the way to the latest one.**
|
||
</Callout>
|
||
|
||
Operators who are about to migrate their nodes need to configure their [VPS](vps-setup.md) and setup `nym-node` which can be downloaded as a [pre-built binary](../binaries/pre-built-binaries.md) or compiled from [source](../binaries/building-nym.md).
|
||
|
||
To migrate a `nym-mixnode` or a `nym-gateway` to `nym-node` is fairly simple, use the `migrate` command with `--config-file` flag pointing to the original `config.toml` file, with a conditional argument defining which type of node this configuration belongs to. Examples are below.
|
||
|
||
Make sure to use `--deny-init` flag to prevent initialisation of a new node.
|
||
|
||
<MigrateTabs />
|
||
|
||
### Next steps
|
||
|
||
If there are any problems checkout the troubleshooting section or report an issue.
|
||
|
||
Follow up with [configuration](configuration.mdx) page for automation, reversed proxy setup and other tweaks, then head straight to [bonding](bonding.mdx) page to finalise your setup.
|