diff --git a/documentation/operators/src/changelog.md b/documentation/operators/src/changelog.md index 707adc484c..9a364f0441 100644 --- a/documentation/operators/src/changelog.md +++ b/documentation/operators/src/changelog.md @@ -2,6 +2,358 @@ This page displays a full list of all the changes during our release cycle from [`v2024.3-eclipse`](https://github.com/nymtech/nym/blob/nym-binaries-v2024.3-eclipse/CHANGELOG.md) onwards. Operators can find here the newest updates together with links to relevant documentation. The list is sorted so that the newest changes appear first. +## `v2024.10-caramello` + +- [Release binaries](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2024.10-caramello) +- [Release CHANGELOG.md](https://github.com/nymtech/nym/blob/nym-binaries-v2024.10-caramello/CHANGELOG.md) +- [`nym-node`](nodes/nym-node.md) version `1.1.7` + +~~~admonish example collapsible=true title='CHANGELOG.md' +- Backport 4844 and 4845 ([#4857]) +- Bugfix/client registration vol2 ([#4856]) +- Remove wireguard feature flag and pass runtime enabled flag ([#4839]) +- Eliminate cancel unsafe sig awaiting ([#4834]) +- added explicit updateable admin to the mixnet contract ([#4822]) +- using legacy signing payload in CLI and verifying both variants in contract ([#4821]) +- adding ecash contract address ([#4819]) +- Check profit margin of node before defaulting to hardcoded value ([#4802]) +- Sync last_seen_bandwidth immediately ([#4774]) +- Feature/additional ecash nym cli utils ([#4773]) +- Better storage error logging ([#4772]) +- bugfix: make sure DKG parses data out of events if logs are empty ([#4764]) +- Fix clippy on rustc beta toolchain ([#4746]) +- Fix clippy for beta toolchain ([#4742]) +- Disable testnet-manager on non-unix ([#4741]) +- Don't set NYM_VPN_API to default ([#4740]) +- Update publish-nym-binaries.yml ([#4739]) +- Update ci-build-upload-binaries.yml ([#4738]) +- Add NYM_VPN_API to network config ([#4736]) +- Re-export RecipientFormattingError in nym sdk ([#4735]) +- Persist wireguard peers ([#4732]) +- Fix tokio error in 1.39 ([#4730]) +- Feature/vesting purge plus ranged cost params ([#4716]) +- Fix (some) feature unification build failures ([#4681]) +- Feature Compact Ecash : The One PR ([#4623]) + +[#4857]: https://github.com/nymtech/nym/pull/4857 +[#4856]: https://github.com/nymtech/nym/pull/4856 +[#4839]: https://github.com/nymtech/nym/pull/4839 +[#4834]: https://github.com/nymtech/nym/pull/4834 +[#4822]: https://github.com/nymtech/nym/pull/4822 +[#4821]: https://github.com/nymtech/nym/pull/4821 +[#4819]: https://github.com/nymtech/nym/pull/4819 +[#4802]: https://github.com/nymtech/nym/pull/4802 +[#4774]: https://github.com/nymtech/nym/pull/4774 +[#4773]: https://github.com/nymtech/nym/pull/4773 +[#4772]: https://github.com/nymtech/nym/pull/4772 +[#4764]: https://github.com/nymtech/nym/pull/4764 +[#4746]: https://github.com/nymtech/nym/pull/4746 +[#4742]: https://github.com/nymtech/nym/pull/4742 +[#4741]: https://github.com/nymtech/nym/pull/4741 +[#4740]: https://github.com/nymtech/nym/pull/4740 +[#4739]: https://github.com/nymtech/nym/pull/4739 +[#4738]: https://github.com/nymtech/nym/pull/4738 +[#4736]: https://github.com/nymtech/nym/pull/4736 +[#4735]: https://github.com/nymtech/nym/pull/4735 +[#4732]: https://github.com/nymtech/nym/pull/4732 +[#4730]: https://github.com/nymtech/nym/pull/4730 +[#4716]: https://github.com/nymtech/nym/pull/4716 +[#4681]: https://github.com/nymtech/nym/pull/4681 +[#4623]: https://github.com/nymtech/nym/pull/4623 +~~~ + +### Features + +- [Add 1GB/day/user bandwidth cap](https://github.com/nymtech/nym/pull/4717) + +~~~admonish example collapsible=true title='Testing steps performed' +**Scenario 1: Bandwidth Decreasing Continuously** + +1. Started the client and noted the initial bandwidth (e.g., 1GB). +2. Used the client and tracked bandwidth usage over time (e.g., decrease by 100MB every hour). +3. Restarted the client after some usage. +4. Verified the bandwidth continued from the last recorded value, not reset. + +The bandwidth continued decreasing without resetting upon restart. Logs and reports correctly reflected the decreasing bandwidth. + +**Scenario 2: Bandwidth Reset Next Day** + +1. Used the client normally until the end of the day. +2. Suspended some clients and kept others active. +3. Checked bandwidth at midnight. +4. Verified that bandwidth reset to 1GB for both suspended and active clients. + +Bandwidth reset to 1GB for all clients at midnight. Logs and reports correctly showed the reset. + +**Scenario 3: Bandwidth Reset at a Different Time (e.g., Midday)** + +1. Configured the system to reset bandwidth at midday. +2. Used the client and monitored bandwidth until midday. +3. Kept the client connected during the reset time. +4. Verified that bandwidth reset to 1GB live at midday. + +Bandwidth reset to 1GB at midday while the client was connected. Logs and reports correctly reflected the reset. + +**Scenario 4: Stale Check for 3 Days** + +1. Kept a client inactive for 3 days. +2. Verified removal from the peer list after 3 days. +3. Reconnected the client after 3 days and checked for a new private IP. +4. Restarted a client within 3 days and verified it retained the same private IP. + +The client was removed from the peer list after 3 days of inactivity. Upon re-connection after 3 days, the client received a new private IP. The client retained the same private IP when restarted within 3 days. +~~~ + +- [Feature/merge back](https://github.com/nymtech/nym/pull/4710): Merge back from the release branch the changes that fix the `nym-node` upgrades + +- [Removed mixnode/gateway config migration code and disabled cli without explicit flag](https://github.com/nymtech/nym/pull/4706): `nym-gateway` and `nym-mixnode` commands now won't do anything without explicit `--force-run` to bypass the deprecation. The next step, in say a month or so, is to completely remove all `cli` related things. + +~~~admonish example collapsible=true title='Testing steps performed' +- Verify that the `nym-gateway` binary and `nym-mixnode` binary commands return the _error message_ stating to update to nym-node +- Check that when adding the `--force-run` flag, it still allows the command to be run (aside from `init` which has been removed) and the message stating to update to nym-node is a _warning_ now +- Check `nym-node` is not affected +- Reviewed the changes in the PR +~~~ + +- [Handle clients with different versions in IPR](https://github.com/nymtech/nym/pull/4723): Allow the IPR to handle clients connecting both using `v6` and `v7`, independently. The motivation is that we want to be able to roll out a API version change gradually for VPN clients without breaking backwards compatibility. The main feature on the new `v7` format that is not yet used, is that it adds signatures for connect/disconnect. + +~~~admonish example collapsible=true title='Testing steps performed' +Run the same command (using same gateways deployed from this PR) on different versions of the `nym-vpn-cli`. + +Example: +```sh +~/nym-vpn-core-v0.1.10_macos_universal ❯ sudo -E ./nym-vpn-cli -c ../qa.env run --entry-gateway-id $entry_gateway --exit-gateway-id $exit_gateway --enable-two-hop + +~/nym-vpn-core-v0.1.11-dev_macos_universal ❯ sudo -E ./nym-vpn-cli -c ../qa.env run --entry-gateway-id $entry_gateway --exit-gateway-id $exit_gateway --enable-two-hop +``` +~~~ + +- [Backport `#4844` and `#4845`](https://github.com/nymtech/nym/pull/4857) + +- [Remove wireguard feature flag and pass runtime enabled flag](https://github.com/nymtech/nym/pull/4839) + +- [Eliminate cancel unsafe sig awaiting](https://github.com/nymtech/nym/pull/4834) + +- [Added explicit updateable admin to the mixnet contract](https://github.com/nymtech/nym/pull/4822) + +- [Using legacy signing payload in CLI and verifying both variants in contract](https://github.com/nymtech/nym/pull/4821) + +- [Adding ecash contract address](https://github.com/nymtech/nym/pull/4819) + +- [Check profit margin of node before defaulting to hardcoded value ](https://github.com/nymtech/nym/pull/4802) + +- [Sync `last_seen_bandwidth` immediately](https://github.com/nymtech/nym/pull/4774) + +- [Feature/additional ecash `nym-cli` utils](https://github.com/nymtech/nym/pull/4773) + +- [Better storage error logging](https://github.com/nymtech/nym/pull/4772) + +- [Disable testnet-manager on non-unix](https://github.com/nymtech/nym/pull/4741) + +- [Don't set NYM_VPN_API to default](https://github.com/nymtech/nym/pull/4740) + +- [Update publish-nym-binaries.yml](https://github.com/nymtech/nym/pull/4739): Adds wireguard to builds + +- [Update ci-build-upload-binaries.yml](https://github.com/nymtech/nym/pull/4738): Adds wireguard for ci-builds + +- [Add NYM_VPN_API to network config](https://github.com/nymtech/nym/pull/4736) + +- [Re-export RecipientFormattingError in nym sdk](https://github.com/nymtech/nym/pull/4735) + +- [Persist wireguard peers](https://github.com/nymtech/nym/pull/4732) + +- [Feature/vesting purge plus ranged cost params](https://github.com/nymtech/nym/pull/4716): Combines [\#4715](https://github.com/nymtech/nym/pull/4715) and [\#4711](https://github.com/nymtech/nym/pull/4711) into one. + - Disables all non-essential operations on the vesting contract => you can no longer bond mixnodes/make delegations/etc. (you can still, however, withdraw your vested tokens and so on) + - Introduces admin-controlled minimum (and maximum) profit margin and interval operating costs. + - both contracts have to be migrated **at the same time**. ideally within the same transaction + - mixnet contract migration is not allowed (and will fail) if there are any pending actions involving vesting tokens, like delegating, increasing pledge, etc + +- [Bump braces from `3.0.2` to `3.0.3` in `/nym-wallet/webdriver`](https://github.com/nymtech/nym/pull/4709): Bumps [braces](https://github.com/micromatch/braces) from `3.0.2` to `3.0.3`. + +### Bugfix + +- [chore: fix 1.80 lint issues](https://github.com/nymtech/nym/pull/4731) + +~~~admonish example collapsible=true title='Testing steps performed' +- Building all binaries is ok +- Running `cargo fmt` returns no issues +~~~ + +- [Fix version 1 not having template correspondent initially](https://github.com/nymtech/nym/pull/4733) + +~~~admonish example collapsible=true title='Testing steps performed' +Tested updating an old `nym-node` version and ensuring it did not throw any errors. +~~~ + +- [Bugfix/client registration vol2](https://github.com/nymtech/nym/pull/4856) + +- [Fix tokio error in `1.39`](https://github.com/nymtech/nym/pull/4730): + - Bump tokio to `1.39.2`, skipping the issue with `1.39.1` + + +- [Fix (some) feature unification build failures](https://github.com/nymtech/nym/pull/4681): Running a script in the root workspace that builds each crate independently + +~~~admonish example collapsible=true title='The script' + ```sh + #!/bin/bash + + packages=$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[].name') + + # Loop through each package and build + for package in $packages; do + echo "Building $package" + cargo clean + cargo check -p "$package" + if [ $? -ne 0 ]; then + echo "Build failed for $package. Stopping." + exit 1 + fi + done + ``` +~~~ + +- [bugfix: make sure DKG parses data out of events if logs are empty](https://github.com/nymtech/nym/pull/4764): This will be the case on post `0.50` chains + +- [Fix clippy on rustc beta toolchain](https://github.com/nymtech/nym/pull/4746): Fix clippy warnings for rust beta toolchain + +- [Fix clippy for beta toolchain](https://github.com/nymtech/nym/pull/4742): Fix beta toolchain clippy by removing unused module + - Add `nym-` prefix to `serde-common` crate + - Remove ignored `default-features = false` attribute for workspace dependency + +### Crypto + +- [Feature Compact Ecash : The One PR](https://github.com/nymtech/nym/pull/4623) + +### Operators Guide, Tooling & Updates + +- More explicit [setup for `nym-node`](nodes/setup.md#initialise--run) with a new [option explanation](nodes/setup.md#essential-parameters--variables), including syntax examples + +- New [VPS networking configuration steps for Wireguard](nodes/configuration.md#routing-configuration) + +- Wireguard [builds from source](binaries/building-nym.md) together with `nym-node`, no need to specify with a feature flag anymore + +- Wireguard peers stay connected for longer time, re-connections are also faster + +- Profit margin and operating cost values will be set to the agreed values, the values can be changed in the future through [Nym Operators governance process](https://forum.nymtech.net/t/poll-proposal-for-on-chain-minimum-profit-margin-for-all-nym-nodes/253) +```admonish success title="" +- Minimum profit margin = 20% +- Maximum profit margin = 50% +- Minimum operating cost = 0 NYM +- Maximum operating cost = 1000 NYM +``` + +- [Nym Harbourmater](https://harbourmaster.nymtech.net) has several new functionalities: + - Version counting graph for Gateways and Mixnodes + - Several new columns with larger nodes performance and settings overview. + - Top routing score now includes: + - Wireguard registration and complete handshake test, to configure see [tasklist below](#operators-tasks) + - DNS resolution check, to configure see [tasklist below](#operators-tasks) + - Wireguard perfomance > 0.75, to configure see [tasklist below](#operators-tasks) + +- New wallet coming out soon! + - Vesting contract functionalities have been purged, users can only remove tokens from vesting + +- [Nym API Check CLI](testing/node-api-check.md) is upgraded according to the latest API endpoints, output is cleaner and more concise. + + +#### Operators Tasks + +```admonish warning title="" +**The steps below are highly recommended for all operators and mandatory for everyone who is a part of Nym Delegation or Grant program. Deadline is Friday, September 20th, 2024.** +``` + +Every `nym-node` should be upgraded to the latest version! Operators can test using [Sandbox env](sandbox.md) during the pre-release period, then upgrade on mainnet. During the upgrade, please follow the points below before you restart the node: + +**`nym-node`** + +- Make sure to fill in basic description info, into the file located at `.nym/nym-nodes//data/description.toml` (all nodes) +- Configure wireguard routing with new [`network_tunnel_manager.sh`](https://gist.github.com/tommyv1987/ccf6ca00ffb3d7e13192edda61bb2a77) following [these steps](nodes/configuration.md#routing-configuration) (Gateways only for the time being) +- Enable Wireguard with `--wireguard-enabled true` flag included in your run command (Gateways only for the time being) + - Note: On some VPS this setup may not be enough to get the correct results as some ISPs have their own security groups setup below the individual VPS. In that case a ticket to ISP will have to be issued to open the needed settings. We are working on a template for such ticket. +- Setup [reverse proxy and WSS](nodes/proxy-configuration.md) on `nym-node` (Gateways only for the time being) +- Don't forget to restart your node - or (preferably using [systemd automation](nodes/configuration.md#systemd)) reload daemon and restart the service +- Migrating from `mixnet` or `gateway` smart contracts to a new `nym-node` smart contract will be available soon with an upcoming version of Nym desktop wallet. After this migration all `nym-nodes` will be able to receive delegation. The operators will have to confirm the migration once it's deployed. +- Optional: Use [`nym-gateway-probe`](testing/gateway-probe.html) and [NymVPN CLI](https://nymtech.net/developers/nymvpn/cli.html) to test your own Gateway +- Optional: Run the script below to measure ping speed of your Gateway and share your results in [Nym Operators channel](https://matrix.to/#/#operators:nymtech.chat) + +~~~admonish example collapsible=true title='The script to measure Gateway ping results' +We made a script for pinging nymtech.net from your GWs. Can you please install it and then share the result together with your Gateway ID: + +1. Get the script onto your machine (soon on github for curl or wget): + +```sh +# paste all this block as one command +cat <<'EOL' > ping_with_curl_average_for_wg_check.sh +#!/bin/bash + +ping_with_curl_average_for_wg_check() { + total_connect_time=0 + total_total_time=0 + iterations=5 + timeout=2 + + for ((i=1; i<=iterations; i++)); do + echo "ping attempt $i..." + + echo "curling nymtech.net to check ping response times" + times=$(curl -I https://nymtech.net --max-time $timeout \ + -w "time_connect=%{time_connect}\ntime_total=%{time_total}" -o /dev/null -s) + + time_connect=$(echo "$times" | grep "time_connect" | cut -d"=" -f2) + time_total=$(echo "$times" | grep "time_total" | cut -d"=" -f2) + + total_connect_time=$(echo "$total_connect_time + $time_connect" | bc) + total_total_time=$(echo "$total_total_time + $time_total" | bc) + + echo "time to connect: $time_connect s" + echo "total time: $time_total s" + done + + average_connect_time=$(echo "scale=3; $total_connect_time / $iterations" | bc) + average_total_time=$(echo "scale=3; $total_total_time / $iterations" | bc) + + echo "-----------------------------------" + echo "average time to connect: $average_connect_time s" + echo "average total time: $average_total_time s" +} + +ping_with_curl_average_for_wg_check +EOL +``` + +2. Make executable: + +```sh +chmod +x ping_with_curl_average_for_wg_check.sh +``` + +3. In case you don't have `bc`, install it: + +```sh +sudo apt install bc +``` + +4. Run: + +```sh +./ping_with_curl_average_for_wg_check.sh +``` + +5. Share results and ID key in [Nym Operators channel](https://matrix.to/#/#operators:nymtech.chat) + +THANK YOU! +~~~ + +**validators** + +- Validators need to update and prepare for ecash implementation. + +### Known Bugs & Undone features + +- New `nym-nodes` without a performance 24h history above 50% don't show routing properly on `nym-gateway-probe`, on Nym Harbourmaster the page may appear blank - we are working on a fix. +- Wireguard works on IPv4 only for the time being, we are working on IPv6 implementation. +--- + ## `v2024.9-topdeck` - [Release binaries](https://github.com/nymtech/nym/releases/tag/nym-binaries-v2024.9-topdeck) diff --git a/documentation/operators/src/nodes/configuration.md b/documentation/operators/src/nodes/configuration.md index b933c4dede..b44f5bed23 100644 --- a/documentation/operators/src/nodes/configuration.md +++ b/documentation/operators/src/nodes/configuration.md @@ -103,7 +103,7 @@ To automate with `systemd` use this init service file by saving it as `/etc/syst nano /etc/systemd/system/nym-node.service ``` -2. Paste this config file +2. Paste this config file, substitute `` and `` with your correct values and add all flags to run your `nym-node` to `ExecStart` line: ```ini [Unit] Description=Nym Node @@ -199,7 +199,7 @@ In this (unusual) case your `mixnode` will not be able to route the packets. The ```admonish info We recommend operators to configure their `nym-node` with the full routing configuration. -However, most of the time the packets sent through the Mixnet are IPv4 based. The IPv6 packets are still pretty rare and therefore it's not mandatory from operational point of view to have this configuration implemented if you running only `mixnode` mode. +However, most of the time the packets sent through the Mixnet are IPv4 based. The IPv6 packets are still pretty rare and therefore it's not mandatory from operational point of view to have this configuration implemented if you running only `mixnode` mode. If you preparing to run a `nym-node` with all modes enabled in the future, this setup is required. ``` @@ -212,7 +212,7 @@ For everyone participating in Delegation Program or Service Grant program, this You can always check IPv6 address and connectivity by using some of these methods: -~~~admonish example collapsible=true +~~~admonish example collapsible=true title="Test IPv6 methods" ```sh # locally listed IPv6 addresses ip -6 addr @@ -241,19 +241,21 @@ Make sure to keep your IPv4 address enabled while setting up IPv6, as the majori While we're working on Rust implementation to have these settings as a part of the binary build, to solve these connectivity requirements in the meantime we wrote a script [`network_tunnel_manager.sh`](https://gist.github.com/tommyv1987/ccf6ca00ffb3d7e13192edda61bb2a77) to support the operators to configure their servers and address all the connectivity requirements. -Networking configuration across different ISPs and various operation systems does not have a generic solution. If the provided configuration setup doesn't solve your problem check out [IPv6 troubleshooting](../troubleshooting/vps-isp.md#ipv6-troubleshooting) page. Be aware that you may have to do more research and customised adjustments. +Networking configuration across different ISPs and various operation systems does not have a generic solution. If the provided configuration setup doesn't solve your problem check out [IPv6 troubleshooting](../troubleshooting/vps-isp.md#ipv6-troubleshooting) page. Be aware that you may have to do more research, customised adjustments or contact your ISP to change settings for your VPS. The `nymtun0` interface is dynamically managed by the `exit-gateway` service. When the service is stopped, `nymtun0` disappears, and when started, `nymtun0` is recreated. -The script should be used in a context where `nym-node`is running to fully utilise its capabilities, particularly for fetching IPv6 addresses or applying network rules that depend on the `nymtun0` interface and to establish a WireGuard tunnel. +The `nymwg` interface is used for creating a secure wireguard tunnel as part of the Nym Network configuration. Similar to `nymtun0`, the script manages iptables rules specific to `nymwg` to ensure proper routing and forwarding through the wireguard tunnel. The `nymwg` interface needs to be correctly configured and active for the related commands to function properly. This includes applying or removing iptables rules and running connectivity tests through the `nymwg` tunnel. -Before starting with the following, make sure you have the [latest `nym-node` binary](https://github.com/nymtech/nym/releases/) installed and your [VPS setup](vps-setup.md) finished properly! +The script should be used in a context where `nym-node` is running to fully utilise its capabilities, particularly for fetching IPv6 addresses or applying network rules that depend on the `nymtun0` and `nymwg` interfaces and to establish a WireGuard tunnel. + +**Before starting with the following configuration, make sure you have the [latest `nym-node` binary](https://github.com/nymtech/nym/releases/) installed and your [VPS setup](vps-setup.md) finished properly!** 1. Download `network_tunnel_manager.sh`, make executable and run: ```sh -curl -L -o network_tunnel_manager.sh https://gist.githubusercontent.com/tommyv1987/ccf6ca00ffb3d7e13192edda61bb2a77/raw/3c0a38c1416f8fdf22906c013299dd08d1497183/network_tunnel_manager.sh && \ +curl -L https://gist.githubusercontent.com/tommyv1987/ccf6ca00ffb3d7e13192edda61bb2a77/raw/74241cc06492b955e582052939090f57a285a65e/network_tunnel_manager.sh -o network_tunnel_manager.sh && \ chmod +x network_tunnel_manager.sh && \ ./network_tunnel_manager.sh ``` @@ -333,7 +335,10 @@ operation check_nymtun_iptables completed successfully. ./network_tunnel_manager.sh apply_iptables_rules_wg ``` -7. At this point your node needs to be [bonded](bonding.md) to the API for `nymtun0` to interact with the network. After bonding please follow up with the remaining steps below to ensure that your node is routing properly. +7. Apply rules to configure DNS routing and allow ICMP piung test for node probing (network testing): +```sh +./network_tunnel_manager.sh configure_dns_and_icmp_wg +``` 8. Check `nymtun0` interface: ```sh @@ -368,7 +373,7 @@ ip addr show nymtun0 11. Now you can run your node with the `--wireguard-enabled true` flag or add it to your [systemd service config](#systemd). Restart your `nym-node` or [systemd](#following-steps-for-nym-nodes-running-as-systemd-service) service (recommended): ```sh -systemctl daemon-reload && systemctl restart nym-node.service +systemctl daemon-reload && systemctl restart nym-node.service ``` - Optionally, you can check if the node is running correctly by monitoring the service logs: ```sh diff --git a/documentation/operators/src/nodes/setup.md b/documentation/operators/src/nodes/setup.md index 542dc7d883..8b6a53d84d 100644 --- a/documentation/operators/src/nodes/setup.md +++ b/documentation/operators/src/nodes/setup.md @@ -86,24 +86,6 @@ To list all available flags for each command, run `./nym-node --help` 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). ``` -#### Flags Summary - -Some of the most useful flags and their explanation: - -~~~admonish example collapsible=true title="Flags explanation:" -- `--id `: Local identifier of your node. This `` determines your config path located at `~/.nym/nym-nodes//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 `: 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. -- `--mode`: Determines the mode of the node and is always required. -- `--write-changes`: Used to change values within the `config.toml` file after the node has been run. -- `--mnemonic`: This is for when gateways are coconut-credentials-enforced, and this mnemonic is used as the `double_spend` prevention. This account needs credit in order for it to work. -- `--expose-system-info `: Sets your system info visibility on the network. -- `--expose-system-hardware `: Sets your system hardware info visibility on the network. -- `--expose-crypto-hardware `: Sets your crypto hardware info visibility on the network. -~~~ - ### Terms & Conditions ```admonish info @@ -150,72 +132,112 @@ When we use `run` command the node will do `init` as well, unless we specify wit 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 `, 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//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 --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. + ```admonish success title="" -**We recommend operators to setup an [automation](configuration.md#systemd) flow for their nodes!** +**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). ``` +#### 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: [`mixnode`](#mode-miznode), [`exit-gateway`](#mode-exit-gateway), or [`entry-gateway](#mode-entry-gateway), please familiarise yourself with the essential paramters and variables convention we use in the guide. + +Substitute any variables in `<>` brackets your own value, without `<>` brackets. Here is a list of important options and variables. + +| Flag (Option) | Variable | Description | Syntax example | +| :-- | :--- | :--- | :--- | +| `--mode` | `` | A functionality of your `nym-node` in the mixnet - mandatory! Chose from `entry-gateway`, `mixnode` or `exit-gateway` | `--mode exit-gateway` | +| `--id` | `` | A local only `nym-node` identifier, specified by flag `--id`. Not mandatory as it defaults to `default-nym-node` if not specified. | `--id alice_super_node` | +| `-w` or `--write-changes` | *none* | Specify whether to write new changes - the values of other flags in the given command - to the config file | `--write-changes` | +| `--accept-operator-terms-and-conditions` | *none* | A flag added explicitly to `nym-node run` command every time, showing that the operator agreed with [T&Cs](#terms--conditions) | `--accept-operator-terms-and-conditions` | +| `--public-ips` | `` | IPv4 of the `nym-node` server - mandatory! Use this address as a `host` value for bonding.Use this address as a `host` value for bonding. | `--public-ips "$(curl -4 https://ifconfig.me)"` | +| `--mixnet-bind-address` | `` | Address to bind to for listening for mixnet packets - mandatory! Must be on port `1789`! | `--mixnet-bind-address 0.0.0.0:1789` | +| `--http-bind-address` | `` | Socket address this node will use for binding its http API - mandatory! Must be on port `8080`! | `--http-bind-address 0.0.0.0:8080` | +| `--hostname` | `` | Your registered DNS domain, asigned to the VPS with `nym-node`. Use without prefix like `http://` or `https://` | `exit-gateway1.squad.nsl` | +| `--location` | `` | Loacation of your node. 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. | `--location JAM` | +| `--wireguard-private-ip` | `` | Private IP address of the wireguard gateway. This mandatory field is set to a correct default: `10.1.0.1`, operators upgrading from older versions must overwrite it. | `--wireguard-private-ip 10.1.0.1` | +| `--wireguard-enabled` | `` | Specifies whether the wireguard service is enabled, possible values: `true` or `false` - `true` is recommended | `--wireguard-enabled true` | +| `--expose-system-info` | `` | Specify whether basic system information should be exposed. default: `true`, possible values: `true` or `false` | `--expose-system-info false` | +| `--expose-system-hardware` | `` | Specify whether basic system hardware information should be exposed. default: `true`, possible values: `true` or `false` | `--expose-system-hardware false` | +| *not a flag* | `` | Specify a full path to the given file, directory or binary behind this variable | `/root/src/nym/target/release/` | + ```admonish note To prevent over-flooding of our documentation we cannot provide with every single command syntax as there is a large combination of possibilities. Please use a common sense and the explanation in `--help` option. ``` #### Mode: `exit-gateway` +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](#essential-paramteters--varibles) before you start and make sure that your `nym-node` is up to date with the [latest version](https://github.com/nymtech/nym/releases/). + **Initialise and run** in one command: + +To initialise and test run your node, use this command: ```sh -# simple default -./nym-node run --mode exit-gateway +./nym-node run --id --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --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. -# with other options -./nym-node run --id --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --accept-operator-terms-and-conditions --wireguard-enabled true +We highly recommend to setup [reverse proxy and WSS](proxy-configuration.md) for `nym-node`. If you haven't configured any of that, skip `--hostname` flag. -# is in format without 'https://' prefix -# 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. -# wireguard can be enabled from version 1.1.6 onwards -``` +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 : -```sh -# simple default -./nym-node run --init-only --mode exit-gateway +**Initialise only** without running the node with `--init-only` command: -# with a custom `--id` and other options -./nym-node run --id --init-only --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --accept-operator-terms-and-conditions --wireguard-enabled true +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. -# is in format without 'https://' prefix -# 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. -# wireguard can be enabled from version 1.1.6 onwards +```sh +./nym-node run --id --init-only --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --wireguard-enabled true ``` -Run the node with custom `--id` without initialising, using `--deny-init` command +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: ```sh ./nym-node run --id --deny-init --mode exit-gateway --accept-operator-terms-and-conditions ``` #### Mode: `entry-gateway` +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](#essential-paramteters--varibles) before you start and make sure that your `nym-node` is up to date with the [latest version](https://github.com/nymtech/nym/releases/). + **Initialise and run:** + +To initialise and test run with yur node with all needed options, use this command: ```sh -./nym-node run --mode entry-gateway +./nym-node run --id --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --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. -Initialise & run with all options -```sh -./nym-node run --id --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --accept-operator-terms-and-conditions --wireguard-enabled true +We highly recommend to setup [reverse proxy and WSS](proxy-configuration.md) for `nym-node`. If you haven't configured any of that, skip `--hostname` flag. -# is in format without 'https://' prefix -# 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. -# wireguard can be enabled from version 1.1.6 onwards -``` +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. -Initialise only, with an `--init-only` command (a custom `--id` used): ```sh -./nym-node run --id --init-only --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --accept-operator-terms-and-conditions +./nym-node run --id --init-only --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --wireguard-enabled true ``` -Run the node with custom `--id` without initialising: +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: ```sh ./nym-node run --id --deny-init --mode entry-gateway --accept-operator-terms-and-conditions ``` @@ -224,17 +246,27 @@ Run the node with custom `--id` without initialising: **Initialise and run:** ```sh -./nym-node run --mode mixnode +./nym-node run --mode mixnode --mixnet-bind-address 0.0.0.0:1789 --verloc-bind-address 0.0.0.0:1790 --http-bind-address 0.0.0.0:8080 --public-ips "$(curl -4 https://ifconfig.me)" --accept-operator-terms-and-conditions ``` +**Init only** + +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. + Initialise only with a custom `--id` and `--init-only` command: ```sh -./nym-node run --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 +./nym-node run --mode mixnode --id --init-only --mixnet-bind-address 0.0.0.0:1789 --verloc-bind-address 0.0.0.0:1790 --http-bind-address 0.0.0.0:8080 --public-ips "$(curl -4 https://ifconfig.me)" --accept-operator-terms-and-conditions ``` -Run the node with custom `--id` without initialising: +If you prefer to have a generic local identifier set to `default-nym-node`, skip `--id` option. + +**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: ```sh -./nym-node run --id --deny-init --mode mixnode --accept-operator-terms-and-conditions +./nym-node run --mode mixnode --id --deny-init --accept-operator-terms-and-conditions ``` ### Migrate