Maintenance

ℹ️

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).

Useful commands

--no-banner: Adding --no-banner startup flag will prevent Nym banner being printed even if run in tty environment.
build-info: A build-info command prints the build information like commit hash, rust version, binary version just like what command --version does. However, you can also specify an --output=json flag that will format the whole output as a json, making it an order of magnitude easier to parse.

For example ./target/debug/nym-network-requester --no-banner build-info --output json will return:

{"binary_name":"nym-network-requester","build_timestamp":"2023-07-24T15:38:37.00657Z","build_version":"1.1.23","commit_sha":"c70149400206dce24cf20babb1e64f22202672dd","commit_timestamp":"2023-07-24T14:45:45Z","commit_branch":"feature/simplify-cli-parsing","rustc_version":"1.71.0","rustc_channel":"stable","cargo_profile":"debug"}

Configure your firewall

Although your nym-node or validator (denoted as <NODE>) is now ready to receive traffic, your server may not be. The following commands will allow you to set up a firewall using ufw.

SSH to your server as root or become one running sudo -i or su. If you prefer to administrate your VPS from a user environment, supply the commands with prefix sudo.

1. Start with setting up the essential tools on your server.

Get your system up to date

apt update -y && apt --fix-broken install

Install dependencies

apt -y install ca-certificates jq curl wget ufw jq tmux pkg-config build-essential libssl-dev git

Double check ufw is installed correctly

apt install ufw --fix-missing

2. Configure your firewall using Uncomplicated Firewall (UFW)

For a nym-node or Nyx validator to recieve traffic, you need to open ports on the server. The following commands will allow you to set up a firewall using ufw.

Check if you have ufw installed:

ufw version

If it's not installed, install with:

apt install ufw -y

Enable ufw

ufw enable

Check the status of the firewall

ufw status

3. Open all needed ports to have your firewall for `nym-node` working correctly

In case of reverse proxy setup add:

ufw allow 443/tcp

Re-check the status of the firewall:

ufw status

For more information about your node's port configuration, check the port reference table below.

Backup a node

Anything can happen to the server on which your node is running. To back up your nym-node keys and configuration protects the operators against the negative impact of unexpected events. To restart your node on another server, two essential pieces are needed:

Node keys to initialise the same node on a new VPS
Access to the bonding Nym account (wallet seeds) to edit the IP on smart contract

Assuming that everyone access their wallets from local machine and does not store their seeds on VPS, point 2. should be a given. To backup your nym-node keys and configuration in the easiest way possible, copy the entire config directory .nym from your VPS to your local desktop, using a special copy command scp:

⚠️

Never store your mnemonic seed anywhere online nor do not share it with anyone!

1. Create a directory where you want to store your backup

mkdir -pv <PATH_TO_TARGET_DIRECTORY>

2. Copy configuration folder `.nym` from your VPS to your newly created backup directory

scp -r <SOURCE_USER_NAME>@<SOURCE_HOST_ADDRESS>:~/.nym/nym-nodes/<ID> <PATH_TO_TARGET_DIRECTORY>

3. Verify the success of the backup

The scp command should print logs, an operator can see directly whether it was successful or if it encountered any error. However, double check that all your needed configuration is in the backup target directory.

Restoring a node

In case your VPS shut down and you have a backup of your node keys and access to your bonding wallet, you can easily restore your node on another server without losing your delegation.

1. Prepare new VPS

On VPS: Do all preliminary steps needed to run a nym-node.
On VPS: Create a .nym/nym-nodes configuration folder:

mkdir -pv ~/.nym/nym-nodes

2. Restore your node configuration

From machine where your node is backed up (usually local desktop): Copy the folder with your node keys and configuration to the newly created folder on your VPS using scp command. Make sure to grab the entire nym-node configuration folder, which is called after your local nym-node identifier (<ID>), the -r (recursive) flag will take care of all sub-directories and their content:

scp -r <PATH_TO_LOCAL_NODE_CONFIGURATION_FOLDER> <VPS_USER_NAME>@<VPS_HOST_ADDRESS>:~/.nym/nym-nodes/

3. Configure your node on the new VPS

Edit ~/.nym/nym-nodes/<ID>/config/config.toml config with the new listening address IP - it's the one under the header [host], called public_ips = [<PUBLIC_IPS>,] and add your new location (field location = <LOCATION>, formats 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). You can see your IP by running a command echo "$(curl -4 https://ifconfig.me)".
Try to run the node and see if everything works.
Setup the systemd automation (don't forget to add the terms and conditions flag) to ExecStart command, reload the daemon and run the service.

4. Change the node smart contract info via the wallet interface

Open Nym Wallet, go to Bonding, open Settings and change Host value to the new nym-node IP address. Otherwise the keys will point to the old IP address in the smart contract, and the node will not be able to be connected, and it will fail up-time checks, returning zero performance.

Moving a node

In case of a need to move a Nym Node from one machine to another and avoiding to lose the delegation, here are few steps how to do it.

1. Prepare both servers

Assuming both machines are remote VPS.

Make sure your ~/.ssh/<SSH_KEY>.pub is in both of the servers ~/.ssh/authorized_keys file
Create a nym-node folder in the target VPS. SSH in from your terminal and run:

# in case none of the nym configs was created previously
mkdir ~/.nym
 
#in case no `nym-node` was initialized previously
mkdir ~/.nym/nym-nodes

2. Move the node data and keys to the new machine

Open your local terminal (as that one's ssh key is authorized in both of the VPS) and run:

scp -r -3 <SOURCE_USER_NAME>@<SOURCE_HOST_ADDRESS>:~/.nym/nym-nodes <TARGET_USER_NAME>@<TARGET_HOST_ADDRESS>:~/.nym/nym-nodes/

3. Open new/target VPS terminal and configure the node

Edit ~/.nym/nym-nodes/<ID>/config/config.toml config with the new listening address IP - it's the one under the header [host], called public_ips = [<PUBLIC_IPS>,] and add your new location (field location = <LOCATION>, formats 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). You can see your IP by running a command echo "$(curl -4 https://ifconfig.me)".
Try to run the node and see if everything works.
Setup the systemd automation (don't forget to add the terms and conditions flag) to ExecStart command, reload the daemon and run the service. If you want to use the exact same service config file, you can also copy it from one VPS to another following the same logic by opening your local terminal (as that one's ssh key is authorized in both of the VPS) and running:

scp -r -3 <SOURCE_USER_NAME>@<SOURCE_HOST_ADDRESS>:/etc/systemd/system/nym-node.service <TARGET_USER_NAME>@<TARGET_HOST_ADDRESS>:/etc/systemd/system/nym-node.service

4. Change the node smart contract info via the wallet interface

Open Nym Wallet, go to Bonding, open Settings and change Host value to the new nym-node IP address. Otherwise the keys will point to the old IP address in the smart contract, and the node will not be able to be connected, and it will fail up-time checks, returning zero performance.
Make sure to stop the old node.

Rename Node Local Identifier

Local node identifier, denoted as <ID> accross the documentation (not the identity key) is a name chosen by operators which defines where the nodes configuration data will be stored, where the ID determines the path to ~/.nym/nym-nodes/<ID>/. This ID is never shared on the network.

When running a nym-node, a local identifier specified with a flag --ID <ID> is no longer necessary. Nodes without a specified ID will be assigned a default ID default-nym-node. This streamlines node management, particularly for operators handling multiple nodes via ansible and other automation scripts, as all data is stored at ~/.nym/nym-nodes/default-nym-node.

If you already operate a nym-node and wish to change the local ID to default-nym-node or anything else, follow the steps below to do so.

💡

In the example we use default-nym-node as a target <ID>, if you prefer to use another name, edit the syntax in the commands accordingly.

1. Copy the configuration directory to the new one

cp -r  ~/.nym/nym-nodes/<ID> ~/.nym/nym-nodes/default-nym-node/

2. Rename all original `<ID>` occurrences in `config.toml` to `default-nym-node`

# check occurences of the <SOURCE_ID>
grep -ir  "<ID>" ~/.nym/nym-nodes/default-nym-node/*

⚠️

If your node <ID> was too generic (like 'gateway' etc) and it occurs elsewhere than just a custom value, do not use sed command but rewrite the values manually using a text editor!

If you are clear with occurrence found above, move on using sed command:

sed -i -e "s/<ID>/default-nym-node/g" ~/.nym/nym-nodes/default-nym-node/config/config.toml

If you are not sure and want to play it safe, do it manually by opening config.toml and rewriting each occurence of <ID>:

nano ~/.nym/nym-nodes/default-nym-node/config/config.toml

3. Validate by rechecking the config file content

# either re-run
grep -ir  "<ID>" ~/.nym/nym-nodes/default-nym-node/*
 
# or by reading the config file
less ~/.nym/nym-nodes/default-nym-node/config/config.toml

Pay extra attention to the hostname line. In case its value was somehow correlated with the source <ID> string you may need to correct it back

4. Reload your systemd service daemon and restart the service

If you chosen default-nym-node as an ID, you can drop --id flag from node running commands, otherwise specify with the new <ID>.
If automation isn't your thing, simply reboot the node. To automate with systemd is highly recommended.

5. Be careful before removing old config

If you double-checked that everything works fine, you can consider removing your old config directory

Ports

All <NODE>-specific port configuration can be found in $HOME/.nym/<NODE>/<YOUR_ID>/config/config.toml. If you do edit any port configs, remember to restart your client and node processes.

Nym Node Port Reference

Default port	Use
`1789`	Listen for Mixnet traffic
`1790`	Listen for VerLoc traffic
`8080`	Metrics http API endpoint
`1789`	Listen for Mixnet traffic
`9000`	Listen for Client traffic
`9001`	WSS
`51822/udp`	WireGuard

Validator Port Reference

All validator-specific port configuration can be found in $HOME/.nymd/config/config.toml. If you do edit any port configs, remember to restart your validator.

Default port	Use
1317	REST API server endpoint
26656	Listen for incoming peer connections
26660	Listen for Prometheus connections

Nyx Validator & NymAPI Config Manual Node Upgrade

Maintenance

Useful commands

Configure your firewall

1. Start with setting up the essential tools on your server.

2. Configure your firewall using Uncomplicated Firewall (UFW)

3. Open all needed ports to have your firewall for nym-node working correctly

Backup a node

1. Create a directory where you want to store your backup

2. Copy configuration folder .nym from your VPS to your newly created backup directory

3. Verify the success of the backup

Restoring a node

1. Prepare new VPS

2. Restore your node configuration

3. Configure your node on the new VPS

4. Change the node smart contract info via the wallet interface

Moving a node

1. Prepare both servers

2. Move the node data and keys to the new machine

3. Open new/target VPS terminal and configure the node

4. Change the node smart contract info via the wallet interface

Rename Node Local Identifier

1. Copy the configuration directory to the new one

2. Rename all original <ID> occurrences in config.toml to default-nym-node

3. Validate by rechecking the config file content

4. Reload your systemd service daemon and restart the service

5. Be careful before removing old config

Ports

Nym Node Port Reference

Validator Port Reference

3. Open all needed ports to have your firewall for `nym-node` working correctly

2. Copy configuration folder `.nym` from your VPS to your newly created backup directory

2. Rename all original `<ID>` occurrences in `config.toml` to `default-nym-node`