From aa26ba5da1e2b25a1426cef6ac0e2d765fe893d6 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 29 Oct 2024 11:42:45 +0100 Subject: [PATCH] added standalone tcpproxy binary info --- .../docs/pages/developers/rust/tcpproxy.mdx | 2 + documentation/docs/pages/developers/tools.mdx | 2 + .../docs/pages/developers/tools/_meta.json | 3 +- .../developers/tools/standalone-tcpproxy.mdx | 62 +++++++++++++++++++ 4 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 documentation/docs/pages/developers/tools/standalone-tcpproxy.mdx diff --git a/documentation/docs/pages/developers/rust/tcpproxy.mdx b/documentation/docs/pages/developers/rust/tcpproxy.mdx index 287232a27f..e4bfac03b1 100644 --- a/documentation/docs/pages/developers/rust/tcpproxy.mdx +++ b/documentation/docs/pages/developers/rust/tcpproxy.mdx @@ -3,3 +3,5 @@ This module exposes the `TcpProxyClient` and the `TcpProxyServer` which can be used to proxy traffic through the Mixnet in a way that is more familiar to developers than the methods exposed by the [`Mixnet` module](./mixnet). Both `Client` and `Server` are intended to be initialised and then run in a background thread, exposing a configurable `localhost` socket which developers can read/write/stream to without having to worry about the [message-based](../concepts/messages) nature of sending and receiving traffic to/from the Mixnet. + +> Non-Rust/Go developers who want to experiment with this module can start with the [standalone binaries](../tools/standalone-tcpproxy). diff --git a/documentation/docs/pages/developers/tools.mdx b/documentation/docs/pages/developers/tools.mdx index f07507f497..ccd413c5ba 100644 --- a/documentation/docs/pages/developers/tools.mdx +++ b/documentation/docs/pages/developers/tools.mdx @@ -3,3 +3,5 @@ There are a few tools available to developers for chain interaction: the `nym-cli` tool, which operates as an easier-to-use wrapper around `nyxd`, to allow operators to script interactions with their infrastructure (and those who prefer CLI tools ;) ). There is also a basic echo server tool which app developers can use as a quick endpoint for traffic testing. This will be deployed onto a persistent public server in the future so devs dont have to run it themselves. + +Finally, there are a pair of standalone versions of the TcpProxy Rust SDK module for developers to begin experimenting with sending app traffic through them mixnet. diff --git a/documentation/docs/pages/developers/tools/_meta.json b/documentation/docs/pages/developers/tools/_meta.json index 0577fbabb6..8aa37f3c3b 100644 --- a/documentation/docs/pages/developers/tools/_meta.json +++ b/documentation/docs/pages/developers/tools/_meta.json @@ -1,4 +1,5 @@ { "nym-cli": "Nym-cli", - "echo-server": "Echo Server" + "echo-server": "Echo Server", + "standalone-tcpproxy": "TcpProxy Binaries (Standalone)" } diff --git a/documentation/docs/pages/developers/tools/standalone-tcpproxy.mdx b/documentation/docs/pages/developers/tools/standalone-tcpproxy.mdx new file mode 100644 index 0000000000..177a080a5c --- /dev/null +++ b/documentation/docs/pages/developers/tools/standalone-tcpproxy.mdx @@ -0,0 +1,62 @@ +# Standalone TcpProxy Binaries + +Standalone versions of the `TcpProxyClient` and `TcpProxyServer` [sdk module](../rust/tcpproxy) can be found [here](https://github.com/nymtech/standalone-tcp-proxies/tree/main). + +These might be an easy way for developers to start proxying their traffic throught the mixnet and understanding the sort of latency they should expect, and whether their application can currently tolerate it. They might also prove useful for server setups where several components are being run via init scripts, and the addition of a separate process is acceptable. + +## Build +```shell +cargo build --release +``` + +## Use +```shell +» ./target/release/proxy_server --help +Usage: proxy_server [OPTIONS] --upstream-tcp-address + +Options: + -u, --upstream-tcp-address + Upstream address of the server process we want to proxy traffic to e.g. 127.0.0.1:9067 + -c, --config-dir + Config directory [default: /tmp/nym-tcp-proxy-server] + -e, --env-path + Optional env filepath - if none is supplied then the proxy defaults to using mainnet else just use a path to one of the supplied files in envs/ e.g. ./envs/sandbox.env + -h, --help +``` + +```shell +» ./target/release/proxy_client --help +Usage: proxy_client [OPTIONS] --server-address + +Options: + --close-timeout + Send timeout in seconds [default: 30] + -s, --server-address + Nym address of the NymProxyServer e.g. EjYsntVxxBJrcRugiX5VnbKMbg7gyBGSp9SLt7RgeVFV.EzRtVdHCHoP2ho3DJgKMisMQ3zHkqMtAFAW4pxsq7Y2a@Hs463Wh5LtWZU@NyAmt4trcCbNVsuUhry1wpEXpVnAAfn + --listen-address + Listen address [default: 127.0.0.1] + --listen-port + Listen port [default: 8080] + -e, --env-path + Optional env filepath - if none is supplied then the proxy defaults to using mainnet else just use a path to one of the supplied files in envs/ e.g. ./envs/sandbox.env + -h, --help + Print help +``` + +## Run +```shell +# set up the server on your remote machine, listening on the port your upstream process is expecting to communicate on (e.g. 127.0.0.1:9067). +# this will log the Nym address of the Nym Proxy Server to pass to the proxy_client +./target/release/proxy_server -u + + +# start your proxy client with the address of the server client. by default this listens on 127.0.0.1:8080 +./target/release/proxy_client --server-address + +# now start your client process, directing its traffic to the listen port of your nym proxy client process. all traffic will now be proxied through the mixnet. +``` + +> You can run on another network by downloading on of the [env files](https://github.com/nymtech/nym/tree/nym-binaries-v2024.12-aero/envs) and passing that to both clients with `-e ` + +### A Note on Switching Networks +If you are running the `proxy_server` binary on one network and then switch to another, make sure to either specify a new env-specific directory for key and surb storage, or remove the existing one, before running the binary. Since the `proxy_client` relies on ephemeral clients, then this is not a problem for this binary.