Nym Node Setup & Run
This documentation page provides a guide on how to set up and run a NYM NODE, along with explanations of available flags, commands, and examples.
Current version
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
Summary
Our documentation often refer to syntax annotated in <>
brackets. We use this expression for variables that are unique to each user (like path, local moniker, versions etcetra).
Any syntax in <>
brackets needs to be substituted with your correct name or version, without the <>
brackets. If you are unsure, please check our table of essential parameters and variables (opens in a new tab).
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 (opens in a new tab).
To determine which mode your node is running, you can check the :8080/api/v1/roles
endpoint. For example:
# 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:
# 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.
You can always use --help
flag to see the commands or arguments associated with a given command.
Run ./nym-node --help
to see all available commands:
Usage: nym-node [OPTIONS] <COMMAND>
Commands:
build-info Show build information of this binary
bonding-information Show bonding information of this node depending on its currently selected mode
node-details Show details of this node
migrate Attempt to migrate an existing mixnode or gateway into a nym-node
run Start this nym-node
sign Use identity key of this node to sign provided message
help Print this message or the help of the given subcommand(s)
Options:
-c, --config-env-file <CONFIG_ENV_FILE>
Path pointing to an env file that configures the nym-node and overrides any preconfigured values [env: NYMNODE_CONFIG_ENV_FILE_ARG=]
--no-banner
Flag used for disabling the printed banner in tty [env: NYMNODE_NO_BANNER=]
-h, --help
Print help
-V, --version
Print version
To list all available flags for each command, run ./nym-node <COMMAND> --help
for example ./nym-node run --help
:
Start this nym-node
Usage: nym-node run [OPTIONS]
Options:
--id <ID>
Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node]
--config-file <CONFIG_FILE>
Path to a configuration file of this node [env: NYMNODE_CONFIG=]
--accept-operator-terms-and-conditions
Explicitly specify whether you agree with the terms and conditions of a nym node operator as defined at <https://nymtech.net/terms-and-conditions/operators/v1.0.0> [env: NYMNODE_ACCEPT_OPERATOR_TERMS=]
--deny-init
Forbid a new node from being initialised if configuration file for the provided specification doesn't already exist [env: NYMNODE_DENY_INIT=]
--init-only
If this is a brand new nym-node, specify whether it should only be initialised without actually running the subprocesses [env: NYMNODE_INIT_ONLY=]
--local
Flag specifying this node will be running in a local setting [env: NYMNODE_LOCAL=]
--mode <MODE>
Specifies the current mode of this nym-node [env: NYMNODE_MODE=] [possible values: mixnode, entry-gateway, exit-gateway]
-w, --write-changes
If this node has been initialised before, specify whether to write any new changes to the config file [env: NYMNODE_WRITE_CONFIG_CHANGES=]
--bonding-information-output <BONDING_INFORMATION_OUTPUT>
Specify output file for bonding information of this nym-node, i.e. its encoded keys. NOTE: the required bonding information is still a subject to change and this argument should be treated only as a preview of future features [env: NYMNODE_BONDING_INFORMATION_OUTPUT=]
-o, --output <OUTPUT>
Specify the output format of the bonding information (`text` or `json`) [env: NYMNODE_OUTPUT=] [default: text] [possible values: text, json]
--public-ips <PUBLIC_IPS>
Comma separated list of public ip addresses that will be announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding [env: NYMNODE_PUBLIC_IPS=]
--hostname <HOSTNAME>
Optional hostname associated with this gateway that will be announced to the nym-api and subsequently to the clients [env: NYMNODE_HOSTNAME=]
--location <LOCATION>
Optional **physical** location of this node's server. Either full country name (e.g. 'Poland'), two-letter alpha2 (e.g. 'PL'), three-letter alpha3 (e.g. 'POL') or three-digit numeric-3 (e.g. '616') can be provided [env: NYMNODE_LOCATION=]
--http-bind-address <HTTP_BIND_ADDRESS>
Socket address this node will use for binding its http API. default: `0.0.0.0:8080` [env: NYMNODE_HTTP_BIND_ADDRESS=]
--landing-page-assets-path <LANDING_PAGE_ASSETS_PATH>
Path to assets directory of custom landing page of this node [env: NYMNODE_HTTP_LANDING_ASSETS=]
--http-access-token <HTTP_ACCESS_TOKEN>
An optional bearer token for accessing certain http endpoints. Currently only used for prometheus metrics [env: NYMNODE_HTTP_ACCESS_TOKEN=]
--expose-system-info <EXPOSE_SYSTEM_INFO>
Specify whether basic system information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_INFO=] [possible values: true, false]
--expose-system-hardware <EXPOSE_SYSTEM_HARDWARE>
Specify whether basic system hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_HARDWARE=] [possible values: true, false]
--expose-crypto-hardware <EXPOSE_CRYPTO_HARDWARE>
Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false]
--mixnet-bind-address <MIXNET_BIND_ADDRESS>
Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=]
--mixnet-announce-port <MIXNET_ANNOUNCE_PORT>
If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_MIXNET_ANNOUNCE_PORT=]
--nym-api-urls <NYM_API_URLS>
Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=]
--nyxd-urls <NYXD_URLS>
Addresses to nyxd chain endpoint which the node will use for chain interactions [env: NYMNODE_NYXD=]
--wireguard-enabled <WIREGUARD_ENABLED>
Specifies whether the wireguard service is enabled on this node [env: NYMNODE_WG_ENABLED=] [possible values: true, false]
--wireguard-bind-address <WIREGUARD_BIND_ADDRESS>
Socket address this node will use for binding its wireguard interface. default: `0.0.0.0:51822` [env: NYMNODE_WG_BIND_ADDRESS=]
--wireguard-announced-port <WIREGUARD_ANNOUNCED_PORT>
Port announced to external clients wishing to connect to the wireguard interface. Useful in the instances where the node is behind a proxy [env: NYMNODE_WG_ANNOUNCED_PORT=]
--wireguard-private-network-prefix <WIREGUARD_PRIVATE_NETWORK_PREFIX>
The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=]
--verloc-bind-address <VERLOC_BIND_ADDRESS>
Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=]
--verloc-announce-port <VERLOC_ANNOUNCE_PORT>
If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_VERLOC_ANNOUNCE_PORT=]
--entry-bind-address <ENTRY_BIND_ADDRESS>
Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=]
--announce-ws-port <ANNOUNCE_WS_PORT>
Custom announced port for listening for websocket client traffic. If unspecified, the value from the `bind_address` will be used instead [env: NYMNODE_ENTRY_ANNOUNCE_WS_PORT=]
--announce-wss-port <ANNOUNCE_WSS_PORT>
If applicable, announced port for listening for secure websocket client traffic [env: NYMNODE_ENTRY_ANNOUNCE_WSS_PORT=]
--enforce-zk-nyms <ENFORCE_ZK_NYMS>
Indicates whether this gateway is accepting only coconut credentials for accessing the mixnet or if it also accepts non-paying clients [env: NYMNODE_ENFORCE_ZK_NYMS=] [possible values: true, false]
--mnemonic <MNEMONIC>
Custom cosmos wallet mnemonic used for zk-nym redemption. If no value is provided, a fresh mnemonic is going to be generated [env: NYMNODE_MNEMONIC=]
--upstream-exit-policy-url <UPSTREAM_EXIT_POLICY_URL>
Specifies the url for an upstream source of the exit policy used by this node [env: NYMNODE_UPSTREAM_EXIT_POLICY=]
--open-proxy <OPEN_PROXY>
Specifies whether this exit node should run in 'open-proxy' mode and thus would attempt to resolve **ANY** request it receives [env: NYMNODE_OPEN_PROXY=] [possible values: true, false]
-h, --help
Print help
The Wireguard flags currently have limited functionality. From version 1.1.6
(v2024.9-topdeck
(opens in a new tab)) 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.
Terms & Conditions
From nym-node
version 1.1.3
onward is required to accept Operators Terms & Conditions (opens in a new tab) 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 (opens in a new tab) introducing the T&Cs or to Operator AMA with CEO Harry Halpin (opens in a new tab) 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 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):
# 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
# 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.
All commands with more options listed below include --accept-operator-terms-and-conditions
flag, read Terms & Conditions chapter above before executing these commands.
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. Before you scroll down to syntax examples for the mode of your choice please familiarise yourself with the essential paramters and variables convention we use in the guide.
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, use the explanation in --help
option and common sence.
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
config file.
Below is a step by step guide how to initialise and run nym-node
. Each tab represents one functionality.
If you run a nym-node
for the first time, you will need to specify a few parameters, please read the section Essential Parameters & Variables before you start and make sure that your nym-node
is up to date with the latest version (opens in a new tab).
Initialise and Run
To initialise and test run your node, use this command:
./nym-node run --id <ID> --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<HOSTNAME>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <LOCATION> --accept-operator-terms-and-conditions --wireguard-enabled true
If you prefer to have a generic local identifier set to default-nym-node
, skip --id
option.
We highly recommend to setup reverse proxy and WSS for nym-node
. If you haven't configured any of that, skip --hostname
flag.
In any case --public-ips
is a necessity for your node to bond to API and communicate with the internet.
Initialise only without running the node with --init-only
command:
Adding --init-only
option results in nym-node
initialising a configuration file config.toml
without running - a good option for an initial node setup. Remember that if you using this flag on a node which already has a config file, this will not over-write the values, unless used with a specified flag --write-changes
(-w
) - a good option for introducing changes to your config.toml
file.
./nym-node run --id <ID> --init-only --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "<HOSTNAME>" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <LOCATION> --wireguard-enabled true
In the example above we dropped --accept-operator-terms-and-conditions
as the flag must be added to a running command explicitly and it is not stored in the config, --init-only
will not run the node.
Deny init
--deny-init
was introduced as an additional safety for migration from legacy binaries to nym-node
to prevent operators initialise over existing nodes. For most of the operators, this flag is not needed.
In this example we run the node with custom --id
without initialising, using --deny-init
command:
./nym-node run --id <ID> --deny-init --mode exit-gateway --accept-operator-terms-and-conditions
We recommend operators to setup an automation 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.
Migrate
Legacy binaries nym-mixnode
and nym-gateway
had been deprecated, nym-node
is the only binary to use for gateway
or mixnode
functionalities!
From 2024.14-crunch
release (nym-node v1.2.0
) onward, nym-node
binary does not have migrate
command included. In case you are still running a legacy node and want to migrate, download (opens in a new tab) an older nym-node
binary and upgrade to the latest after migrating.
Furthermore, giving that legacy nodes had been deprecated for several months, Nym cannot promise 100% serialisation for operators migrating from long outdated versions. If you are about to migrate, start with nym-node v1.1.0
(opens in a new tab) and keep upgrading version by version all the way to the latest one.
Operators who are about to migrate their nodes need to configure their VPS and setup nym-node
which can be downloaded as a pre-built binary or compiled from source.
To migrate a nym-mixnode
or a nym-gateway
to nym-node
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. The exact steps are below.
Make sure to use --deny-init
flag to prevent initialisation of a new node.
Migrate your nym-gateway
to nym-node --mode entry-gateway
or --mode exit-gateway
using these commands:
1. Move relevant info from config.toml
./nym-node migrate --config-file ~/.nym/gateways/<ID>/config/config.toml gateway
2. Initialise with new nym-node
config chosing one of the options below:
- as
entry-gateway
:
./nym-node run --id <ID> --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname <HOSTNAME> --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <LOCATION> --accept-operator-terms-and-conditions --wireguard-enabled true
- or as
exit-gateway
:
./nym-node run --id <ID> --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname <HOSTNAME> --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location <LOCATION> --accept-operator-terms-and-conditions --wireguard-enabled true
After you upgraded your node to the latest release of nym-node
, make sure that you also follow the steps to migrate your node in the Mixnet smart contract, othewise your node will never receive any rewards.
Next steps
If there are any problems checkout the troubleshooting section or report an issue.
Follow up with configuration page for automation, reversed proxy setup and other tweaks, then head straight to bonding page to finalise your setup.