From 958bc2ae9ad1083f1ecf56abbef98533bb1e9bdb Mon Sep 17 00:00:00 2001 From: serinko <97586125+serinko@users.noreply.github.com> Date: Thu, 11 Jan 2024 16:34:25 +0000 Subject: [PATCH] [DOCs]: NymVPN alpha - pages for events (#4309) * initialise new nymvpn guide pages * docs: nymvpn guide, testing, troubleshooting and faq * add faq * remove todo points * resolve review comments * change landing page order * incorporate huxis user feedback * add binaries link * change menu naming -> upper case * final version for cryptotalk demo * change naming convention client -> cli --- documentation/dev-portal/src/SUMMARY.md | 14 +- .../dev-portal/src/events/37c3/nym-vpn.md | 457 ------------------ .../dev-portal/src/events/37c3/welcome.md | 14 - .../{37c3 => cryptotalk}/images/image1.png | Bin .../{37c3 => cryptotalk}/images/image2.png | Bin .../{37c3 => cryptotalk}/images/image3.png | Bin .../{37c3 => cryptotalk}/images/image4.png | Bin .../{37c3 => cryptotalk}/images/image5.png | Bin .../{37c3 => cryptotalk}/images/json.png | Bin .../faq.md => cryptotalk/nym-vpn-faq.md} | 19 +- .../src/events/cryptotalk/nym-vpn-linux.md | 198 ++++++++ .../src/events/cryptotalk/nym-vpn-mac.md | 191 ++++++++ .../src/events/cryptotalk/nym-vpn-testing.md | 195 ++++++++ .../cryptotalk/nym-vpn-troubleshooting.md | 100 ++++ .../src/events/cryptotalk/nym-vpn.md | 51 ++ 15 files changed, 754 insertions(+), 485 deletions(-) delete mode 100644 documentation/dev-portal/src/events/37c3/nym-vpn.md delete mode 100644 documentation/dev-portal/src/events/37c3/welcome.md rename documentation/dev-portal/src/events/{37c3 => cryptotalk}/images/image1.png (100%) rename documentation/dev-portal/src/events/{37c3 => cryptotalk}/images/image2.png (100%) rename documentation/dev-portal/src/events/{37c3 => cryptotalk}/images/image3.png (100%) rename documentation/dev-portal/src/events/{37c3 => cryptotalk}/images/image4.png (100%) rename documentation/dev-portal/src/events/{37c3 => cryptotalk}/images/image5.png (100%) rename documentation/dev-portal/src/events/{37c3 => cryptotalk}/images/json.png (100%) rename documentation/dev-portal/src/events/{37c3/faq.md => cryptotalk/nym-vpn-faq.md} (64%) create mode 100644 documentation/dev-portal/src/events/cryptotalk/nym-vpn-linux.md create mode 100644 documentation/dev-portal/src/events/cryptotalk/nym-vpn-mac.md create mode 100644 documentation/dev-portal/src/events/cryptotalk/nym-vpn-testing.md create mode 100644 documentation/dev-portal/src/events/cryptotalk/nym-vpn-troubleshooting.md create mode 100644 documentation/dev-portal/src/events/cryptotalk/nym-vpn.md diff --git a/documentation/dev-portal/src/SUMMARY.md b/documentation/dev-portal/src/SUMMARY.md index 42c25632a2..0e761b86cd 100644 --- a/documentation/dev-portal/src/SUMMARY.md +++ b/documentation/dev-portal/src/SUMMARY.md @@ -24,7 +24,7 @@ - [NymConnect X Electrum](tutorials/electrum.md) - [NymConnect X Firo wallet](tutorials/firo.md) -# Code Examples +# Code Examples - [Custom Service Providers](examples/custom-services.md) - [Apps Using Network Requesters](examples/using-nrs.md) @@ -49,9 +49,9 @@ - [Preparing Your Service](tutorials/cosmos-service/service.md) - [Preparing Your Service pt2](tutorials/cosmos-service/service-src.md) - [Querying the Chain](tutorials/cosmos-service/querying.md) - + - [Typescript](tutorials/typescript.md) - - [Simple Service Provider](tutorials/simple-service-provider/simple-service-provider.md) + - [Simple Service Provider](tutorials/simple-service-provider/simple-service-provider.md) - [Tutorial Overview](tutorials/simple-service-provider/overview.md) - [Preparing Your User Client Environment](tutorials/simple-service-provider/preparating-env.md) - [Building Your User Client](tutorials/simple-service-provider/user-client.md) @@ -68,6 +68,12 @@ # Events +- [CryptoTalk](events/cryptotalk/nym-vpn.md) + - [NymVPN Linux Guide](events/cryptotalk/nym-vpn-linux.md) + - [NymVPN MacOS Guide](events/cryptotalk/nym-vpn-mac.md) + - [NymVPN Testing](events/cryptotalk/nym-vpn-testing.md) + - [NymVPN Troubleshooting](events/cryptotalk/nym-vpn-troubleshooting.md) + - [NymVPN FAQ](events/cryptotalk/nym-vpn-faq.md) - [Web3Privacy Now](./events/web3-privacy.md) - [HCPP23-serinko](./events/hcpp23-serinko.md) - [HCPP23-max](./events/hcpp23-max.md) @@ -83,7 +89,7 @@ - [Community Applications and Guides](community-resources/community-applications-and-guides.md) - [Change Service Grantee Information](info-request.md) ---- +--- # Misc. - [Code of Conduct](coc.md) - [Licensing](licensing.md) diff --git a/documentation/dev-portal/src/events/37c3/nym-vpn.md b/documentation/dev-portal/src/events/37c3/nym-vpn.md deleted file mode 100644 index 6b94d26a41..0000000000 --- a/documentation/dev-portal/src/events/37c3/nym-vpn.md +++ /dev/null @@ -1,457 +0,0 @@ -# NymVPN alpha - -Nym has announced [NymVPN](https://nymvpn.com/en) and presented the [NymVPN Litepaper](https://nymvpn.com/nymVPN-litepaper.pdf). At CCC 2023 we have the unique opportunity to do the first alpha public testing. This page provides a how to guide, explaining steps to install and run NymVPN CLI and GUI on the Nym Sandbox testnet. - -NymVPN is a client that uses [Nym Mixnet](https://nymtech.net) to anonymise users entire internet traffic. - -The default is to run in 5-hop mode: - -``` - ┌─►mix──┐ mix mix - │ │ - Entry │ │ Exit -client ───► Gateway ──┘ mix │ mix ┌─►mix ───► Gateway ───► internet - │ │ - │ │ - mix └─►mix──┘ mix -``` - -Users can switch to 2-hop only mode, which is a faster but less private option. In this mode traffic is only sent between the two Gateway's, and is not passed between Mix Nodes. - -The client can optionally do the first connection to the entry gateway using Wireguard. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device. - -```admonish warning -NymVPN is an experimental software and it's for [testing](./nym-vpn.md#testing) purposes only. All users testing the client are expected to sign GDPR Information Sheet and Consent Form (shared at the event), and follow the steps listed in the form [*NymVPN User research at 37c3*](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko). -``` - -## Goals - -This alpha testing will help: - -* Stabilise NymVPN client -* Understand NymVPN client behavior in various setups (OS, connectivity, etc.) -* Stabilize the VPN infrastructure and improve its reliability / speed / features (e.g. IPv6 support) -* Load test the network in Sandbox environment and identify / anticipate potential weaknesses - - -```admonish info -Our alpha testing round is done live with some participants at CCC 2023. This guide will not work for everyone, as the NymVPN binaries aren't publicly accessible yet. Note that this setup of Nym testnet Sandbox environment is limited for CCC 2023 event and some of the configurations will not work in the future. -``` - -> **If you commit to test NymVPN alpha, please start with the [user research form](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko) where all the steps will be provided**. - -## Preparation - -> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. - -We have CLI and UI binaries available for Linux (Debian based) and macOS. - -![](images/image1.png) - -* Visit the [releases page](https://github.com/nymtech/nym/releases/tag/ccc) to download the binary for your system. -* Open terminal in the same directory and make executable by running: - -```sh -# for CLI -chmod +x ./nym-vpn-cli - -# for GUI -chmod +x ./nym-vpn_0.0.0_amd64.AppImage -# make sure your path to package is correct and the package name as well -``` - -* If you prefer to use the `.deb` version for installation (Linux only), open terminal in the same directory and run: -``` -sudo dpkg -i ./.deb -# or -sudo apt-get install -f ./.deb -``` - -* For CLI: 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. In case of GUI setup, see the steps below. - -### GUI configuration - -* Create a NymVPN config directory called `nym-vpn` in your `~/.config`, either manually or by a command: -```sh -# for Linux -mkdir $HOME/.config/nym-vpn/ - -# for macOS -mkdir $HOME/Library/Application Support/nym-vpn/ -``` -* Create the network config by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the directory `nym-vpn` you just created -* Create the main config file called `config.toml` in the same directory with this content: -```toml -# for Linux -env_config_file = "/home//.config/nym-vpn/sandbox.env" # change to your username -entry_node_location = "DE" # two letters country code - -# for macOS -env_config_file = "$HOME/Library/Application Support/nym-vpn/" -entry_node_location = "DE" # two letters country code -``` - -## Running - -***For NymVPN to work, all other VPNs must be switched off!*** - -**Note:** At this alpha stage of NymVPN, network connection (wifi) must be re-connected after or in-between NymVPN testing rounds. - -* Get your private key for wireguard setup [here](https://nymvpn.com/en/37c3) -* See a JSON list of all Gateways [here](https://nymvpn.com/en/ccc/api/gateways) -* As NymVPN need a permission for network settings, it is run with `sudo` root command - -### CLI - -Make sure your terminal is open in the same directory as your `nym-vpn-cli` binary. - -```admonish info -The entire command syntax with all the needed arguments' values and your private key for testing purposes can be found on our event webpage [nymvpn.com/en/37c3](https://nymvpn.com/en/37c3). -``` - -Running a help command: - -```sh -./nym-vpn-cli --help -``` - -~~~admonish example collapsible=true title="Console output" -``` -Usage: nym-vpn-cli [OPTIONS] - -Options: - -c, --config-env-file - Path pointing to an env file describing the network - --mixnet-client-path - Path to the data directory of a previously initialised mixnet client, where the keys reside - --entry-gateway-id - Mixnet public ID of the entry gateway - --entry-gateway-country - Auto-select entry gateway by country ISO - --exit-router-address - Mixnet recipient address - --exit-gateway-id - - --exit-router-country - Mixnet recipient address - --enable-wireguard - Enable the wireguard traffic between the client and the entry gateway - --private-key - Associated private key - --wg-ip - The IP address of the wireguard interface - --ip - The IP address of the TUN device - --mtu - The MTU of the TUN device - --disable-routing - Disable routing all traffic through the VPN TUN device - --enable-two-hop - 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 - -h, --help - Print help - -V, --version - Print version - - -``` -~~~ - -To run the CLI a few things need to be specified: - -```sh -sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id --exit-router-address --enable-wireguard --private-key --wg-ip -``` - -### Options Flags - -Here is a list of the options and their descriptions. Some are essential, some are more technical and not needed to adjusted by users: - -- `-c` is a path to the [Sandbox config](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) file saved as `sandbox.env` -- `--entry-gateway-id`: paste one of the values labeled with a key `"identityKey"` (without `" "`) from [here](https://nymvpn.com/en/ccc/api/gateways) -- `--exit-router-address`: paste one of the values labeled with a key `"address"` (without `" "`) from here [here](https://nymvpn.com/en/ccc/api/gateways) -- `--enable-wireguard`: Enable the wireguard traffic between the client and the entry gateway. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device -- `--wg-ip`: The address of the wireguard interface, you can get it [here](https://nymvpn.com/en/37c3) -- `--private-key`: get your private key for testing purposes [here](https://nymvpn.com/en/37c3) -- `--enable-two-hop` is a faster setup where the traffic is routed from the client to Entry Gateway and directly to Exit Gateway (default is 5-hops) - -**More advanced options** - -- `--enable-poisson`: Enables process rate limiting of outbound traffic (disabled by default). It means that NymVPN client will send packets at a steady stream to the Entry Gateway. By default it's on average one sphinx packet per 20ms, but there is some randomness (poisson distribution). When there are no real data to fill the sphinx packets with, cover packets are generated instead. -- `--ip` is the IP address of the TUN device. That is the IP address of the local private network that is set up between local client and the Exit Gateway. -- `--mtu`: The MTU of the TUN device. That is the max IP packet size of the local private network that is set up between local client and the Exit Gateway. -- `--disable-routing`: Disable routing all traffic through the VPN TUN device. - -### GUI - -If you installed the `.deb` package you may be able to have a NymVPN application icon in your app menu. However this may not work as the application needs root permission. - -Make sure you went through the GUI configuration in the [preparation section](./nym-vpn.md#gui-configuration). Then open terminal in the same directory where you [installed](./nym-vpn.md#preparation) the binary run: - -```sh -sudo -E ./nym-vpn_0.0.0_amd64.AppImage - -# In case you use another binary, just add the correct name as: -sudo -E ./ -``` - -In case of errors, see [troubleshooting section](./nym-vpn.md#macos-alert-on-nymvpn-ui-startup). - - -## Testing - -One of the main aims of the demo is testing; your results will help us to make NymVPN robust and stabilise both the client and the network through provided measurements. Before you go into testing, make sure you went through [preparation steps](./nym-vpn.md#preparation) and the [CLI binary](https://github.com/nymtech/nym/releases/tag/ccc) for your system is ready to run. - -1. Create a directory called `nym-vpn-tests` and copy your `nym-vpn-cli` binary and `sandbox.env` to that directory -2. Copy the [block below](./nym-vpn.md#testssh) and save it to the same folder as `tests.sh` -3. Open terminal in the same directory -4. Turn off any existing VPN's (including the NymVPN instances) and make the script executable by running `chmod +x ./tests.sh` -5. Run the tests: `sudo ./tests.sh` -6. In case of errors, see [troubleshooting section](./nym-vpn.md#missing-jq-error) below -7. The script will print a JSON view of existing Gateways and prompt you to: - - ***(Make sure to use two different Gateways for entry and exit!)*** - - `enter a gateway ID:` paste one of the values labeled with a key `"identityKey"` printed above (without `" "`) - - `enter an exit address:` paste one of the values labeled with a key `"address"` printed above (without `" "`) - - `enable WireGuard? (yes/no):` if you chose yes, find your private key and wireguard IP [here](https://nymvpn.com/en/37c3) -8. Note that the testing script doesn't print many logs, in case of doubts you can check logs in the log file `temp_log.txt` located in the same directory. -9. The script shall run the tests and generate a folder called `tests_` and files `perf_test_results.log` or `two_hop_perf_test_results.log` as well as some temp files. This is how the directory structure will look like: -```sh -nym-vpn-tests -├── tests.sh -├── nym-vpn-cli -├── sandbox.env -├── perf_test_results.log -├── tests_ -│   ├── api_response_times.txt -│   ├── download_time.txt -│   └── ping_results.txt -├── timeout -└── two_hop_perf_test_results.log -``` -10. In case of errors, see [troubleshooting section](./nym-vpn.md#missing-jq-error) below -11. When the tests are finished, remove the `nym-vpn-cli` binary from the folder and compress it as `nym-vpn-tests.zip` -12. Upload this compressed file to the [questionnaire](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko) upload field when prompted. - -#### tests.sh - -```sh -#!/bin/bash - -ENDPOINT="https://sandbox-nym-api1.nymtech.net/api/v1/gateways/described" -json_array=() -echo "🚀 🏎 - please be patient, i'm fetching you your entry points - 🚀 🏎 " - -data=$(curl -s "$ENDPOINT" | jq -c '.[] | {host: .bond.gateway.host, hostname: .self_described.host_information.hostname, identity_key: .bond.gateway.identity_key, exitGateway: .self_described.ip_packet_router.address}') - -while IFS= read -r entry; do - host=$(echo "$entry" | jq -r '.host') - hostname=$(echo "$entry" | jq -r '.hostname') - identity_key=$(echo "$entry" | jq -r '.identity_key') - exit_gateway_address=$(echo "$entry" | jq -r '.exitGateway // empty') - valid_ip=$(echo "$host") - - if [ -n "$exit_gateway_address" ]; then - exit_gateway="{\"address\": \"${exit_gateway_address}\"}" - else - exit_gateway="{}" - fi - if [[ $valid_ip =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then - country_info=$(curl -s "http://ipinfo.io/${valid_ip}/country" | tr -d '\n') - country_info_escaped=$(echo "$country_info" | tr -d '\n' | jq -aRs . | tr -d '"') - else - country_info_escaped="" - fi - json_object="{\"hostname\": \"${hostname}\", \"identityKey\": \"${identity_key}\", \"exitGateway\": ${exit_gateway}, \"location\": \"${country_info_escaped}\"}" - json_array+=("$json_object") -done < <(echo "$data") - -if [ $? -ne 0 ]; then - echo "error fetching data from endpoint" - exit 1 -fi - -download_file() { - local file_url=$1 - local output_file=$2 - local time_file=$3 - - echo "starting download speed test..." - local start_time=$(date +%s) - if [[ "$OSTYPE" == "linux-gnu"* ]]; then - wget -O $output_file $file_url - elif [[ "$OSTYPE" == "darwin"* ]]; then - curl -o $output_file $file_url - fi - local end_time=$(date +%s) - local elapsed_time=$((end_time - start_time)) - echo "download speed test completed in $elapsed_time seconds." >"$time_file" -} - -if ! command -v jq &>/dev/null; then - echo "jq is not installed. Please install jq to proceed." - exit 1 -fi - -temp_log_file="temp_log.txt" - -perform_tests() { - local gateway_id=$1 - local exit_address=$2 - local test_directory="tests_${gateway_id}_${exit_address}" - local file_url="http://ipv4.download.thinkbroadband.com/2MB.zip" - - mkdir -p "$test_directory" - local ping_results_file="${test_directory}/ping_results.txt" - local download_time_file="${test_directory}/download_time.txt" - local api_response_file="${test_directory}/api_response_times.txt" - - # ping test - echo "starting ping test..." - for site in google.com youtube.com facebook.com baidu.com wikipedia.org amazon.com twitter.com instagram.com yahoo.com ebay.com netflix.com; do - ping -c 4 $site >>"$ping_results_file" - done - echo "ping test completed. Results saved in $ping_results_file" - - # download speed test - download_file $file_url /dev/null "$download_time_file" - - # api test - local api_endpoint="https://validator.nymtech.net/api/v1/mixnodes" - local iterations=10 - >"$api_response_file" - for i in $(seq 1 $iterations); do - local start_time=$(date +%s) - local response=$(curl -s -o /dev/null -w '%{http_code}' $api_endpoint) - local end_time=$(date +%s) - - local elapsed_seconds=$((end_time - start_time)) - local hours=$((elapsed_seconds / 3600)) - local minutes=$(((elapsed_seconds % 3600) / 60)) - local seconds=$((elapsed_seconds % 60)) - - local human_readable_time=$(printf "%02dh:%02dm:%02ds" $hours $minutes $seconds) - echo "iteration $i: response Time = ${human_readable_time}, status code = $response" >>"$api_response_file" - done - echo "api response test completed. Results saved in $api_response_file." -} - -printf "%s\n" "${json_array[@]}" | jq -s . - -read -p "enter a gateway ID: " identity_key -read -p "enter an exit address: " exit_address - -while true; do - read -p "enable WireGuard? (yes/no): " enable_wireguard - enable_wireguard=$(echo "$enable_wireguard" | tr '[:upper:]' '[:lower:]') - - case "$enable_wireguard" in - "yes") - read -p "enter your WireGuard private key: " priv_key - read -p "enter your WireGuard IP: " wg_ip - wireguard_options="--enable-wireguard --private-key $priv_key --wg-ip $wg_ip" - break - ;; - "no") - wireguard_options="" - break - ;; - *) - echo "invalid response. please enter 'yes' or 'no'." - ;; - esac -done - -sudo ./nym-vpn-cli -c sandbox.env --entry-gateway-id ${identity_key} --exit-router-address ${exit_address} --enable-two-hop $wireguard_options >"$temp_log_file" 2>&1 & - -timeout=15 -start_time=$(date +%s) -while true; do - current_time=$(date +%s) - if grep -q "received plain" "$temp_log_file"; then - echo "successful configuration with identity_key: $identity_key and exit address: $exit_address" >>perf_test_results.log - perform_tests "$identity_key" "$exit_address" - break - fi - if ((current_time - start_time > timeout)); then - echo "failed to connect with identity_key: $identity_key using the exit address: $exit_address" >>perf_test_results.log - break - fi - sleep 1 -done - -echo "terminating nym-vpn-cli..." -pkill -f './nym-vpn-cli' -sleep 5 -rm -f "$temp_log_file" - -``` - -## Troubleshooting - -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 event. - -#### Thread `main` panicked - -If you see a message like: -```sh -thread 'main' panicked at /Users/runner/.cargo/git/checkouts/mullvadvpn-app-a575cf705b5dfd76/ccfbaa2/talpid-routing/src/unix.rs:301:30: -``` -Restart your wifi connection and start again. - -#### macOS alert on NymVPN UI startup - -If you are running NymVPN on mac OS for the first time, you may see this alert message: - -![](images/image3.png) - -1. Head to System Settings -> Privacy & Security and click `Allow anyway` - -![](images/image5.png) - -2. Confirm with your password or TouchID - -3. Possibly you may have to confirm again upon running the application - -#### Missing `jq` error - -In case of missing `jq` on Linux (Debian) install it with: -```sh -# Linux (Debian) -sudo apt-get install jq -# macOS -brew install jq -``` -On some Linux distributions however the [script](./nym-vpn.md#testssh) returns `jq` error even if your system claims that `jq is already the newest version`. -In that case, comment the `jq` check in the script as follows: -```sh -#if ! command -v jq &>/dev/null; then -# echo "jq is not installed. Please install jq to proceed." -# exit 1 -#fi -``` - -#### Error current_time: not found - -When running `sudo sh ./test.sh` you may see an error like: `93: current_time: not found`. This has something to do with the `current_time` setup of your system and on itself shall not have a negative impact on the test. It has nothing to do with the client at all as it only relates to the code in our testing script. - -#### Not connecting to the endpoint - -In case the automatic download of all the Gateways fail (and it shouldn't), you do an easy manual work around: - -1. Open the list of Gateways created by API [here](https://nymvpn.com/en/ccc/api/gateways) -2. On top click on `JSON` option (shall be default view) and `Save` -3. Save it as `data.json` to the `nym-vpn-tests` folder -4. Replace line 3 in the [script `tests.sh`](./nym-vpn.md#testssh) with: -```sh -NEW_ENDPOINT="http://localhost:8000/data.json" -``` -5. In a new terminal window run: -```sh -python3 -m http.server 8000 -``` -6. Continue with the steps listed in [testing section](./nym-vpn.md#testing) - - - diff --git a/documentation/dev-portal/src/events/37c3/welcome.md b/documentation/dev-portal/src/events/37c3/welcome.md deleted file mode 100644 index f7ead77c08..0000000000 --- a/documentation/dev-portal/src/events/37c3/welcome.md +++ /dev/null @@ -1,14 +0,0 @@ -# Chaos Communication Congress 2023 - -At [CCC 2019](https://constructiveproof.com/posts/2020-01-27-nym-testnet-up-and-running/) we announced the first demo of the [Nym Mixnet](https://github.com/nymtech/nym). Now, four years later we are honoured to present our new product: [NymVPN](https://blog.nymtech.net/nymvpn-an-invitation-for-privacy-experts-and-enthusiasts-63644139d09d). NymVPN is a client/application which captures the entire network stack of a user's device, sending this traffic through either a 2-hop VPN or through the 5-hop Mixnet. CCC 2023 is the first public demo of both the GUI and CLI versions of NymVPN. - -At first glance Nym platform may seem pretty complex. To make the connection between Nym and the community of developers, operators and users participating on the event as smooth as possible, we created a segment of documentation tailored specifically for the conference. The following pages provide an easy introduction to the NymVPN alpha client. We recommend interested developers to begin with [Nym network overview](https://nymtech.net/docs/architecture/network-overview.html) and the [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) pages. - -**See pages below for more content:** - -* [NymVPN alpha guide](nym-vpn.md) -* [FAQ @ 37c3](faq.md) - -
- - diff --git a/documentation/dev-portal/src/events/37c3/images/image1.png b/documentation/dev-portal/src/events/cryptotalk/images/image1.png similarity index 100% rename from documentation/dev-portal/src/events/37c3/images/image1.png rename to documentation/dev-portal/src/events/cryptotalk/images/image1.png diff --git a/documentation/dev-portal/src/events/37c3/images/image2.png b/documentation/dev-portal/src/events/cryptotalk/images/image2.png similarity index 100% rename from documentation/dev-portal/src/events/37c3/images/image2.png rename to documentation/dev-portal/src/events/cryptotalk/images/image2.png diff --git a/documentation/dev-portal/src/events/37c3/images/image3.png b/documentation/dev-portal/src/events/cryptotalk/images/image3.png similarity index 100% rename from documentation/dev-portal/src/events/37c3/images/image3.png rename to documentation/dev-portal/src/events/cryptotalk/images/image3.png diff --git a/documentation/dev-portal/src/events/37c3/images/image4.png b/documentation/dev-portal/src/events/cryptotalk/images/image4.png similarity index 100% rename from documentation/dev-portal/src/events/37c3/images/image4.png rename to documentation/dev-portal/src/events/cryptotalk/images/image4.png diff --git a/documentation/dev-portal/src/events/37c3/images/image5.png b/documentation/dev-portal/src/events/cryptotalk/images/image5.png similarity index 100% rename from documentation/dev-portal/src/events/37c3/images/image5.png rename to documentation/dev-portal/src/events/cryptotalk/images/image5.png diff --git a/documentation/dev-portal/src/events/37c3/images/json.png b/documentation/dev-portal/src/events/cryptotalk/images/json.png similarity index 100% rename from documentation/dev-portal/src/events/37c3/images/json.png rename to documentation/dev-portal/src/events/cryptotalk/images/json.png diff --git a/documentation/dev-portal/src/events/37c3/faq.md b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-faq.md similarity index 64% rename from documentation/dev-portal/src/events/37c3/faq.md rename to documentation/dev-portal/src/events/cryptotalk/nym-vpn-faq.md index 3fc48ea00b..9f7cf619b3 100644 --- a/documentation/dev-portal/src/events/37c3/faq.md +++ b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-faq.md @@ -1,16 +1,16 @@ -# Frequently Asked Questions @ 37C3 +# Frequently Asked Questions -This is a FAQ page tailored for CCC 2023 event (37c3). If you interested to read more about Nym platform, you can have a look at [Nym general FAQ](https://nymtech.net/developers/faq/general-faq.html) and read through Nym's technical [documentation](https://nymtech.net/docs), [Developer Portal](https://nymtech.net/developers) and [Operators Guide](https://nymtech.net/operators). +This is a FAQ page tailored for this event. If you interested to read more about Nym platform, you can have a look at [Nym general FAQ](https://nymtech.net/developers/faq/general-faq.html) and read through Nym's technical [documentation](https://nymtech.net/docs), [Developer Portal](https://nymtech.net/developers) and [Operators Guide](https://nymtech.net/operators). ## NymVPN -If this your first time hearing about NymVPN, make sure you read [NymVPN webpage](https://nymvpn.com/en), the official [support & FAQ page](https://nymvpn.com/en/support) and our guide on how to [install, run and test](./nym-vpn.md) the client. +If this your first time hearing about NymVPN, make sure you visit [NymVPN webpage](https://nymvpn.com/en), the official NymVPN [support & FAQ page](https://nymvpn.com/en/support) and the proceed to the introduction and guide on how to [install, run and test](./nym-vpn.md) the client. -Below are some extra FAQ's which came out during the event. +Below are some extra FAQs which came out during the initial alpha testing round. ### What's the difference between 2-hops and 5-hops -The default is 5-hops (including Entry and Exit Gateways), which means that the traffic goes from the local client to Entry Gateway -> though 3 layes of Mix Nodes -> to Exit Gateway -> internet. this option uses all the Nym Mixnet features for maximum privacy. +The default is 5-hops (including Entry and Exit Gateways), which means that the traffic goes from the local client to Entry Gateway -> through 3 layers of Mix Nodes -> to Exit Gateway -> internet. this option uses all the Nym Mixnet features for maximum privacy. ``` ┌─►mix──┐ mix mix @@ -22,7 +22,7 @@ client ───► Gateway ──┘ mix │ mix ┌─►mix ───► mix └─►mix──┘ mix ``` -The 2-hop option is going from the local client -> Entry Gateway -> directly to Exit Gateway -> internet. This option is good for operations demanding faster connection. Keep in mind that this setup by-passes the 3 layers of Mix Nodes. +The 2-hop option is going from the local client -> Entry Gateway -> directly to Exit Gateway -> internet. This option is good for operations demanding faster connection. Keep in mind that this setup by-passes the 3 layers of Mix Nodes. The anonymising features done by your local client like breaking data into same-size packets with inserting additional "dummy" ones to break the time and volume patterns is done in both options. ``` Entry Exit @@ -50,15 +50,15 @@ We have a list of questions related to Nym Nodes and the incentives behind runni ## Project Smoosh -Project Smoosh is a code name for a process in which different components of Nym Mixnet architecture get *smooshed* into one binary. Check out [Smoosh FAQ](https://nymtech.net/operators/faq/smoosh-faq.html) in Operators Guide to read more. +Project Smoosh is a code name for a process in which different components of Nym Mixnet architecture get *smooshed* into one binary. Check out [Smoosh FAQ](https://nymtech.net/operators/faq/smoosh-faq.html) in Operators Guide to read more. ## Exit Gateway -Part of the the transition under code name [Project Smoosh](./faq.md#project-smoosh) is a creation of [Nym Exit Gateway](https://nymtech.net/operators/legal/exit-gateway.html) functionality. The operators running Gateways would have to “open” their nodes to a wider range of online services, in a similar fashion to Tor exit relays. The main change will be to expand the original short [allowed.list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to a more permissive setup. An [exit policy](https://nymtech.net/.wellknown/network-requester/exit-policy.txt) will constrain the hosts that the users of the Nym VPN and Mixnet can connect to. This will be done in an effort to protect the operators, as Gateways will act both as SOCKS5 Network Requesters, and exit nodes for IP traffic from Nym VPN and Mixnet clients. +Part of the the transition under code name [Project Smoosh](./nym-vpn-faq.md#project-smoosh) is a creation of [Nym Exit Gateway](https://nymtech.net/operators/legal/exit-gateway.html) functionality. The operators running Gateways would have to “open” their nodes to a wider range of online services, in a similar fashion to Tor exit relays. The main change will be to expand the original short [allowed.list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to a more permissive setup. An [exit policy](https://nymtech.net/.wellknown/network-requester/exit-policy.txt) will constrain the hosts that the users of the Nym VPN and Mixnet can connect to. This will be done in an effort to protect the operators, as Gateways will act both as SOCKS5 Network Requesters, and exit nodes for IP traffic from Nym VPN and Mixnet clients. * Read more how the exit policy gets implemented [here](https://nymtech.net/operators/faq/smoosh-faq.html#how-will-the-exit-policy-be-implemented) * Check out [Nym Operators Legal Forum](https://nymtech.net/operators/legal/exit-gateway.html) -* Do reach out to us during 37c3 with any experiences you may have running Tor Exit relays or legal findings and suggestions for Nym Exit Gateway operators +* Do reach out to us during 37c3 with any experiences you may have running Tor Exit relays or legal findings and suggestions for Nym Exit Gateway operators ## Nym Integrations and SDKs @@ -67,4 +67,3 @@ If you are a dev who is interested to integrate Nym, have a look on our SDK tuto * [Rust SDKs](https://nymtech.net/developers/tutorials/cosmos-service/intro.html) * [TypeScript SDKs](https://sdk.nymtech.net/) * [Integration FAQ](https://nymtech.net/developers/faq/integrations-faq.html) - diff --git a/documentation/dev-portal/src/events/cryptotalk/nym-vpn-linux.md b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-linux.md new file mode 100644 index 0000000000..eb053c25e8 --- /dev/null +++ b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-linux.md @@ -0,0 +1,198 @@ +# NymVPN alpha: Guide for GNU/Linux + +```admonish warning +NymVPN is an experimental software and it's for [testing](./nym-vpn-testing.md) purposes only. All users testing the client are expected to sign GDPR Information Sheet and Consent Form (shared at the event), and follow the steps listed in the form [*NymVPN User research*](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2). +``` + +## Preparation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +You can use our automated script of follow the steps below to download, verify, install and run NymVPN client. + + +### Automated Script CLI Installation + +Open a terminal and follow these steps: + +* Download the script +```sh +curl -o nym-vpn-cli-executor.sh -L https://gist.githubusercontent.com/tommyv1987/87267ded27e1eb7651aa9cc745ddf4af/raw/99cea8f4d80f2d002802ed1cbedba288bfca4488/execute-nym-vpn-cli-binary.sh +``` +* Make the script executable +```sh +chmod u+x nym-vpn-cli-executor.sh +``` +* Run the script +```sh +./nym-vpn-cli-executor.sh +``` +* When prompted to verify `sha256sum` paste one from the [release page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) including the binary name (all as one input with a space in between), for example: +```sh +61a08de46881411e140f66cdb4940041150adb573c10e3f510a58a86a32f08fb nym-vpn-cli-ubuntu-22.04.zip +``` + +The script will automatically start the client. Follow the instructions: + +* The script will print a JSON view of existing Gateways and prompt you to: + - ***(Make sure to use two different Gateways for entry and exit!)*** + - `enter a gateway ID:` paste one of the values labeled with a key `"identityKey"` printed above (without `" "`) + - `enter an exit address:` paste one of the values labeled with a key `"address"` printed above (without `" "`) + - `do you want five hop or two hop?`: type `five` or `two` + +### Manual CLI and GUI Installation + +* Visit the [releases page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) to download the binary for Debian based Linux +* Open terminal in the same directory and check the the `sha256sum` by running: +```sh +# for CLI +sha256sum ./nym-vpn-cli_0.1.0_ubuntu-22.04_amd64.zip + +# for GUI +sha256sum ./nym-vpn-ui_0.0.2_ubuntu-22.04_amd64.zip +``` +* Compare the result with the sha256 hash shared on the [release page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) +* Extract files with `unzip` command or manually as you are used to +* If you prefer to run `.AppImage` make executable by running: +```sh +# for CLI +chmod +x ./nym-vpn-cli + +# for GUI +chmod +x ./appimage/nym-vpn_0.0.2_amd64.AppImage +# make sure your path to package is correct and the package name as well +``` +* If you prefer to use the `.deb` version for installation (Linux only), open terminal in the same directory and run: +```sh +cd deb + +sudo dpkg -i ./nym-vpn_0.0.2_amd64.deb + +# or +sudo apt-get install -f ./nym-vpn_0.0.2_amd64.deb + +``` +* **For CLI**: 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. In case of GUI setup, see the steps below. + +### GUI configuration + +* Create a NymVPN config directory called `nym-vpn` in your `~/.config`, either manually or by a command: +```sh +# for Linux +mkdir $HOME/.config/nym-vpn/ +``` +* Create the network config by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the directory `nym-vpn` you just created +* Create the main config file called `config.toml` in the same directory with this content: +```toml +# change to your username +env_config_file = "/home//.config/nym-vpn/sandbox.env" +entry_node_location = "DE" # two letters country code +``` + +## Run NymVPN + +* **For NymVPN to work, all other VPNs must be switched off!** +* At this alpha stage of NymVPN, network connection (wifi) must be re-connected after or in-between NymVPN testing rounds. + +### Run CLI + +Make sure your terminal is open in the same directory as your `nym-vpn-cli` binary. + +* Find the entire command with all the needed arguments' values and your wireguard private key for testing purposes at [nymvpn.com/en/alpha](https://nymvpn.com/en/alpha) +* Run it with `sudo` as root, the command will look like this with specified arguments: +```sh +sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id --exit-router-address --enable-wireguard --private-key --wg-ip +``` +* To chose different Gateways, visit [nymvpn.com/en/alpha/api/gateways](https://nymvpn.com/en/alpha/api/gateways) +* To see all possibilities see [command explanation](#cli-commands-and-options) below + +### Run GUI + +In case you used `.deb` package and installed the client, you may be able to have a NymVPN application icon in your app menu. However this may not work as the application needs root permission. + +Make sure you went through the GUI configuration in the [preparation section](#gui-configuration). Then open terminal in the same directory where you [installed](#preparation) the binary and run: + +```sh +# .AppImage must be run from the same directory +sudo -E ./nym-vpn_0.0.2_amd64.AppImage + +# .deb installation shall be executable from anywhere as +sudo -E nym-vpn +``` + +In case of errors, see [troubleshooting section](./nym-vpn-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 --exit-router-address --enable-wireguard --private-key --wg-ip +``` +* To chose 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 +``` + +~~~admonish example collapsible=true title="Console output" +``` +Usage: nym-vpn-cli [OPTIONS] + +Options: + -c, --config-env-file + Path pointing to an env file describing the network + --mixnet-client-path + Path to the data directory of a previously initialised mixnet client, where the keys reside + --entry-gateway-id + Mixnet public ID of the entry gateway + --entry-gateway-country + Auto-select entry gateway by country ISO + --exit-router-address + Mixnet recipient address + --exit-gateway-id + + --exit-router-country + Mixnet recipient address + --enable-wireguard + Enable the wireguard traffic between the client and the entry gateway + --private-key + Associated private key + --wg-ip + The IP address of the wireguard interface + --ip + The IP address of the TUN device + --mtu + The MTU of the TUN device + --disable-routing + Disable routing all traffic through the VPN TUN device + --enable-two-hop + 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 + -h, --help + Print help + -V, --version + Print version + + +``` +~~~ + +**Fundamental commands and arguments** + +Here is a list of the options and their descriptions. Some are essential, some are more technical and not needed to adjusted by users: + +- `-c` is a path to the [Sandbox config](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) file saved as `sandbox.env` +- `--entry-gateway-id`: paste one of the values labeled with a key `"identityKey"` (without `" "`) from [here](https://nymvpn.com/en/alpha/api/gateways) +- `--exit-router-address`: paste one of the values labeled with a key `"address"` (without `" "`) from here [here](https://nymvpn.com/en/alpha/api/gateways) +- `--enable-wireguard`: Enable the wireguard traffic between the client and the entry gateway. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device +- `--wg-ip`: The address of the wireguard interface, you can get it [here](https://nymvpn.com/en/alpha) +- `--private-key`: get your private key for testing purposes [here](https://nymvpn.com/en/alpha) +- `--enable-two-hop` is a faster setup where the traffic is routed from the client to Entry Gateway and directly to Exit Gateway (default is 5-hops) + +**Advanced options** + +- `--enable-poisson`: Enables process rate limiting of outbound traffic (disabled by default). It means that NymVPN client will send packets at a steady stream to the Entry Gateway. By default it's on average one sphinx packet per 20ms, but there is some randomness (poisson distribution). When there are no real data to fill the sphinx packets with, cover packets are generated instead. +- `--ip` is the IP address of the TUN device. That is the IP address of the local private network that is set up between local client and the Exit Gateway. +- `--mtu`: The MTU of the TUN device. That is the max IP packet size of the local private network that is set up between local client and the Exit Gateway. +- `--disable-routing`: Disable routing all traffic through the VPN TUN device. diff --git a/documentation/dev-portal/src/events/cryptotalk/nym-vpn-mac.md b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-mac.md new file mode 100644 index 0000000000..8c7eeb417c --- /dev/null +++ b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-mac.md @@ -0,0 +1,191 @@ +# NymVPN alpha: Guide for Mac OS + +```admonish warning +NymVPN is an experimental software and it's for [testing](./nym-vpn-testing.md) purposes only. All users testing the client are expected to sign GDPR Information Sheet and Consent Form (shared at the event), and follow the steps listed in the form [*NymVPN User research*](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2). +``` + +## Preparation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +### CLI Installation + +You can use our automated script of follow the steps below to download, verify, install and run NymVPN client. + +#### Automated Script CLI Installation + +Open a terminal and follow these steps: + +* Download the script +```sh +curl -o nym-vpn-client-executor.sh -L https://gist.githubusercontent.com/tommyv1987/87267ded27e1eb7651aa9cc745ddf4af/raw/99cea8f4d80f2d002802ed1cbedba288bfca4488/execute-nym-vpn-cli-binary.sh +``` +* Make the script executable +```sh +chmod u+x nym-vpn-client-executor.sh +``` +* Run the script +```sh +./nym-vpn-client-executor.sh +``` +* When prompted to verify `sha256sum` paste one from the [release page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) including the binary name (all as one input with a space in between), for example: +```sh +96623ccc69bc4cc0e4e3e18528b6dae6be69f645d0a592d926a3158ce2d0c269 nym-vpn-cli_0.1.0_macos_x86_64.zip +``` + +The script will automatically start the client. Follow the instructions: + +* The script will print a JSON view of existing Gateways and prompt you to: + - ***(Make sure to use two different Gateways for entry and exit!)*** + - `enter a gateway ID:` paste one of the values labeled with a key `"identityKey"` printed above (without `" "`) + - `enter an exit address:` paste one of the values labeled with a key `"address"` printed above (without `" "`) + - `do you want five hop or two hop?`: type `five` or `two` + +#### Manual CLI Installation + +* Visit the [releases page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) to download the binary for Debian based Linux +* Open terminal in the same directory and check the the `sha256sum` by running: +```sh +# x86_64 +sha256sum ./nym-vpn-cli_0.1.0_macos_x86_64.zip + +# aarch64 +sha256sum ./nym-vpn-cli_0.1.0_macos_aarch64.zip +``` +* Compare the result with the sha256 hash shared on the [release page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) +* Extract files with `unzip` command or manually as you are used to +```sh +# for CLI +chmod +x ./nym-vpn-cli +``` + +* 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. In case of GUI setup, see the steps below. + +### GUI Installation + +We created a [script](https://gist.github.com/tommyv1987/7d210d4daa8f7abc61f9a696d0321f19) which does download, extraction, installation and configuration for MacOS users automatically following the steps below: + +* To download the script, open a terminal in a directory where you want to download the script and run: +```sh +curl -o nym-vpn-client-executor.sh - L https://gist.githubusercontent.com/tommyv1987/7d210d4daa8f7abc61f9a696d0321f19/raw/4397365b4cf74594c7f99c1ef5d690b2f5b41192/nym-vpn-client-macos-executor.sh +``` +* Make executable +```sh +chmod u+x nym-vpn-client-macos-executor.sh +``` +* Run +```sh +./nym-vpn-client-macos-executor.sh +``` +* When prompted to verify `sha256sum` paste one from the [release page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.2) including the binary name (all as one input with a space in between), for example: +```sh +06c7c82f032f230187da1002a9a9a88242d3bbf6c5c09dc961a71df151d768d0 nym-vpn-ui_0.0.2_macos_x86_64.zip +``` +* The script will run the application and it will prompt you for a country code to exit, chose one of the offered options + +In case of errors check out the [troubleshooting](./nym-vpn-troubleshooting.html#installing-gui-on-macos-not-working) section. + +## Run NymVPN + +* **For NymVPN to work, all other VPNs must be switched off!** +* At this alpha stage of NymVPN, network connection (wifi) must be re-connected after or in-between NymVPN testing rounds. + +### Run CLI + +Make sure your terminal is open in the same directory as your `nym-vpn-cli` binary. + +* Find the entire command with all the needed arguments' values and your wireguard private key for testing purposes at [nymvpn.com/en/alpha](https://nymvpn.com/en/alpha) +* Run it with `sudo` as root, the command will look like this with specified arguments: +```sh +sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id --exit-router-address --enable-wireguard --private-key --wg-ip +``` +* To chose different Gateways, visit [nymvpn.com/en/alpha/api/gateways](https://nymvpn.com/en/alpha/api/gateways) +* To see all possibilities see [command explanation](#cli-commands-and-options) below + +### Run GUI + +Make sure you went through the GUI configuration in the [preparation section](#gui-installation). + +You may be able to have a NymVPN application icon in your app menu. However this may not work as the application needs root permission. + +* Run GUI from terminal: +```sh +sudo $nym_vpn_dir/nym-vpn +``` + +In case of errors, see [troubleshooting section](./nym-vpn-troubleshooting.md#macos-alert-on-nymvpn-ui-startup). + +### CLI Commands and Options + +The basic syntax of `nym-vpn-cli` is: +```sh +sudo ./nym-vpn-cli -c ./sandbox.env --entry-gateway-id --exit-router-address --enable-wireguard --private-key --wg-ip +``` +* To chose 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 +``` + +~~~admonish example collapsible=true title="Console output" +``` +Usage: nym-vpn-cli [OPTIONS] + +Options: + -c, --config-env-file + Path pointing to an env file describing the network + --mixnet-client-path + Path to the data directory of a previously initialised mixnet client, where the keys reside + --entry-gateway-id + Mixnet public ID of the entry gateway + --entry-gateway-country + Auto-select entry gateway by country ISO + --exit-router-address + Mixnet recipient address + --exit-gateway-id + + --exit-router-country + Mixnet recipient address + --enable-wireguard + Enable the wireguard traffic between the client and the entry gateway + --private-key + Associated private key + --wg-ip + The IP address of the wireguard interface + --ip + The IP address of the TUN device + --mtu + The MTU of the TUN device + --disable-routing + Disable routing all traffic through the VPN TUN device + --enable-two-hop + 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 + -h, --help + Print help + -V, --version + Print version + + +``` +~~~ + +**Fundamental commands and arguments** + +Here is a list of the options and their descriptions. Some are essential, some are more technical and not needed to adjusted by users: + +- `-c` is a path to the [Sandbox config](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) file saved as `sandbox.env` +- `--entry-gateway-id`: paste one of the values labeled with a key `"identityKey"` (without `" "`) from [here](https://nymvpn.com/en/alpha/api/gateways) +- `--exit-router-address`: paste one of the values labeled with a key `"address"` (without `" "`) from here [here](https://nymvpn.com/en/alpha/api/gateways) +- `--enable-wireguard`: Enable the wireguard traffic between the client and the entry gateway. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device +- `--wg-ip`: The address of the wireguard interface, you can get it [here](https://nymvpn.com/en/alpha) +- `--private-key`: get your private key for testing purposes [here](https://nymvpn.com/en/alpha) +- `--enable-two-hop` is a faster setup where the traffic is routed from the client to Entry Gateway and directly to Exit Gateway (default is 5-hops) + +**Advanced options** + +- `--enable-poisson`: Enables process rate limiting of outbound traffic (disabled by default). It means that NymVPN client will send packets at a steady stream to the Entry Gateway. By default it's on average one sphinx packet per 20ms, but there is some randomness (poisson distribution). When there are no real data to fill the sphinx packets with, cover packets are generated instead. +- `--ip` is the IP address of the TUN device. That is the IP address of the local private network that is set up between local client and the Exit Gateway. +- `--mtu`: The MTU of the TUN device. That is the max IP packet size of the local private network that is set up between local client and the Exit Gateway. +- `--disable-routing`: Disable routing all traffic through the VPN TUN device. diff --git a/documentation/dev-portal/src/events/cryptotalk/nym-vpn-testing.md b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-testing.md new file mode 100644 index 0000000000..88e7e3a949 --- /dev/null +++ b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-testing.md @@ -0,0 +1,195 @@ +# Testing NymVPN alpha + +> Before you get into testing NymVPN, make sure to go through the preparation steps for [Linux](nym-vpn-linux.md) or [MacOS](nym-vpn-mac.md). + +One of the main aims of NymVPN alpha release is testing; your results will help us to make NymVPN robust and stabilise both the client and the network through provided measurements. + +## Steps to test NymVPN + +> 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 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 `chmod +x ./tests.sh` +5. Run the tests: `sudo ./tests.sh` +6. In case of errors, see the [troubleshooting section](./nym-vpn-troubleshooting.md#missing-jq-error) below +7. The script will print a JSON view of existing Gateways and prompt you to: + - ***(Make sure to use two different Gateways for entry and exit!)*** + - `enter a gateway ID:` paste one of the values labeled with a key `"identityKey"` printed above (without `" "`) + - `enter an exit address:` paste one of the values labeled with a key `"address"` printed above (without `" "`) + - `enable WireGuard? (yes/no):` if you chose yes, find your private key and wireguard IP [here](https://nymvpn.com/en/alpha) +8. Note that the testing script doesn't print many logs, in case of doubts you can check logs in the log file `temp_log.txt` located in the same directory. +9. The script shall run the tests and generate a folder called `tests_` and files `perf_test_results.log` or `two_hop_perf_test_results.log` as well as some temp files. This is how the directory structure will look like: +```sh +nym-vpn-tests +├── tests.sh +├── nym-vpn-cli +├── sandbox.env +├── perf_test_results.log +├── tests_ +│   ├── api_response_times.txt +│   ├── download_time.txt +│   └── ping_results.txt +├── timeout +└── two_hop_perf_test_results.log +``` +10. In case of errors, see [troubleshooting section](./nym-vpn-troubleshooting.md#missing-jq-error) below +11. When the tests are finished, remove the `nym-vpn-cli` binary from the folder and compress the entire folder as `nym-vpn-tests.zip` +12. Upload this compressed file to the [questionnaire](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2) upload field when prompted + +#### tests.sh + +This is the testing script which needs to be copied and saved as `tests.sh` to your `nym-vpn-tests` folder and then run from there as described [above](#steps-to-test-nymvpn). + +```sh +#!/bin/bash + +ENDPOINT="https://sandbox-nym-api1.nymtech.net/api/v1/gateways/described" +json_array=() +echo "🚀 🏎 - please be patient, i'm fetching you your entry points - 🚀 🏎 " + +data=$(curl -s "$ENDPOINT" | jq -c '.[] | {host: .bond.gateway.host, hostname: .self_described.host_information.hostname, identity_key: .bond.gateway.identity_key, exitGateway: .self_described.ip_packet_router.address}') + +while IFS= read -r entry; do + host=$(echo "$entry" | jq -r '.host') + hostname=$(echo "$entry" | jq -r '.hostname') + identity_key=$(echo "$entry" | jq -r '.identity_key') + exit_gateway_address=$(echo "$entry" | jq -r '.exitGateway // empty') + valid_ip=$(echo "$host") + + if [ -n "$exit_gateway_address" ]; then + exit_gateway="{\"address\": \"${exit_gateway_address}\"}" + else + exit_gateway="{}" + fi + if [[ $valid_ip =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + country_info=$(curl -s "http://ipinfo.io/${valid_ip}/country" | tr -d '\n') + country_info_escaped=$(echo "$country_info" | tr -d '\n' | jq -aRs . | tr -d '"') + else + country_info_escaped="" + fi + json_object="{\"hostname\": \"${hostname}\", \"identityKey\": \"${identity_key}\", \"exitGateway\": ${exit_gateway}, \"location\": \"${country_info_escaped}\"}" + json_array+=("$json_object") +done < <(echo "$data") + +if [ $? -ne 0 ]; then + echo "error fetching data from endpoint" + exit 1 +fi + +download_file() { + local file_url=$1 + local output_file=$2 + local time_file=$3 + + echo "starting download speed test..." + local start_time=$(date +%s) + if [[ "$OSTYPE" == "linux-gnu"* ]]; then + wget -O $output_file $file_url + elif [[ "$OSTYPE" == "darwin"* ]]; then + curl -o $output_file $file_url + fi + local end_time=$(date +%s) + local elapsed_time=$((end_time - start_time)) + echo "download speed test completed in $elapsed_time seconds." >"$time_file" +} + +if ! command -v jq &>/dev/null; then + echo "jq is not installed. Please install jq to proceed." + exit 1 +fi + +temp_log_file="temp_log.txt" + +perform_tests() { + local gateway_id=$1 + local exit_address=$2 + local test_directory="tests_${gateway_id}_${exit_address}" + local file_url="http://ipv4.download.thinkbroadband.com/2MB.zip" + + mkdir -p "$test_directory" + local ping_results_file="${test_directory}/ping_results.txt" + local download_time_file="${test_directory}/download_time.txt" + local api_response_file="${test_directory}/api_response_times.txt" + + # ping test + echo "starting ping test..." + for site in google.com youtube.com facebook.com baidu.com wikipedia.org amazon.com twitter.com instagram.com yahoo.com ebay.com netflix.com; do + ping -c 4 $site >>"$ping_results_file" + done + echo "ping test completed. Results saved in $ping_results_file" + + # download speed test + download_file $file_url /dev/null "$download_time_file" + + # api test + local api_endpoint="https://validator.nymtech.net/api/v1/mixnodes" + local iterations=10 + >"$api_response_file" + for i in $(seq 1 $iterations); do + local start_time=$(date +%s) + local response=$(curl -s -o /dev/null -w '%{http_code}' $api_endpoint) + local end_time=$(date +%s) + + local elapsed_seconds=$((end_time - start_time)) + local hours=$((elapsed_seconds / 3600)) + local minutes=$(((elapsed_seconds % 3600) / 60)) + local seconds=$((elapsed_seconds % 60)) + + local human_readable_time=$(printf "%02dh:%02dm:%02ds" $hours $minutes $seconds) + echo "iteration $i: response Time = ${human_readable_time}, status code = $response" >>"$api_response_file" + done + echo "api response test completed. Results saved in $api_response_file." +} + +printf "%s\n" "${json_array[@]}" | jq -s . + +read -p "enter a gateway ID: " identity_key +read -p "enter an exit address: " exit_address + +while true; do + read -p "enable WireGuard? (yes/no): " enable_wireguard + enable_wireguard=$(echo "$enable_wireguard" | tr '[:upper:]' '[:lower:]') + + case "$enable_wireguard" in + "yes") + read -p "enter your WireGuard private key: " priv_key + read -p "enter your WireGuard IP: " wg_ip + wireguard_options="--enable-wireguard --private-key $priv_key --wg-ip $wg_ip" + break + ;; + "no") + wireguard_options="" + break + ;; + *) + echo "invalid response. please enter 'yes' or 'no'." + ;; + esac +done + +sudo ./nym-vpn-cli -c sandbox.env --entry-gateway-id ${identity_key} --exit-router-address ${exit_address} --enable-two-hop $wireguard_options >"$temp_log_file" 2>&1 & + +timeout=15 +start_time=$(date +%s) +while true; do + current_time=$(date +%s) + if grep -q "received plain" "$temp_log_file"; then + echo "successful configuration with identity_key: $identity_key and exit address: $exit_address" >>perf_test_results.log + perform_tests "$identity_key" "$exit_address" + break + fi + if ((current_time - start_time > timeout)); then + echo "failed to connect with identity_key: $identity_key using the exit address: $exit_address" >>perf_test_results.log + break + fi + sleep 1 +done + +echo "terminating nym-vpn-cli..." +pkill -f './nym-vpn-cli' +sleep 5 +rm -f "$temp_log_file" + +``` diff --git a/documentation/dev-portal/src/events/cryptotalk/nym-vpn-troubleshooting.md b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-troubleshooting.md new file mode 100644 index 0000000000..d6a72a0599 --- /dev/null +++ b/documentation/dev-portal/src/events/cryptotalk/nym-vpn-troubleshooting.md @@ -0,0 +1,100 @@ +# Troubleshooting + +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 event. + +#### Problems with the newest version `nym-vpn-alpha-0.0.2 demo` + +Try the previous version `nym-vpn-alpha-0.0.1 demo` which was tested multiple times by downloading the client from this [release page(https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.1) and doing all the steps with the name of your downloaded binary. + +#### Installing GUI on MacOS not working + +In case there was a problem running the script, try a manual configuration: + +* Visit the [releases page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.1) to download the binary for Debian based Linux +* Open terminal in the same directory and check the the `sha256sum` by running: +```sh +# for MacOS GUI +sha256sum ./nym-vpn-ui-macos-latest.zip +``` +* Compare the result with the sha256 hash shared on the [release page](https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.1) +* Extract files with `unzip` command or manually as you are used toi +* Create a NymVPN config directory called `nym-vpn` in your `~/.config`, either manually or by a command: +```sh +mkdir $HOME/Library/Application Support/nym-vpn/ +``` +* Create the network config by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the config directory `nym-vpn` you just created +* Create the main config file called `config.toml` in the same directory with this content: +```toml +env_config_file = "$HOME/Library/Application Support/nym-vpn/" +entry_node_location = "DE" # two letters country code +``` + +**Note:** Some users had a problem to access their home config folder on macOS, in that case save the configuration files in the same directory where you downloaded your `nym-vpn` binary as following: + +* Create the network config by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `.env` (yes just like that) in the same directory like `nym-vpn` binaries. +* Create the main config file called `config.toml` in the very same directory with this content: +```toml +env_config_file = "$HOME/Library/Application Support/nym-vpn/" +entry_node_location = "DE" # two letters country code +``` + +#### Thread `main` panicked + +If you see a message like: +```sh +thread 'main' panicked at /Users/runner/.cargo/git/checkouts/mullvadvpn-app-a575cf705b5dfd76/ccfbaa2/talpid-routing/src/unix.rs:301:30: +``` +Restart your wifi connection and start again. + +#### macOS alert on NymVPN UI startup + +If you are running NymVPN on mac OS for the first time, you may see this alert message: + +![](images/image3.png) + +1. Head to System Settings -> Privacy & Security and click `Allow anyway` + +![](images/image5.png) + +2. Confirm with your password or TouchID + +3. Possibly you may have to confirm again upon running the application + +#### Missing `jq` error + +In case of missing `jq` on Linux (Debian) install it with: +```sh +# Linux (Debian) +sudo apt-get install jq +# macOS +brew install jq +``` +On some Linux distributions however the [script](./nym-vpn.md#testssh) returns `jq` error even if your system claims that `jq is already the newest version`. +In that case, comment the `jq` check in the script as follows: +```sh +#if ! command -v jq &>/dev/null; then +# echo "jq is not installed. Please install jq to proceed." +# exit 1 +#fi +``` + +#### Error current_time: not found + +When running `sudo sh ./test.sh` you may see an error like: `93: current_time: not found`. This has something to do with the `current_time` setup of your system and on itself shall not have a negative impact on the test. It has nothing to do with the client at all as it only relates to the code in our testing script. + +#### Not connecting to the endpoint + +In case the automatic download of all the Gateways fail (and it shouldn't), you do an easy manual work around: + +1. Open the list of Gateways created by API [here](https://nymvpn.com/en/ccc/api/gateways) +2. On top click on `JSON` option (shall be default view) and `Save` +3. Save it as `data.json` to the `nym-vpn-tests` folder +4. Replace line 3 in the [script `tests.sh`](./nym-vpn.md#testssh) with: +```sh +NEW_ENDPOINT="http://localhost:8000/data.json" +``` +5. In a new terminal window run: +```sh +python3 -m http.server 8000 +``` +6. Continue with the steps listed in [testing section](./nym-vpn.md#testing) diff --git a/documentation/dev-portal/src/events/cryptotalk/nym-vpn.md b/documentation/dev-portal/src/events/cryptotalk/nym-vpn.md new file mode 100644 index 0000000000..07e57a458c --- /dev/null +++ b/documentation/dev-portal/src/events/cryptotalk/nym-vpn.md @@ -0,0 +1,51 @@ +# NymVPN alpha + +
+ +We are honored to present NymVPN, a client that uses [Nym Mixnet](https://nymtech.net) to anonymise all of a user's internet traffic through either a 5-hop mixnet (for a full network privacy) or the faster 2-hop decentralised VPN (with some extra features). At this event we have the unique opportunity to be part of the initial alpha testing. The following pages provide a how-to guide, explaining steps to install and run NymVPN CLI and GUI on our testing environment Nym Sandbox. + +## NymVPN + +The following overview provides an easy introduction to the NymVPN alpha client. We recommend interested developers to begin with [Nym network overview](https://nymtech.net/docs/architecture/network-overview.html) and the [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) pages. + +The default is to run in 5-hop mode: + +``` + ┌─►mix──┐ mix mix + │ │ + Entry │ │ Exit +client ───► Gateway ──┘ mix │ mix ┌─►mix ───► Gateway ───► internet + │ │ + │ │ + mix └─►mix──┘ mix +``` + +Users can switch to 2-hop only mode, which is a faster but less private option. In this mode traffic is only sent between the two Gateways, and is not passed between Mix Nodes. + +The client can optionally do the first hop (local client to Entry Gateway) using Wireguard. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device. + +## NymVPN Guide & FAQ pages + +To download, install and test NymVPN alpha, visit pages listed below: + +* [GNU/Linux](nym-vpn-linux.md) +* [Mac OS](nym-vpn-mac.md) +* [Testing scripts](nym-vpn-testing.md) +* [Troubleshooting](nym-vpn-troubleshooting.md) +* [NymVPN FAQ](nym-vpn-faq.md) + +## Goals of testing + +This alpha testing will help: + +* Stabilise NymVPN client +* Understand NymVPN client behavior in various setups (OS, connectivity, etc.) +* Stabilize the VPN infrastructure and improve its reliability / speed / features (e.g. IPv6 support) +* Load test the network in Sandbox environment and identify / anticipate potential weaknesses + + +```admonish info +Our alpha testing round is done live with some participants at the event. This guide will not work for everyone, as the NymVPN binaries aren't publicly accessible yet. Note that this setup of Nym testnet Sandbox environment is limited event and some of the configurations will not work in the future. + +**If you commit to test NymVPN alpha, please start with the [user research form](https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2) where all the steps will be provided**. +```