From ae7206e0c29172e605e5f1d33362d670dc24df2d Mon Sep 17 00:00:00 2001 From: import this <97586125+serinko@users.noreply.github.com> Date: Wed, 28 Aug 2024 13:10:36 +0000 Subject: [PATCH] [DOCs/dev-portal]: Update NymVPN & socks5 cli docs --- documentation/dev-portal/src/SUMMARY.md | 2 +- .../dev-portal/src/clients/socks5-client.md | 149 +----------------- .../dev-portal/src/clients/socks5/setup.md | 126 ++++++++++++++- documentation/dev-portal/src/nymvpn/cli.md | 6 +- documentation/dev-portal/src/nymvpn/intro.md | 19 +-- 5 files changed, 134 insertions(+), 168 deletions(-) diff --git a/documentation/dev-portal/src/SUMMARY.md b/documentation/dev-portal/src/SUMMARY.md index 355ed85568..70b789373e 100644 --- a/documentation/dev-portal/src/SUMMARY.md +++ b/documentation/dev-portal/src/SUMMARY.md @@ -52,7 +52,7 @@ - [Integrations](faq/integrations-faq.md) # User Manuals -- [NymVPN alpha](nymvpn/intro.md) +- [NymVPN beta](nymvpn/intro.md) - [CLI](nymvpn/cli.md) --- diff --git a/documentation/dev-portal/src/clients/socks5-client.md b/documentation/dev-portal/src/clients/socks5-client.md index 75159cc40d..b72298df75 100644 --- a/documentation/dev-portal/src/clients/socks5-client.md +++ b/documentation/dev-portal/src/clients/socks5-client.md @@ -2,12 +2,16 @@ > The Nym Socks5 Client was built in the [building nym](../binaries/building-nym.md) section. If you haven't yet built Nym and want to run the code on this page, go there first. +**To install and operate `nym-socks5-client`, visit [Setup & Run](socks5/setup.md) and [Using Your Client](socks5/usage.md) pages.** + ## Current version + ``` ``` ## What is this client for? + Many existing applications are able to use either the SOCKS4, SOCKS4A, or SOCKS5 proxy protocols. If you want to send such an application's traffic through the mixnet, you can use the `nym-socks5-client` to bounce network traffic through the Nym network, like this: ``` @@ -64,147 +68,4 @@ The `nym-socks5-client` allows you to do the following from your local machine: The `nym-network-requester` then reassembles the original TCP stream using the packets' sequence numbers, and make the intended request. It will then chop up the response into Sphinx packets and send them back through the mixnet to your `nym-socks5-client`. The application will then receive its data, without even noticing that it wasn't talking to a "normal" SOCKS5 proxy! -## Client setup -### Viewing command help - -You can check that your binaries are properly compiled with: - -``` -./nym-socks5-client --help -``` - -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - -You can check the necessary parameters for the available commands by running: - -``` -./nym-client --help -``` - -### Initialising a new client instance -Before you can use the client, you need to initalise a new instance of it, which can be done with the following command: - -``` -./nym-socks5-client init --id docs-example --use-reply-surbs true --provider Entztfv6Uaz2hpYHQJ6JKoaCTpDL5dja18SuQWVJAmmx.Cvhn9rBJw5Ay9wgHcbgCnVg89MPSV5s2muPV2YF1BXYu@Fo4f4SQLdoyoGkFae5TpVhRVoXCF8UiypLVGtGjujVPf -``` - -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - -The `--id` in the example above is a local identifier so that you can name your clients and keep track of them on your local system; it is **never** transmitted over the network. - -The `--use-reply-surbs` field denotes whether you wish to send [SURBs](https://nymtech.net/docs/architecture/traffic-flow.md#private-replies-using-surbs) along with your request. It defaults to `false`, we are explicitly setting it as `true`. It defaults to `false` for compatibility with older versions of the [Network Requester](https://nymtech.net/nodes/network-requester.md). - -The `--provider` field needs to be filled with the Nym address of a Network Requester that can make network requests on your behalf. If you don't want to [run your own](https://nymtech.net/operators/nodes/network-requester.md) you can select one from the [mixnet explorer](https://explorer.nymtech.net/network-components/service-providers) by copying its `Client ID` and using this as the value of the `--provider` flag. Alternatively, you could use [this list](https://harbourmaster.nymtech.net/). - -#### Choosing a Gateway -By default - as in the example above - your client will choose a random gateway to connect to. - -However, there are several options for choosing a gateway, if you do not want one that is randomly assigned to your client: -* If you wish to connect to a specific gateway, you can specify this with the `--gateway` flag when running `init`. -* You can also choose a gateway based on its location relative to your client. This can be done by appending the `--latency-based-selection` flag to your `init` command. This command means that to select a gateway, your client will: - * fetch a list of all availiable gateways - * send few ping messages to all of them, and measure response times. - * create a weighted distribution to randomly choose one, favouring ones with lower latency. - -> Note this doesn't mean that your client will pick the closest gateway to you, but it will be far more likely to connect to gateway with a 20ms ping rather than 200ms - -### Configuring your client -When you initalise a client instance, a configuration directory will be generated and stored in `$HOME_DIR/.nym/socks5-clients//`. - -``` -tree $HOME//.nym/socks5-clients/docs-example -├── config -│   └── config.toml -└── data - ├── ack_key.pem - ├── credentials_database.db - ├── gateway_shared.pem - ├── persistent_reply_store.sqlite - ├── private_encryption.pem - ├── private_identity.pem - ├── public_encryption.pem - └── public_identity.pem - -``` - -The `config.toml` file contains client configuration options, while the two `pem` files contain client key information. - -The generated files contain the client name, public/private keypairs, and gateway address. The name `` in the example above is just a local identifier so that you can name your clients. - -#### Configuring your client for Docker -By default, the native client listens to host `127.0.0.1`. However this can be an issue if you wish to run a client in a Dockerized environment, where it can be convenenient to listen on a different host such as `0.0.0.0`. - -You can set this via the `--host` flag during either the `init` or `run` commands. - -Alternatively, a custom host can be set in the `config.toml` file under the `socket` section. If you do this, remember to restart your client process. - -### Running the socks5 client - -You can run the initialised client by doing this: - -``` -./nym-socks5-client run --id docs-example -``` - -## Automating your socks5 client with systemd - -Create a service file for the socks5 client at `/etc/systemd/system/nym-socks5-client.service`: - -```ini -[Unit] -Description=Nym Socks5 Client -StartLimitInterval=350 -StartLimitBurst=10 - -[Service] -User=nym # replace this with whatever user you wish -LimitNOFILE=65536 -ExecStart=/home/nym/nym-socks5-client run --id -KillSignal=SIGINT -Restart=on-failure -RestartSec=30 - -[Install] -WantedBy=multi-user.target -``` - -Now enable and start your socks5 client: - -``` -systemctl enable nym-socks5-client.service -systemctl start nym-socks5-client.service -# you can always check your socks5 client has succesfully started with: -systemctl status nym-socks5-client.service -``` - -## Using your Socks5 Client - -After completing the steps above, your local Socks5 Client will be listening on `localhost:1080` ready to proxy traffic to the Network Requester set as the `--provider` when initialising. - -When trying to connect your app, generally the proxy settings are found in `settings->advanced` or `settings->connection`. - -Here is an example of setting the proxy connecting in Blockstream Green: - -![Blockstream Green settings](../images/wallet-proxy-settings/blockstream-green.gif) - -Most wallets and other applications will work basically the same way: find the network proxy settings, enter the proxy url (host: **localhost**, port: **1080**). - -In some other applications, this might be written as **localhost:1080** if there's only one proxy entry field. - -## Useful Commands - -**no-banner** - -Adding `--no-banner` startup flag will prevent Nym banner being printed even if run in tty environment. - -**build-info** - -A `build-info` command prints the build information like commit hash, rust version, binary version just like what command `--version` does. However, you can also specify an `--output=json` flag that will format the whole output as a json, making it an order of magnitude easier to parse. +Since the introduction of `nym-node` binary, `nym-network-requester` is incorporated in every node running in `exit-gateway` mode. The narrow whitelist was exchanged for a less restrictive Nym [exit policy](https://nymtech.net/.wellknown/network-requester/exit-policy.txt), where except the IPs and ports all internet access is permitted. `nym-socks5-client` users can find a full list of Network Requester addresses on [Nym Harbourmaster](https://harbourmaster.nymtech.net/) under tab called *SOCKS5 NETWORK REQUESTERS*. diff --git a/documentation/dev-portal/src/clients/socks5/setup.md b/documentation/dev-portal/src/clients/socks5/setup.md index a1fc1210a3..26dc0fda7a 100644 --- a/documentation/dev-portal/src/clients/socks5/setup.md +++ b/documentation/dev-portal/src/clients/socks5/setup.md @@ -1,4 +1,4 @@ -# Setup +# Setup & Run Nym Socks5 Client > `nym-socks5-client` now also supports SOCKS4 and SOCKS4A protocols as well as SOCKS5. @@ -9,7 +9,7 @@ Since the beginning of 2024 NymConnect is no longer maintained. Nym is developin If users want to route their traffic through socks5 we advice to use this client. If you want to run deprecated NymConnect, visit [NymConnect archive page](../../archive/nym-connect.md) with setup and application examples. ``` -## Setup and Run +## Setup ### Download or compile socks5 client @@ -17,11 +17,11 @@ If you are using OSX or a Debian-based operating system, you can download the `n If you are using a different operating system, head over to the [Building from Source](https://nymtech.net/docs/binaries/building-nym.html) page for instructions on how to build the repository from source. -### Initialise your socks5 client +### Initialise Socks5 Client -To initialise your `nym-socks5-client` you need to have an address of a Network Requester (NR). Nowadays NR is part of every Exit Gateway (`nym-node --mode exit-gateway`). The easiest way to get a NR address is to visit [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/) and scroll down to *SOCKS5 Network Requesters* table. There you can filter the NR by Gateways identity address, and other options. +To initialise your `nym-socks5-client` you need to have an address of a Network Requester (NR). Nowadays NR is part of every Exit Gateway (`nym-node --mode exit-gateway`). The easiest way to get a NR address is to visit [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/) and open the tab called *SOCKS5 NETWORK REQUESTERS*. There you can filter the NR by Gateways identity address, and other options. -Use the following command to initialise `nym-socs5-client` where `` can be anything you want (it's only for local config file storage) and `` is suplemented with a NR address: +Use the following command to initialise `nym-socs5-client` where `` can be anything you want (it's only for local config file storage identification and never shared on the network) and `` is suplemented with a NR address: ``` ./nym-socks5-client init --id --provider @@ -37,9 +37,123 @@ Another option to find a NR address associated with a Gateway is to query nodes ``` ~~~ -### Start your socks5 client +## Run + Now your client is initialised, start it with the following: ``` ./nym-socks5-client run --id ``` + +## Useful commands + +### Viewing Command `--help` + +You can check that your binaries are properly compiled with: + +``` +./nym-socks5-client --help +``` + +~~~admonish example collapsible=true title="Console output" +``` + +``` +~~~ + +You can check the necessary parameters for the available commands by running: + +``` +./nym-socks5-client --help +``` +For example `./nym-socks5-client run --help` will return all options associated with `run` command. + +~~~admonish example collapsible=true title="Console output" +``` + +``` +~~~ + +### `build-info` + +A `build-info` command prints the build information like commit hash, rust version, binary version just like what command `--version` does. However, you can also specify an `--output=json` flag that will format the whole output as a json, making it an order of magnitude easier to parse. + +### Flags & Arguments + +* `--id`: A local identifier so that you can name your clients and keep track of them on your local system; it is **never** transmitted over the network. + +* `--use-reply-surbs`: This field denotes whether you wish to send [SURBs](https://nymtech.net/docs/architecture/traffic-flow.md#private-replies-using-surbs) along with your request. It defaults to `false` and must be explicitly set to `true` to activate. + +* `--use-anonymous-replies `: Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + +* `--gateway`: By default your client will choose a random gateway to connect to. However, there are several options for choosing a gateway, if you do not want one that is randomly assigned to your client: + +* `--latency-based-selection`: This flag will choose a gateway based on its location relative to your client. This argument means that to select a gateway, your client will: + * fetch a list of all availiable gateways + * send few ping messages to all of them, and measure response times. + * create a weighted distribution to randomly choose one, favouring ones with lower latency. + +> Note this doesn't mean that your client will pick the closest gateway to you, but it will be far more likely to connect to gateway with a 20ms ping rather than 200ms + +## Configuring `nym-socks5-client` + +When you initalise a client instance, a configuration directory will be generated and stored in `$HOME_DIR/.nym/socks5-clients//`. + +``` +tree $HOME/.nym/socks5-clients/ +├── config +│   └── config.toml +└── data + ├── ack_key.pem + ├── credentials_database.db + ├── gateways_registrations.sqlite + ├── persistent_reply_store.sqlite + ├── private_encryption.pem + ├── private_identity.pem + ├── public_encryption.pem + └── public_identity.pem +``` + +The `config.toml` file contains client configuration options, while the two `pem` files contain client key information. + +The generated files contain the client name, public/private keypairs, and gateway address. The name `` in the example above is just a local identifier so that you can name your clients. + +### Configuring your client for Docker + +By default, the native client listens to host `127.0.0.1`. However this can be an issue if you wish to run a client in a Dockerized environment, where it can be convenenient to listen on a different host such as `0.0.0.0`. + +You can set this via the `--host` flag during either the `init` or `run` commands. + +Alternatively, a custom host can be set in the `config.toml` file under the `socket` section. If you do this, remember to restart your client process. + +### Automating your socks5 client with systemd + +Create a service file for the socks5 client at `/etc/systemd/system/nym-socks5-client.service`: + +```ini +[Unit] +Description=Nym Socks5 Client +StartLimitInterval=350 +StartLimitBurst=10 + +[Service] +User=nym # replace this with whatever user you wish +LimitNOFILE=65536 +ExecStart=/home/nym/nym-socks5-client run --id +KillSignal=SIGINT +Restart=on-failure +RestartSec=30 + +[Install] +WantedBy=multi-user.target +``` + +Now enable and start your socks5 client: + +``` +systemctl enable nym-socks5-client.service +systemctl start nym-socks5-client.service + +# you can always check your socks5 client has succesfully started with: +systemctl status nym-socks5-client.service +``` diff --git a/documentation/dev-portal/src/nymvpn/cli.md b/documentation/dev-portal/src/nymvpn/cli.md index ae74274cf3..dc1c2f2238 100644 --- a/documentation/dev-portal/src/nymvpn/cli.md +++ b/documentation/dev-portal/src/nymvpn/cli.md @@ -1,7 +1,7 @@ # 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 tip title="NymVPN CLI Testnet" +If you testing NymVPN CLI and want to try our Sandbox testnet environment, you can visit an explicit guide at [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net/). This page alco contains an auto generating access token button. ``` ```admonish info @@ -225,7 +225,7 @@ Options: ## Testnet environment -If you want to run NymVPN CLI in Nym Sandbox environment, there are a few adjustments to be done: +If you want to run NymVPN CLI in Nym Sandbox environment, there are a few adjustments to be done. You can follow the steps below or follow more explicit guide on [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net), including the access token auto generation button. 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 diff --git a/documentation/dev-portal/src/nymvpn/intro.md b/documentation/dev-portal/src/nymvpn/intro.md index 02150ffe5a..b559d22bd6 100644 --- a/documentation/dev-portal/src/nymvpn/intro.md +++ b/documentation/dev-portal/src/nymvpn/intro.md @@ -1,19 +1,13 @@ -# NymVPN alpha +# NymVPN beta -
- -```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). +**NymVPN** 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. +**You are invited to take part in the beta 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.* +*NOTE: NymVPN beta is experimental software for testing purposes only.* ## NymVPN Overview @@ -32,7 +26,4 @@ client ───► Gateway ──┘ mix │ mix ┌─►mix ───► 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. - +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 through the mixnet. The client than use two wireguard tunnels with the Entry and Exit Gateway nodes, the Exit Gateway one being tunnelled itself through the Entry Gateway tunnel. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device.