From ebc8a216f13205ad32dbe7b24697b0d31271d5b9 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 16 Oct 2024 19:18:56 +0200 Subject: [PATCH] brought in archive + done rewrites for devportal --- documentation/docs/next.config.js | 191 +++++++++++++- .../docs/pages/developers/_meta.json | 4 +- .../pages/developers/archive/nym-connect.md | 85 +++++++ .../docs/pages/developers/archive/nymvpn.md | 38 +++ .../developers/archive/nymvpn/cli-linux.md | 142 +++++++++++ .../developers/archive/nymvpn/cli-mac.md | 123 +++++++++ .../pages/developers/archive/nymvpn/cli.md | 240 ++++++++++++++++++ .../pages/developers/archive/nymvpn/faq.md | 71 ++++++ .../developers/archive/nymvpn/gui-linux.md | 85 +++++++ .../developers/archive/nymvpn/gui-mac.md | 65 +++++ .../pages/developers/archive/nymvpn/gui.md | 50 ++++ .../developers/archive/nymvpn/testing.md | 209 +++++++++++++++ .../archive/nymvpn/troubleshooting.md | 97 +++++++ documentation/docs/pages/developers/coc.md | 17 ++ 14 files changed, 1415 insertions(+), 2 deletions(-) create mode 100644 documentation/docs/pages/developers/archive/nym-connect.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/cli-linux.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/cli-mac.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/cli.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/faq.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/gui-linux.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/gui-mac.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/gui.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/testing.md create mode 100644 documentation/docs/pages/developers/archive/nymvpn/troubleshooting.md create mode 100644 documentation/docs/pages/developers/coc.md diff --git a/documentation/docs/next.config.js b/documentation/docs/next.config.js index 05414bb49c..d8bc424674 100644 --- a/documentation/docs/next.config.js +++ b/documentation/docs/next.config.js @@ -159,7 +159,196 @@ const config = { permanent: true, }, // dev docs - // operators docs TODO + { + source: "/developers/clients-overview.html", + destination: "/developers/clients", + permanent: true, + }, + { + source: "/developers/sdk/rust/rust.html", + destination: "/developers/rust", + permanent: true, + }, + { + source: "/developers/sdk/rust/message-types.html", + destination: "/developers/rust/mixnet/message-types", + permanent: true, + }, + { + source: "/developers/sdk/rust/message-helpers.html", + destination: "/developers/rust/mixnet/message-helpers", + permanent: true, + }, + { + source: "/developers/sdk/rust/troubleshooting.html", + destination: "/developers/rust/mixnet/troubleshooting", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples.html", + destination: "/developers/rust/mixnet/examples", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/simple.html", + destination: "/developers/rust/mixnet/examples/simple", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/keys.html", + destination: "/developers/sdk/rust/examples/keys.html", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/storage.html", + destination: + "/developers/rust/mixnet/examples/builders/builder-with-storage", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/surbs.html", + destination: "/developers/rust/mixnet/examples/surbs", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/custom-network.html", + destination: "/developers/rust/mixnet/examples/custom-topology", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/socks.html", + destination: "/developers/rust/mixnet/examples/socks", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/split-send.html", + destination: "/developers/rust/mixnet/examples/split-send", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/credential.html", + destination: "/developers/rust/mixnet", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/cargo.html", + destination: "/developers/rust/importing", + permanent: true, + }, + { + source: "/developers/sdk/typescript.html", + destination: "/developers/typescript", + permanent: true, + }, + { + source: "/developers/binaries/pre-built-binaries.html", + destination: "/developers/binaries#pre-built-binaries", + permanent: true, + }, + { + source: "/developers/binaries/building-nym.html", + destination: "/developers/binaries", + permanent: true, + }, + { + source: "/developers/clients/websocket-client.html", + destination: "/developers/clients/websocket", + permanent: true, + }, + { + source: "/developers/clients/websocket/setup.html", + destination: "/developers/clients/websocket/setup", + permanent: true, + }, + { + source: "/developers/clients/websocket/config.html", + destination: "/developers/clients/websocket/config", + permanent: true, + }, + { + source: "/developers/clients/websocket/usage.html", + destination: "/developers/clients/websocket/usage", + permanent: true, + }, + { + source: "/developers/clients/websocket/examples.html", + destination: "/developers/clients/websocket/examples", + permanent: true, + }, + { + source: "/developers/clients/socks5-client.html", + destination: "/developers/clients/socks5", + permanent: true, + }, + { + source: "/developers/clients/socks5/setup.html", + destination: "/developers/clients/socks5#client-setup", + permanent: true, + }, + { + source: "/developers/clients/socks5/usage.html", + destination: "/developers/clients/socks5#using-your-socks5-client", + permanent: true, + }, + { + source: "/developers/clients/webassembly-client.html", + destination: "/developers/clients/webassembly-client", + permanent: true, + }, + { + source: "/developers/tutorials/coming-soon.html", + destination: "/developers/rust#", + permanent: true, + }, + { + source: "/developers/integrations/integration-options.html", + destination: "/developers/integrations", + permanent: true, + }, + { + source: "/developers/faq/integrations-faq.html", + destination: "/developers/integrations", + permanent: true, + }, + { + source: "/developers/coc.html", + destination: "/developers/coc", + permanent: true, + }, + { + source: "/developers/licensing.html", + destination: "/developers/licensing", + permanent: true, + }, + { + source: "/developers/nymvpn/intro.html", + destination: "/developers/archive/nymvpn", + permanent: true, + }, + { + source: "/developers/nymvpn/cli.html", + destination: "/developers/nymvpn/cli", + permanent: true, + }, + { + source: "/developers/archive/nym-connect.html", + destination: "/developers/archive/nym-connect", + permanent: true, + }, + // { + // source: "", + // destination: "", + // permanent: true, + // }, + /* + TODO + /developers/examples/custom-services.html + /developers/examples/using-nrs.html + /developers/examples/browser-only.html + /developers/examples/monorepo-examples.html + /developers/integrations/payment-integration.html + OPERATORS + */ ]; }, images: { diff --git a/documentation/docs/pages/developers/_meta.json b/documentation/docs/pages/developers/_meta.json index a592f7f587..d0103c08a5 100644 --- a/documentation/docs/pages/developers/_meta.json +++ b/documentation/docs/pages/developers/_meta.json @@ -14,5 +14,7 @@ "---": { "type": "separator" }, - "licensing": "Licensing" + "archive": "Archive", + "licensing": "Licensing", + "coc": "Coc" } diff --git a/documentation/docs/pages/developers/archive/nym-connect.md b/documentation/docs/pages/developers/archive/nym-connect.md new file mode 100644 index 0000000000..2dca063dd8 --- /dev/null +++ b/documentation/docs/pages/developers/archive/nym-connect.md @@ -0,0 +1,85 @@ +# Archive page: NymConnect Setup + +```admonish warning +Since the beginning of 2024 NymConnect is no longer maintained. Nym is developing a new client called [NymVPN](https://nymvpn.com), an application routing all users traffic thorugh the mixnet. +If users want to route their traffic through socks5 we advice to use maintained [Nym Socks5 Client](../clients/socks5/setup.md). +``` + +In case you want to run deprecated NymConnect, follow these steps: + +1. Navigate to our [Github repository](https://github.com/nymtech/nym/releases?q=nym-connect&expanded=true) and download NymConnect binary +2. On Linux and Mac, make executable by opening terminal in the same directory and run: + +```sh +chmod +x ./nym-connect_.AppImage +``` + +1. Start the application +2. Click on `Connect` button to initialise the connection with the Mixnet +3. Anytime you'll need to setup Host and Port in your applications, click on `IP` and `Port` to copy the values to clipboard +4. In case you have problems such as `Gateway Issues`, try to reconnect or restart the application + +## Connect Privacy Enhanced Applications (PEApps) + +Here are some examples of applications which will work behind Socks5 proxy (`nym-socks5-client` or deprecated NymConnect), to enhance users privacy. + +### Electrum Bitcoin wallet via NymConnect + +To download Electrum visit the [official webpage](https://electrum.org/#download). To connect to the Mixnet follow these steps: + +1. Start and connect NymConnect (or [`nym-socks5-client`](../clients/socks5/setup.md)) +2. Start your Electrum Bitcoin wallet +3. Go to: *Tools* -> *Network* -> *Proxy* +4. Set *Use proxy* to ✅, choose `SOCKS5` from the drop-down and add (copy-paste) the values from your NymConnect application +5. Now your Electrum Bitcoin wallet runs through the Mixnet and it will be connected only if your NymConnect or `nym-socks5-client` are connected. + +![Electrum Bitcoin wallet setup](../images/electrum_tutorial/electrum.gif) + +### Monero wallet via NymConnect + +To download Monero wallet visit [getmonero.org](https://www.getmonero.org/downloads/). To connect to the Mixnet follow these steps: + +1. Start and connect NymConnect (or [`nym-socks5-client`](../clients/socks5/setup.md)) +2. Start your Monero wallet +3. Go to: *Settings* -> *Interface* -> *Socks5 proxy* -> Add values: IP address `127.0.0.1`, Port `1080` (the values copied from NymConnect) +5. Now your Monero wallet runs through the Mixnet and it will be connected only if your NymConnect or `nym-socks5-client` are connected. + +![Monero wallet setup](../images/monero_tutorial/monero-gui-NC.gif) + +### Matrix (Element) via NymConnect + +To download Element (chat client for Matrix) visit [element.io](https://element.io/download). To connect to the Mixnet follow these steps: + +1. Start and connect NymConnect (or [`nym-socks5-client`](../clients/socks5/setup.md)) +2. Start `element-desktop` with `--proxy-server` argument: + +**Linux** + +```sh +element-desktop --proxy-server=socks5://127.0.0.1:1080 +``` + +**Mac** + +```sh +open -a Element --args --proxy-server=socks5://127.0.0.1:1080 +``` + +To make the start of Element over NymConnect simplier, you can add this command to your key-binding shortcuts in your system settings. + +### Telegram via NymConnect + +1. Start and connect NymConnect (or [`nym-socks5-client`](../clients/socks5/setup.md)) +2. Start your Telegram chat application +3. Open the Telegram proxy settings. + - Linux: *Settings* -> *Advanced* -> *Connection type* -> *Use custom proxy* + - MacOS: *Settings* -> *Advanced* -> *Data & Storage* -> *Connection Type* -> *Use custom Proxy* + - Windows: *Settings* -> *Data and Storage* -> *Use proxy* +4. Add a proxy with the *Add proxy button*. +5. Select *SOCKS5* and make sure the port details are the same as those generated by NymConnect. Alternatively, follow this link: [https://t.me/socks?server=127.0.0.1&port=1080](https://t.me/socks?server=127.0.0.1&port=1080) +6. *Save the proxy settings* in Telegram. +7. Telegram is now running through the Nym Mixnet and is privacy-enhanced! This allows you to connect from regions which blocked Telegram. +8. Note if you remain idle on Telegram for a while you might lose connectivity and your messages might not get through via SOCKS5 proxy. If that happens reconnect your NymConnect and reset the proxy again. + + +Follow this [video](https://youtu.be/quj8H2qeOwY?t=97) to see the steps on Telegram setup. diff --git a/documentation/docs/pages/developers/archive/nymvpn.md b/documentation/docs/pages/developers/archive/nymvpn.md new file mode 100644 index 0000000000..02150ffe5a --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn.md @@ -0,0 +1,38 @@ +# NymVPN alpha + +
+ +```admonish tip title="web3summit testing" +**If you testing NymVPN CLI on Web3 Summit Berlin, visit our event page with all info tailored for the event: [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net/).** +``` + +**NymVPN alpha** is 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). + + +**You are invited to take part in the alpha testing** of this new application. Register for private testing round at [nymvpn.com](https://nymvpn.com/en), that will grant you access to the [download page](https://nymvpn.com/download). Visit [NymVPN Support & FAQ](https://nymvpn.com/en/support) or join the [NymVPN matrix channel](https://matrix.to/#/#NymVPN:nymtech.chat) if you have any questions, comments or blockers. + +Checkout the [release page](https://github.com/nymtech/nym-vpn-client/releases) for available binaries. + +*NOTE: NymVPN alpha is experimental software for testing purposes only.* + + +## NymVPN Overview + +To understand what's under the hood of NymVPN and the mixnet, 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 setup of NymVPN is to run in 5-hop mode (mixnet): + +``` + ┌─►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. It uses Mixnet Sphinx packets with shorter, fixed routes, which improve latency, but doesn't offer the same level of protection as the 5 hop mode. + diff --git a/documentation/docs/pages/developers/archive/nymvpn/cli-linux.md b/documentation/docs/pages/developers/archive/nymvpn/cli-linux.md new file mode 100644 index 0000000000..5d742a5d43 --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/cli-linux.md @@ -0,0 +1,142 @@ +# NymVPN alpha CLI Guide + +```admonish info +NymVPN is an experimental software and it's for testing 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. +``` + +## Installation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +1. Open Github [releases page]({{nym_vpn_releases}}) and download the CLI latest binary for your system + +2. Verify sha hash of your downloaded binary with the one listed on the [releases page]({{nym_vpn_releases}}). You can use a simple `shasum` command and compare strings (ie with Python) or run in the same directory the following command, exchanging `` with the one of your binary, like in the example: +```sh +echo "" | shasum -a 256 -c + +# choose a correct one according to your binary, this is just an example +# echo "0e4abb461e86b2c168577e0294112a3bacd3a24bf8565b49783bfebd9b530e23 nym-vpn-cli__ubuntu-22.04_amd64.tar.gz" | shasum -a 256 -c +``` + +3. Extract files: +```sh +tar -xvf .tar.gz +# for example +# tar -xvf nym-vpn-cli__ubuntu-22.04_x86_64.tar.gz +``` + +4. Make executable: +```sh +# make sure you are in the right sub-directory +chmod u+x ./nym-vpn-cli +``` + +## 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 --exit-router-address --enable-wireguard --private-key --wg-ip +``` +3. To choose different Gateways, visit [explorer.nymtech.net/network-components/gateways](https://explorer.nymtech.net/network-components/gateways) and copy-paste an identity key of your choice +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 <--exit-router-address |--exit-gateway-id |--exit-gateway-country > +``` +* To choose different Gateways, visit [nymvpn.com/en/alpha/api/gateways](https://explorer.nymtech.net/network-components/gateways) +* To see all possibilities run with `--help` flag: +```sh +./nym-vpn-cli --help +``` +~~~admonish example collapsible=true title="Console output" +```sh +Usage: nym-vpn-cli [OPTIONS] <--exit-router-address |--exit-gateway-id |--exit-gateway-country > + +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 + --entry-gateway-low-latency + Auto-select entry gateway by latency + --exit-router-address + Mixnet recipient address + --exit-gateway-id + + --exit-gateway-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 used for the first hop to the entry gateway + --nym-ipv4 + The IPv4 address of the nym TUN device that wraps IP packets in sphinx packets + --nym-ipv6 + The IPv6 address of the nym TUN device that wraps IP packets in sphinx packets + --nym-mtu + The MTU of the nym TUN device that wraps IP packets in sphinx packets + --disable-routing + Disable routing all traffic through the nym TUN device. When the flag is set, the nym TUN device will be created, but to route traffic through it you will need to do it manually, e.g. ping -Itun0 + --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 + --disable-background-cover-traffic + Disable constant rate background loop cover traffic + -h, --help + Print help + -V, --version + Print version +``` +~~~ + +Here is a list of the options and their descriptions. Some are essential, some are more technical and not needed to be adjusted by users. + +**Fundamental commands and arguments** + +- `-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. + +## Testnet environment + +If you want to run NymVPN CLI in Nym Sandbox environment, there are a few adjustments to be done: + +1. 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 +``` + +1. Check available Gateways at [nymvpn.com/en/alpha/api/gateways](https://nymvpn.com/en/alpha/api/gateways) + +2. Run with a flag `-c` +```sh +sudo ./nym-vpn-cli -c /sandbox.env <--exit-router-address |--exit-gateway-id |--exit-gateway-country > +``` diff --git a/documentation/docs/pages/developers/archive/nymvpn/cli-mac.md b/documentation/docs/pages/developers/archive/nymvpn/cli-mac.md new file mode 100644 index 0000000000..9ae4039cdc --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/cli-mac.md @@ -0,0 +1,123 @@ +# NymVPN alpha CLI: Guide for MacOS + +```admonish info +NymVPN is an experimental software and it's for testing 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. +``` + +## Preparation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +1. Open Github [releases page]({{nym_vpn_releases}}) and download the binary for MacOS +2. Verify sha hash of your downloaded binary with the one listed on the [releases page]({{nym_vpn_releases}}). You can use a simple `shasum` command and compare strings (ie with Python) or run in the same directory the following command, exchanging `` with the one of your binary, like in the example: +```sh +echo "" | shasum -a 256 -c + +# choose a correct one according to your binary, this is just an example +# echo "96623ccc69bc4cc0e4e3e18528b6dae6be69f645d0a592d926a3158ce2d0c269 nym-vpn-cli__macos_x86_64.zip" | shasum -a 256 -c +``` +3. Extract files: +```sh +tar -xvf +# for example +# tar -xvf nym-vpn-cli__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 +``` +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 +``` + +## 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 --exit-router-address --enable-wireguard --private-key --wg-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 --exit-router-address --enable-wireguard --private-key --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 +``` +~~~admonish example collapsible=true title="Console output" +```sh +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 used for the first hop to the entry gateway + --nym-ip + The IP address of the nym TUN device that wraps IP packets in sphinx packets + --nym-mtu + The MTU of the nym TUN device that wraps IP packets in sphinx packets + --disable-routing + Disable routing all traffic through the nym TUN device. When the flag is set, the nym TUN device will be created, but to route traffic through it you will need to do it manually, e.g. ping -Itun0 + --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 + --disable-background-cover-traffic + Disable constant rate background loop cover traffic + -h, --help + Print help + -V, --version + Print version +``` +~~~ + +Here is a list of the options and their descriptions. Some are essential, some are more technical and not needed to be adjusted by users. + +**Fundamental commands and arguments** + +- `-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/docs/pages/developers/archive/nymvpn/cli.md b/documentation/docs/pages/developers/archive/nymvpn/cli.md new file mode 100644 index 0000000000..ae74274cf3 --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/cli.md @@ -0,0 +1,240 @@ +# NymVPN CLI Guide + +```admonish tip title="web3summit testing" +**If you testing NymVPN CLI on Web3 Summit Berlin, visit our event page with all info tailored for the event: [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net/).** +``` + +```admonish info +To download NymVPN desktop version, visit [nymvpn.com/en/download](https://nymvpn.com/en/download). + +NymVPN is an experimental software and it's for testing purposes only. Anyone can submit a registration to the private alpha round on [nymvpn.com](https://nymvpn.com/en). +``` + +## Overview + +The core binaries consist of: + +- **`nym-vpn-cli`**: Basic commandline client for running the vpn. This runs in the foreground. + +- **`nym-vpnd`**: Daemon implementation of the vpn client that can run in the background and interacted with using `nym-vpnc`. + +- **`nym-vpnc`**: The commandline client used to interact with `nym-vpnd`. + + +## Installation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +1. Open Github [releases page]({{nym_vpn_releases}}) and download the CLI latest binary for your system (labelled as `nym-vpn-core`) + +2. Verify sha hash of your downloaded binary with the one listed on the [releases page]({{nym_vpn_releases}}). You can use a simple `shasum` command and compare strings (ie with Python) or run in the same directory the following command, exchanging `` with the one of your binary, like in the example: +```sh +echo "" | shasum -a 256 -c + +# choose a correct one according to your binary, this is just an example +# echo "0e4abb461e86b2c168577e0294112a3bacd3a24bf8565b49783bfebd9b530e23 nym-vpn-cli__ubuntu-22.04_amd64.tar.gz" | shasum -a 256 -c +``` + +3. Extract files: +```sh +tar -xvf .tar.gz +# for example +# tar -xvf nym-vpn-cli__ubuntu-22.04_x86_64.tar.gz +``` + +### Building From Source + +NymVPN CLI can be built from source. This process is recommended for more advanced users as the installation may require different dependencies based on the operating system used. + +Start by installing [Go](https://go.dev/doc/install) and [Rust](https://rustup.rs/) languages on your system and then follow these steps: + +1. Clone NymVPN repository: +```sh +git clone https://github.com/nymtech/nym-vpn-client.git +``` + +2. Move to `nym-vpn-client` directory and compile `wireguard`: + +```sh +cd nym-vpn-client + +make build-wireguard +``` + +3. Compile NymVPN CLI +```sh +make build-nym-vpn-core +``` + +Now your NymVPN CLI is installed. Navigate to `nym-vpn-core/target/release` and use the commands the section below to run the client. + +## Running + +If you are running Debian/Ubuntu/PopOS or any other distributio supporting debian packages and systemd, see the [relevant section below](#debian-package-for-debianubuntupopos). + +### Daemon + +Start the daemon with + +```sh +sudo -E ./nym-vpnd +``` + +Then run + +```sh +./nym-vpnc status +./nym-vpnc connect +./nym-vpnc disconnect +``` + +### CLI + +An alternative to the daemon is to run the `nym-vpn-cli` commandline client that runs in the foreground. +```sh +./nym-vpn-cli run +``` + +## Credentials + +NymVPN uses [zkNym bandwidth credentials](https://nymtech.net/docs/bandwidth-credentials.html). Those can be imported as a file or base58 encoded string. + + +```sh +sudo -E ./nym-vpn-cli import-credential --credential-path +sudo -E ./nym-vpn-cli import-credential --credential-data "" +``` + +## Debian package for Debian/Ubuntu/PopOS + +For linux platforms using deb packages and systemd, there are also debian packages. + +```sh +sudo apt install ./nym-vpnd_-1_amd64.deb ./nym-vpnc_-1_amd64.deb + +# In case of error please substitute the correct version +``` + +Installing the `nym-vpnd` deb package starts a `nym-vpnd.service`. Check that the daemon is running with +```sh +systemctl status nym-vpnd.service +``` +and check its logs with +```sh +sudo journalctl -u nym-vpnd.service -f +``` +To stop the background service +```sh +systemctl stop nym-vpnd.service +``` +It will start again on startup, so disable with +```sh +systemctl disable nym-vpnd.service +``` + +Interact with it with `nym-vpnc` +```sh +nym-vpnc status +nym-vpnc connect +nym-vpnc disconnect +``` + +## Commands & Options + +```admonish note +Nym Exit Gateway functionality was implemented just recently and not all the Gateways are upgraded and ready to handle the VPN connections. If you want to make sure you are connecting to a Gateway with an embedded Network Requester, IP Packet Router and applied Nym exit policy, visit [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/) and search Gateways with all the functionalities enabled. +``` + +The basic syntax of `nym-vpn-cli` is: +```sh +# choose only one conditional --argument listed in {brackets} +sudo ./nym-vpn-cli { --exit-router-address |--exit-gateway-id |--exit-gateway-country } +``` + +To see all the possibilities run with `--help` flag: +```sh +./nym-vpn-cli --help +``` + +~~~admonish example collapsible=true title="nym-vpn-cli --help" +```sh +Usage: nym-vpn-cli [OPTIONS] + +Commands: + run Run the client + import-credential Import credential + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file Path pointing to an env file describing the network + --data-path Path to the data directory of the mixnet client + -h, --help Print help + -V, --version Print version +``` +~~~ + +You can also run any command with `--help` flag to see a list of all options associated witht that command, the most important may be `run` command, like in this example. + +~~~admonish example collapsible=true title="nym-vpn-cli run --help" +```sh +Run the client + +Usage: nym-vpn-cli run [OPTIONS] + +Options: + --entry-gateway-id + Mixnet public ID of the entry gateway + --entry-gateway-country + Auto-select entry gateway by country ISO + --entry-gateway-low-latency + Auto-select entry gateway by latency + --exit-router-address + Mixnet recipient address + --exit-gateway-id + Mixnet public ID of the exit gateway + --exit-gateway-country + Auto-select exit gateway by country ISO + --wireguard-mode + Enable the wireguard mode + --nym-ipv4 + The IPv4 address of the nym TUN device that wraps IP packets in sphinx packets + --nym-ipv6 + The IPv6 address of the nym TUN device that wraps IP packets in sphinx packets + --nym-mtu + The MTU of the nym TUN device that wraps IP packets in sphinx packets + --dns + The DNS server to use + --disable-routing + Disable routing all traffic through the nym TUN device. When the flag is set, the nym TUN device will be created, but to route traffic through it you will need to do it manually, e.g. ping -Itun0 + --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 + --disable-background-cover-traffic + Disable constant rate background loop cover traffic + --enable-credentials-mode + Enable credentials mode + --min-mixnode-performance + Set the minimum performance level for mixnodes + -h, --help + Print help + +``` +~~~ + + +## Testnet environment + +If you want to run NymVPN CLI in Nym Sandbox environment, there are a few adjustments to be done: + +1. 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: +```sh +curl -o sandbox.env -L https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env +``` + +2. Check available Gateways at [Sandbox API](https://sandbox-nym-api1.nymtech.net/api/v1/gateways) or [Sandbox Swagger page](https://sandbox-nym-api1.nymtech.net/api/swagger/index.html) + +3. Run with a flag `-c` +```sh +sudo ./nym-vpn-cli -c /sandbox.env <--exit-router-address |--exit-gateway-id |--exit-gateway-country > +``` diff --git a/documentation/docs/pages/developers/archive/nymvpn/faq.md b/documentation/docs/pages/developers/archive/nymvpn/faq.md new file mode 100644 index 0000000000..d05df2d051 --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/faq.md @@ -0,0 +1,71 @@ +# Frequently Asked Questions + +**NymVPN [*Support & FAQ page*](https://nymvpn.com/en/support)** contains all essential FAQs regarding the client. This page (below) is a source of additional information often seeked by users, operators and developers testing NymVPN. + +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 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](intro.md#nymvpn-guides) the client. + +Below are some extra FAQs which came out during the previous alpha testing rounds. + +### 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 -> through 3 layers of Mix Nodes -> to Exit Gateway -> internet. this option uses all the Nym Mixnet features for maximum privacy. + +``` + ┌─►mix──┐ mix mix + │ │ + Entry │ │ Exit +client ───► Gateway ──┘ mix │ mix ┌─►mix ───► Gateway ───► internet + │ │ + │ │ + 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 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 +client ───► Gateway ────► Gateway ───► internet +``` + +We highly recommend to read more about [Nym network overview](https://nymtech.net/docs/architecture/network-overview.html) and the [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html). + +### Why do I see different sizes of packets in my terminal log? + +One of features of Nym Mixnet's clients is to break data into the same size packets called Sphinx, which is currently ~2kb. When running NymVPN, the data log shows payload sizes, which are the raw sizes of the IP packets, not Sphinx. The payload sizes will be capped by the configured MTU, which is set around 1500 bytes. + +### What is 'poisson filter' about? + +By default `--enable-poisson` is disabled and packets are sent from the local client to the Entry Gateway as quickly as possible. With the poisson process enabled the Nym 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. + +Enabling the poisson filter is one of the key mechanisms to de-correlate input and output traffic to the Mixnet. The performance impact however is dramatic: +1 packer per 20ms is 50 packets / sec so ballpark 100kb/s. +For mobile clients that means constantly sending data eating up data allowance. + + +## Nym Mixnet Architecture and Rewards + +We have a list of questions related to Nym Nodes and the incentives behind running them under [FAQ pages](https://nymtech.net/operators/faq/mixnodes-faq.html) in our [Operators Guide](https://nymtech.net/operators). For better knowledge about Nym architecture we recommend to read [Nym network overview](https://nymtech.net/docs/architecture/network-overview.html) and the [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) in our [technical documentation](https://nymtech.net/docs). + +## 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. + +## Exit Gateway + +Part of the the transition under code name [Project Smoosh](#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 with any experiences you may have running Tor Exit relays or legal findings and suggestions for Nym Exit Gateway operators + +## Nym Integrations and SDKs + +If you are a dev who is interested to integrate Nym, have a look on our SDK tutorials: + +* [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/docs/pages/developers/archive/nymvpn/gui-linux.md b/documentation/docs/pages/developers/archive/nymvpn/gui-linux.md new file mode 100644 index 0000000000..e77945d9eb --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/gui-linux.md @@ -0,0 +1,85 @@ +# NymVPN alpha - Desktop: Guide for GNU/Linux + +
+ +```admonish info +NymVPN is an experimental software and it's for testing 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. +``` + +## Preparation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +### Installation + +1. Open Github [releases page]({{nym_vpn_releases}}) and download the binary for Debian based Linux + +2. (Optional: if you don't want to check shasum, skip this point) Verify sha hash of your downloaded binary with the one listed on the [releases page]({{nym_vpn_releases}}). You can use a simple `shasum` command and compare strings (ie with Python) or run in the same directory the following command, exchanging `` with the one of your binary, like in the example: +```sh +echo "" | shasum -a 256 -c + +# choose a correct one according to your binary, this is just an example +# echo "a5f91f20d587975e30b6a75d3a9e195234cf1269eac278139a5b9c39b039e807 nym-vpn-desktop__ubuntu-22.04_x86_64.tar.gz" | shasum -a 256 -c +``` + +3. Extract files: +```sh +tar -xvf .tar.gz +# for example +# tar -xvf nym-vpn-desktop__ubuntu-22.04_x86_64.tar.gz +``` + +4. If you prefer to run `.AppImage` make executable by running: +```sh +# make sure you cd into the right sub-directory after extraction +chmod u+x ./nym-vpn__amd64.AppImage +``` + +5. If you prefer to use the `.deb` version for installation (works on Debian based Linux only), open terminal in the same directory and run: +```sh +# make sure you cd into the right sub-directory after extraction +sudo dpkg -i ./nym-vpn__amd64.deb +# or +sudo apt-get install -f ./nym-vpn__amd64.deb +``` + + + +## 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. + +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. + +Open terminal and run: + +```sh +# .AppImage must be run from the same directory as the binary +sudo -E ./nym-vpn__amd64.AppImage + +# .deb installation shall be executable from anywhere as +sudo -E nym-vpn +``` + +In case of errors, see [troubleshooting section](troubleshooting.md). diff --git a/documentation/docs/pages/developers/archive/nymvpn/gui-mac.md b/documentation/docs/pages/developers/archive/nymvpn/gui-mac.md new file mode 100644 index 0000000000..f3f3ccb89b --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/gui-mac.md @@ -0,0 +1,65 @@ +# NymVPN alpha - Desktop: Guide for Mac OS + +```admonish info +NymVPN is an experimental software and it's for testing 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. +``` + +## Preparation + +> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. + +### Installation + +1. Open Github [releases page]({{nym_vpn_releases}}) and download the binary for your version of MacOS + +2. Recommended (skip this point if you don't want to verify): Verify sha hash of your downloaded binary with the one listed on the [releases page]({{nym_vpn_releases}}). You can use a simple `shasum` command and compare strings (ie with Python) or run in the same directory the following command, exchanging `` with the one of your binary, like in the example: +```sh +echo "" | shasum -a 256 -c + +# choose a correct one according to your binary, this is just an example +# echo "da4c0bf8e8b52658312d341fa3581954cfcb6efd516d9a448c76d042a454b5df nym-vpn-desktop__macos_x86_64.zip" | shasum -a 256 -c +``` + +3. Extract the downloaded file manually or by a command: +```sh +tar -xvf .tar.gz +# for example +# tar -xvf nym-vpn-desktop__macos_aarch64.tar.gz +``` +4. Mount the `.dmg` image you extracted by double clicking on it and move it (drag it) to your `/Application` folder + + + +## 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. + +Run: +```sh +sudo /Applications/nym-vpn.app/Contents/MacOS/nym-vpn + +# If it didn't start try to run with -E flag +sudo -E /Applications/nym-vpn.app/Contents/MacOS/nym-vpn +``` + +In case of errors check out the [troubleshooting](troubleshooting.md#running-gui-failed-due-to-toml-parse-error) section. diff --git a/documentation/docs/pages/developers/archive/nymvpn/gui.md b/documentation/docs/pages/developers/archive/nymvpn/gui.md new file mode 100644 index 0000000000..6eda800aad --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/gui.md @@ -0,0 +1,50 @@ +# NymVPN - Desktop (GUI) + +```admonish info +Our alpha testing round is done with participants at live workshop events and the application in this stage may not work for everyone. + +**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 a desktop (GUI) version of NymVPN client. A demo of how the application will look like for majority of day-to-day users. + +Follow the simple [automated script](#automated-script-for-gui-installation) below to install and run NymVPN GUI. If the script didn't work for your distribution or you prefer to do a manual setup follow the steps in the guide for [Linux](gui-linux.md) or [MacOS](gui-mac.md) . + +Visit NymVPN alpha latest [release page]({{nym_vpn_releases}}) to check sha sums or download the binaries directly. + +## Linux AppImage Automated Installation Method + +The latest releases contain `appimage.sh` script. This method makes the installation simple for Linux users who want to run NymVPN from AppImmage. Executing the command below will download the binary to `~/.local/bin` and verify the checksum: +```sh +curl -fsSL https://github.com/nymtech/nym-vpn-client/releases/download/nym-vpn-desktop-v/appimage.sh | bash +``` + +Run with the command: +```sh +sudo -E ~/.local/bin/nym-vpn.appimage +``` + +## Automated Script for GUI Installation (Linux and Mac) + +We wrote a [script](https://gist.github.com/tommyv1987/7d210d4daa8f7abc61f9a696d0321f19) which does download of dependencies and the application, sha256 verification, extraction, installation and configuration for Linux and MacOS users automatically. Turn off all VPNs and follow the steps below. + +1. Open a terminal window in a directory where you want the script to be downloaded and run +```sh +curl -o nym-vpn-desktop-install-run.sh -L https://gist.githubusercontent.com/tommyv1987/7d210d4daa8f7abc61f9a696d0321f19/raw/939ac8d0afed69f43739b9cf2e5728454ea2c437/nym-vpn-client-install-run.sh && chmod u+x nym-vpn-desktop-install-run.sh && sudo -E ./nym-vpn-desktop-install-run.sh +``` + +2. Follow the prompts in the program + +To start the application again, reconnect your wifi and run +```sh +# Linux .AppImage +sudo -E ~/nym-vpn-latest/nym-vpn-desktop__ubuntu-22.04_x86_64/nym-vpn__amd64.AppImage + +# Linux .deb +sudo -E nym-vpn + +# MacOS +sudo -E $HOME/nym-vpn-latest/nym-vpn +``` + +In case of errors check out the [troubleshooting](troubleshooting.md#running-gui-failed-due-to-toml-parse-error) section. diff --git a/documentation/docs/pages/developers/archive/nymvpn/testing.md b/documentation/docs/pages/developers/archive/nymvpn/testing.md new file mode 100644 index 0000000000..849b670d8f --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/testing.md @@ -0,0 +1,209 @@ +# Testing NymVPN alpha + +
+ +```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. +``` + +> Before you get into testing NymVPN, make sure to go through the preparation steps for NymVPN [CLI](cli.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 ([download here]({{nym_vpn_releases}})) +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. Turn off any existing VPN's (including NymVPN instances), reconnect your wifi and run the `tests.sh` script +```sh +sudo ./tests.sh +```` +6. In case of errors, see the [troubleshooting section](troubleshooting.md#missing-jq-error) +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. 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 + +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/docs/pages/developers/archive/nymvpn/troubleshooting.md b/documentation/docs/pages/developers/archive/nymvpn/troubleshooting.md new file mode 100644 index 0000000000..1ae4046cdb --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn/troubleshooting.md @@ -0,0 +1,97 @@ +# 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 testing workshop or in the NymVPN [Matrix channel](https://matrix.to/#/#NymVPN:nymtech.chat). + +#### NymVPN attempts to connect to sandbox testnet + +If you testing the latest versions and you correctly expect the client to run over the mainnet, but it listens to `https://sandbox-nym-api1.nymtech.net`, it's probably because of your previous configuration. + +Check your `config.toml` either in the directory from which you run your client or in `~/.config/nym-vpn/` and remove `sandbox.env` from the config file and folder. + +If the problem persists (probably due to some locally cache) download [`mainnet.env`](https://github.com/nymtech/nym/blob/master/envs/mainnet.env) and save it to the same directory. + +#### Running GUI failed due to `TOML parse error` + +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. + +```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 +``` + +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 + +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 + + diff --git a/documentation/docs/pages/developers/coc.md b/documentation/docs/pages/developers/coc.md new file mode 100644 index 0000000000..f8771a73bf --- /dev/null +++ b/documentation/docs/pages/developers/coc.md @@ -0,0 +1,17 @@ +# Code of Conduct + +We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic. + +Please avoid using overtly sexual aliases or other nicknames that might detract from a friendly, safe and welcoming environment for all. + +Please be kind and courteous. There’s no need to be mean or rude. + +Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer. + +Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works. + +We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behaviour. We interpret the term “harassment” as including the definition in the Citizen Code of Conduct; if you have any lack of clarity about what might be included in that concept, please read their definition. In particular, we don’t tolerate behaviour that excludes people in socially marginalized groups. + +Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member, please contact one of the channel ops or any of the Rust moderation team immediately. Whether you’re a regular contributor or a newcomer, we care about making this community a safe place for you and we’ve got your back. + +Likewise any spamming, trolling, flaming, baiting or other attention-stealing behaviour is not welcome.