GRIN/nym
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[DOC]: Update nym-vpn commands (#4386)

Browse Source 
* update nym-vpn commands

* update testing flow

* bumped up scripts and version url to 0.0.4

* correct cli script version -> 0.0.2

* update extract commands

* update extract commands

* update gui and cli auto scripts

* correct curl url

* minor fixes to formatting

* add final bash script for desktop

* syntax change

* commenting mac manual steps

* comment off mac manual steps from summary

* Update SUMMARY.md

* Update troubleshooting.md

---------

Co-authored-by: mfahampshire <mfahampshire@pm.me>
This commit is contained in:
import this
2024-02-20 12:08:36 +00:00
committed by GitHub
parent ac676760d4
commit 73632a0ae7
10 changed files with 125 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-portal/book.toml
+1 -1
View File
@@ -31,7 +31,7 @@ assets_version = "3.0.0" # do not edit: managed by `mdbook-admonish install`
minimum_rust_version = "1.66"
wallet_release_version = "1.2.8"
# nym-vpn related variables
nym_vpn_latest_binary_url = "https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.3"
nym_vpn_latest_binary_url = "https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.4"
nym_vpn_form_url = "https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2"
[preprocessor.last-changed]
documentation/dev-portal/src/SUMMARY.md
-1
View File
@@ -21,7 +21,6 @@
- [NymVPN alpha](nymvpn/intro.md)
- [GUI](nymvpn/gui.md)
- [Linux](nymvpn/gui-linux.md)
- [MacOS](nymvpn/gui-mac.md)
- [CLI](nymvpn/cli.md)
- [Linux](nymvpn/cli-linux.md)
- [MacOS](nymvpn/cli-mac.md)
documentation/dev-portal/src/nymvpn/cli-linux.md
+12 -5
View File
@@ -14,11 +14,17 @@ NymVPN is an experimental software and it's for [testing](./testing.md) purposes
echo "<SHA_STRING>" | shasum -a 256 -c
# choose a correct one according to your binary, this is just an example
echo "0e4abb461e86b2c168577e0294112a3bacd3a24bf8565b49783bfebd9b530e23 nym-vpn-cli_0.1.0_ubuntu-22.04_amd64.zip" | shasum -a 256 -c
# echo "0e4abb461e86b2c168577e0294112a3bacd3a24bf8565b49783bfebd9b530e23 nym-vpn-cli_0.1.0_ubuntu-22.04_amd64.zip" | shasum -a 256 -c
```
3. Extract files with `unzip` command or manually as you are used to
4. Make executable by running:
1. Extract files:
```sh
tar -xvf <BINARY>
# for example
# tar -xvf nym-vpn-cli_0.0.2_ubuntu-22.04_x86_64.tar.gz
```
2. Make executable by running:
```sh
# possibly you may have to cd into a sub-directory
chmod u+x ./nym-vpn-cli
```
5. Create Sandbox environment config file by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the same directory as your NymVPN binaries by running:
@@ -54,7 +60,7 @@ sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id <ENTRY_GATEWAY_ID> --exit
./nym-vpn-cli --help
```
~~~admonish example collapsible=true title="Console output"
```
```sh
Usage: nym-vpn-cli [OPTIONS]
Options:
@@ -88,11 +94,12 @@ Options:
Enable two-hop mixnet traffic. This means that traffic jumps directly from entry gateway to exit gateway
--enable-poisson-rate
Enable Poisson process rate limiting of outbound traffic
--disable-background-cover-traffic
Disable constant rate background loop cover traffic
-h, --help
Print help
-V, --version
Print version
```
~~~
documentation/dev-portal/src/nymvpn/cli-mac.md
+13 -7
View File
@@ -14,14 +14,20 @@ NymVPN is an experimental software and it's for [testing](./testing.md) purposes
echo "<SHA_STRING>" | shasum -a 256 -c
# choose a correct one according to your binary, this is just an example
echo "96623ccc69bc4cc0e4e3e18528b6dae6be69f645d0a592d926a3158ce2d0c269 nym-vpn-cli_0.1.0_macos_x86_64.zip" | shasum -a 256 -c
# echo "96623ccc69bc4cc0e4e3e18528b6dae6be69f645d0a592d926a3158ce2d0c269 nym-vpn-cli_0.1.0_macos_x86_64.zip" | shasum -a 256 -c
```
5. Extract files with `unzip` command or manually as you are used to
6. Make executable by running:
3. Extract files:
```sh
tar -xvf <BINARY>
# for example
# tar -xvf nym-vpn-cli_0.0.2_macos_aarch64.tar.gz
```
4. Make executable by running:
```sh
# possibly you may have to cd into a sub-directory
chmod u+x ./nym-vpn-cli
```
7. Create Sandbox environment config file by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the same directory as your NymVPN binaries by running:
5. Create Sandbox environment config file by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the same directory as your NymVPN binaries by running:
```sh
curl -L "https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env" -o sandbox.env
```
@@ -32,7 +38,6 @@ curl -L "https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env"
Make sure your terminal is open in the same directory as your `nym-vpn-cli` binary.
1. Go to [nymvpn.com/en/alpha](https://nymvpn.com/en/alpha) to get the entire command with all the needed arguments' values and your wireguard private key for testing purposes
2. Run it as root with `sudo` - the command will look like this with specified arguments:
```sh
@@ -55,7 +60,7 @@ sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id <ENTRY_GATEWAY_ID> --exit
./nym-vpn-cli --help
```
~~~admonish example collapsible=true title="Console output"
```
```sh
Usage: nym-vpn-cli [OPTIONS]
Options:
@@ -89,11 +94,12 @@ Options:
Enable two-hop mixnet traffic. This means that traffic jumps directly from entry gateway to exit gateway
--enable-poisson-rate
Enable Poisson process rate limiting of outbound traffic
--disable-background-cover-traffic
Disable constant rate background loop cover traffic
-h, --help
Print help
-V, --version
Print version
```
~~~
documentation/dev-portal/src/nymvpn/cli.md
+4 -5
View File
@@ -12,11 +12,11 @@ Follow the simple [automated script](#automated-script-for-cli-installation) bel
## Automated Script for CLI Installation
We wrote a [script](https://gist.github.com/tommyv1987/87267ded27e1eb7651aa9cc745ddf4af) which does download of the CLI, sha256 verification, extraction, installation and configuration for Linux and MacOS users automatically following the steps below:
We wrote a [script](https://gist.github.com/serinko/d65450653d6bbafacbcee71c9cb8fb31) which does download of the CLI, sha256 verification, extraction, installation and configuration for Linux and MacOS users automatically following the steps below:
1. Open a terminal window in a directory where you want the script and NymVPN CLI binary be downloaded and run
```sh
curl -o execute-nym-vpn-cli-binary.sh -L https://gist.githubusercontent.com/tommyv1987/87267ded27e1eb7651aa9cc745ddf4af/raw/2a8b703655549f2e515ef1960b5f6dc54adc02fa/execute-nym-vpn-cli-binary.sh
curl -o execute-nym-vpn-cli-binary.sh -L https://gist.githubusercontent.com/serinko/d65450653d6bbafacbcee71c9cb8fb31/raw/0cbcdd18f7ee94f559692b936061248ebbbf2773/execute-nym-vpn-cli-binary.sh
```
2. Make the script executable
@@ -24,9 +24,9 @@ curl -o execute-nym-vpn-cli-binary.sh -L https://gist.githubusercontent.com/tomm
chmod u+x execute-nym-vpn-cli-binary.sh
```
3. Start the script as root, turn off any VPN and run
3. Start the script, turn off any VPN and run
```sh
sudo ./execute-nym-vpn-cli-binary.sh
sudo -E ./execute-nym-vpn-cli-binary.sh
```
4. Follow the prompts in the program
@@ -43,4 +43,3 @@ sudo ./execute-nym-vpn-cli-binary.sh
To run `nym-vpn-cli` again, reconnect your wifi, move to the directory of your CLI binary `cd ~/nym-vpn-cli-dir` and follow the guide for [Linux](cli-linux.md#run-nymvpn) or [MacOS](cli-mac.md#run-nymvpn). If you find it too difficult, just run this script again - like in step \#3 above.
In case of errors check out the [troubleshooting](troubleshooting.md) section.
documentation/dev-portal/src/nymvpn/gui-linux.md
+47 -7
View File
@@ -1,4 +1,4 @@
# NymVPN alpha GUI: Guide for GNU/Linux
# NymVPN alpha - Desktop: Guide for GNU/Linux
<div style="padding:56.25% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/908221306?h=404b2bbdc8" style="position:absolute;top:0;left:0;width:100%;height:100%;" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe></div><script src="https://player.vimeo.com/api/player.js"></script>
@@ -18,9 +18,52 @@ NymVPN is an experimental software and it's for [testing](./testing.md) purposes
echo "<SHA_STRING>" | shasum -a 256 -c
# choose a correct one according to your binary, this is just an example
echo "a5f91f20d587975e30b6a75d3a9e195234cf1269eac278139a5b9c39b039e807 nym-vpn-desktop_0.0.3_ubuntu-22.04_x86_64.zip" | shasum -a 256 -c
# echo "a5f91f20d587975e30b6a75d3a9e195234cf1269eac278139a5b9c39b039e807 nym-vpn-desktop_0.0.3_ubuntu-22.04_x86_64.zip" | shasum -a 256 -c
```
3. Extract files with `unzip` command or manually as you are used to
3. Extract files:
```sh
tar -xvf <BINARY>
# for example
# tar -xvf nym-vpn-desktop_0.0.4_ubuntu-22.04_x86_64.tar.gz
```
2. Make executable by running:
```sh
# possibly you may have to cd into a sub-directory
chmod u+x <BINARY>
```
5. Create Sandbox environment config file by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the same directory as your NymVPN binaries by running:
```sh
curl -o sandbox.env -L https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env
```
## Run NymVPN
**For NymVPN to work, all other VPNs must be switched off!** At this alpha stage of NymVPN, the network connection (wifi) must be reconnected after or in between the testing rounds.
Make sure your terminal is open in the same directory as your `nym-vpn-cli` binary.
1. Go to [nymvpn.com/en/alpha](https://nymvpn.com/en/alpha) to get the entire command with all the needed arguments' values and your wireguard private key for testing purposes
2. Run it as root with `sudo` - the command will look like this with specified arguments:
```sh
sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id <ENTRY_GATEWAY_ID> --exit-router-address <EXIT_ROUTER_ADDRESS> --enable-wireguard --private-key <PRIVATE_KEY> --wg-ip <WIREGUARD_IP>
```
3. To choose different Gateways, visit [nymvpn.com/en/alpha/api/gateways](https://nymvpn.com/en/alpha/api/gateways) and pick one
4. See all possibilities in [command explanation](#cli-commands-and-options) section below
In case of errors, see [troubleshooting section](troubleshooting.md).
### CLI Commands and Options
The basic syntax of `nym-vpn-cli` is:
```sh
sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id <ENTRY_GATEWAY_ID> --exit-router-address <EXIT_ROUTER_ADDRESS> --enable-wireguard --private-key <PRIVATE_KEY> --wg-ip <WG_IP>
```
* To choose different Gateways, visit [nymvpn.com/en/alpha/api/gateways](https://nymvpn.com/en/alpha/api/gateways)
* To see all possibilities run with `--help` flag:
```sh
./nym-vpn-cli --help
```
4. If you prefer to run `.AppImage` make executable by running:
```sh
chmod u+x ./appimage/nym-vpn_0.0.2_amd64.AppImage
@@ -49,9 +92,6 @@ curl -o $HOME/.config/nym-vpn/sandbox.env -L https://raw.githubusercontent.com/n
```toml
# change <USER> to your username
env_config_file = "/home/<USER>/.config/nym-vpn/sandbox.env"
entry_node_location = "DE" # two letters country code
# You can choose different entry by entering one of the following two letter country codes:
# DE, UK, FR, IE
```
## Run NymVPN
@@ -64,7 +104,7 @@ Open terminal and run:
```sh
# .AppImage must be run from the same directory as the binary
sudo -E ./nym-vpn_0.0.2_amd64.AppImage
sudo -E ./nym-vpn_0.033_amd64.AppImage
# .deb installation shall be executable from anywhere as
sudo -E nym-vpn
documentation/dev-portal/src/nymvpn/gui-mac.md
+10 -8
View File
@@ -1,4 +1,4 @@
# NymVPN alpha GUI: Guide for Mac OS
# NymVPN alpha - Desktop: Guide for Mac OS
```admonish info
NymVPN is an experimental software and it's for [testing](./testing.md) purposes only. All users testing the client are expected to sign GDPR Information Sheet and Consent Form (shared at the workshop) so we use their results to improve the client, and submit the form [*NymVPN User research*]({{nym_vpn_form_url}}) with the testing results.
@@ -20,9 +20,14 @@ mkdir -p "$HOME/nym-vpn-latest"
echo "<SHA_STRING>" | shasum -a 256 -c
# choose a correct one according to your binary, this is just an example
echo "da4c0bf8e8b52658312d341fa3581954cfcb6efd516d9a448c76d042a454b5df nym-vpn-desktop_0.0.3_macos_x86_64.zip" | shasum -a 256 -c
# echo "da4c0bf8e8b52658312d341fa3581954cfcb6efd516d9a448c76d042a454b5df nym-vpn-desktop_0.0.3_macos_x86_64.zip" | shasum -a 256 -c
```
4. Extract files:
```sh
tar -xvf <BINARY>
# for example
# tar -xvf nym-vpn-desktop_0.0.4_macos_aarch64.tar.gz
```
4. Extract files with `unzip` command or manually as you are used to
5. Move to the application directory and make executable
```sh
cd "macos/nym-vpn.app/Contents/MacOS"
@@ -39,9 +44,6 @@ mv nym-vpn "$HOME/nym-vpn-latest"
7. Create the configuration file by opening a text editor and saving the lines below as `config.toml` in the same directory `~/nym-vpn-latest`
```toml
env_config_file = ".env"
entry_node_location = "DE" # two letters country code
# You can choose different entry by entering one of the following two letter country codes:
# DE, UK, FR, IE
```
8. Create testnet configuration file by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `.env` in the same directory `~/nym-vpn-latest`
```sh
@@ -51,9 +53,9 @@ curl -L "https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env"
**For NymVPN to work, all other VPNs must be switched off!** At this alpha stage of NymVPN, the network connection (wifi) must be reconnected after or in between the testing rounds.
Open terminal in your `~/nym-vpn-latest` directory and run:
Run:
```sh
sudo ./nym-vpn
sudo -E $HOME/nym-vpn-latest/nym-vpn
```
In case of errors check out the [troubleshooting](troubleshooting.html#installing-gui-on-macos-not-working) section.
documentation/dev-portal/src/nymvpn/gui.md
+10 -8
View File
@@ -1,4 +1,4 @@
# NymVPN Application (GUI)
# NymVPN - Desktop (GUI)
```admonish info
Our alpha testing round is done with participants at live workshop events. This guide will not work for everyone, as the NymVPN source code is not yet publicly accessible. The alpha testing is done on Nym testnet Sandbox environment, this configuration is limited and will not work in the future.
@@ -6,9 +6,11 @@ Our alpha testing round is done with participants at live workshop events. This
**If you commit to test NymVPN alpha, please start with the [user research form]({{nym_vpn_form_url}}) where all the steps will be provided**. If you disagree with any of the conditions listed, please leave this page.
```
This is the alpha version of NymVPN application - the GUI. A demo of how the client will look like for majority of day-to-day users. For qualitative testing the [CLI](cli.md) is a necessity but to run the GUI holds the same importance as it provides the user with an experience of the actual app and the developers with a valuable feedback from the users.
This is the alpha version of NymVPN desktop application (GUI). A demo of how the client will look like for majority of day-to-day users. For qualitative testing the [CLI](cli.md) is a necessity but to run the GUI holds the same importance as it provides the user with an experience of the actual app and the developers with a valuable feedback from the users.
Follow the simple [automated script](#automated-script-for-gui-installation) below to install and run NymVPN GUI. If you prefer to do a manual setup follow the steps in the guide for [Linux](gui-linux.md) or [MacOS](gui-mac.md).
Follow the simple [automated script](#automated-script-for-gui-installation) below to install and run NymVPN GUI. If you prefer to do a manual setup follow the steps in the guide for [Linux](gui-linux.md).
Visit NymVPN alpha latest [release page]({{nym_vpn_latest_binary_url}}) to check sha sums or download the binaries directly.
## Automated Script for GUI Installation
@@ -16,7 +18,7 @@ We wrote a [script](https://gist.github.com/serinko/e0a9f7ff3d79e974ec6f6783caa1
1. Open a terminal window in a directory where you want the script and NymVPN binary be downloaded and run
```sh
curl -o nym-vpn-desktop-install-run.sh -L https://gist.githubusercontent.com/serinko/e0a9f7ff3d79e974ec6f6783caa1137e/raw/064c0d42af6a187b4f62998a0c2e6a84c319eeef/nym-vpn-desktop-install-run.sh
curl -o nym-vpn-desktop-install-run.sh -L https://gist.githubusercontent.com/serinko/e0a9f7ff3d79e974ec6f6783caa1137e/raw/227c8c348a1e58f68cb500e4504b22412177c680/nym-vpn-desktop-install-run.sh
```
2. Make the script executable
@@ -24,7 +26,7 @@ curl -o nym-vpn-desktop-install-run.sh -L https://gist.githubusercontent.com/ser
chmod u+x nym-vpn-desktop-install-run.sh
```
3. Start the script as root, turn off any VPN and run
3. Start the script, turn off any VPN and run
```sh
sudo -E ./nym-vpn-desktop-install-run.sh
```
@@ -34,10 +36,10 @@ sudo -E ./nym-vpn-desktop-install-run.sh
To start the application again, reconnect your wifi and run
```sh
# Linux
sudo -E ~/nym-vpn-latest/nym-vpn_0.0.3_amd64.AppImage
sudo -E ~/nym-vpn-latest/nym-vpn_0.0.4_amd64.AppImage
# MacOS
sudo $nym_vpn_dir/nym-vpn
sudo -E $HOME/nym-vpn-latest/nym-vpn
```
In case of errors check out the [troubleshooting](troubleshooting.md#installing-gui-on-macos-not-working) section.
In case of errors check out the [troubleshooting](troubleshooting.md#running-gui-failed-due-to-toml-parse-error) section.
documentation/dev-portal/src/nymvpn/testing.md
+10 -7
View File
@@ -14,14 +14,17 @@ One of the main aims of NymVPN alpha release is testing; your results will help
> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets.
1. Create a directory called `nym-vpn-tests` and copy your `nym-vpn-cli` binary ([download here]({{nym_vpn_latest_binary_url}})) and [`sandbox.env`](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) to that directory
2. Copy the [block below](#testssh) and save it as `tests.sh` to the same folder
3. Open terminal in the same directory
4. Turn off any existing VPN's (including the NymVPN instances), reconnect your wifi and make the script executable by running
1. Create a directory called `nym-vpn-tests` and copy your `nym-vpn-cli` binary ([download here]({{nym_vpn_latest_binary_url}}))
2. Copy or download [`sandbox.env`](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) testnet config file to the same directory
```sh
curl -o sandbox.env -L https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env
```
3. Copy the [block below](#testssh) and save it as `tests.sh` to the same folder
4. Open terminal in the same directory and make the script executable
```sh
chmod u+x ./tests.sh
```
5. Run the `tests.sh` script:
5. Turn off any existing VPN's (including NymVPN instances), reconnect your wifi and run the `tests.sh` script
```sh
sudo ./tests.sh
````
@@ -46,8 +49,8 @@ nym-vpn-tests
├── timeout
└── two_hop_perf_test_results.log
```
10. When the tests are finished, remove the `nym-vpn-cli` binary from the folder and compress the entire folder as `nym-vpn-tests.zip`
11. Upload this compressed file to the [form]({{nym_vpn_form_url}}) upload field when prompted
10. When the tests are finished, remove the `nym-vpn-cli` binary from the folder and compress the entire folder as `nym-vpn-tests.zip` (both of these can be done in your graphical environment)
11. Upload this compressed file to the [form]({{nym_vpn_form_url}}) drop field when prompted
#### tests.sh
documentation/dev-portal/src/nymvpn/troubleshooting.md
+18 -4
View File
@@ -2,13 +2,27 @@
Below are listed some points which may need to be addressed when testing NymVPN alpha. If you crashed into any errors which are not listed, please contact us at the testing workshop or in the NymVPN [Matrix channel](https://matrix.to/#/#NymVPN:nymtech.chat).
#### Problems with the newest version `nym-vpn-alpha-0.0.X demo`
#### Running GUI failed due to `TOML parse error`
Try the previous version which was tested multiple times by downloading the client from the [release page](https://github.com/nymtech/nym/releases). Then follow all the setup steps the name of your downloaded binary.
If you see this error when running NymVPN alpha desktop, it's because the older versions needed entry location in `config.toml` configuration file. From `v0.0.3` the entry location is selected directly by the user in the application. This error is due to an old `app-data.toml` config in your computer.
#### Installing GUI on MacOS not working
```sh
2024-02-15T14:25:02.745331Z ERROR read: nym_vpn_desktop::fs::storage: TOML parse error at line 5, column 1
|
5 | [entry_node_location]
| ^^^^^^^^^^^^^^^^^^^^^
wanted exactly 1 element, more than 1 element
self=AppStorage { data: AppData { monitoring: None, autoconnect: None, killswitch: None, entry_location_selector: None, ui_theme: None, ui_root_font_size: None, vpn_mode: None, entry_node_location: None, exit_node_location: None }, dir_path: "/home/companero/.local/share/nym-vpn", filename: "app-data.toml", full_path: "/home/companero/.local/share/nym-vpn/app-data.toml" }
Error: TOML parse error at line 5, column 1
|
5 | [entry_node_location]
| ^^^^^^^^^^^^^^^^^^^^^
wanted exactly 1 element, more than 1 element
```
In case there was a problem running the script, try the [manual setup](gui-mac.md) for MacOS.
Simply delete this file `app-data.toml` from the path listed in the error message. In the example above it would be `/home/companero/.local/share/nym-vpn/app-data.toml`.
The application will create a new one on startup.
#### Thread `main` panicked