diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5089372 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,12 @@ +# README + +This directory documents the usage and deployment of Proteus. + +- To run Proteus as tor bridge, please read ['tor_bridge_setup.md'](tor_bridge_setup.md) +- To run Proteus as tor client, please read ['tor_client_setup.md'](tor_client_setup.md) +- To run Proteus as a standalone proxy server, please read ['standalone_proxy_setup.md'](standalone_proxy_setup.md) +- To run Proteus as a standalone client proxy, please read ['standalone_client_setup.md'](standalone_client_setup.md) +- To run Proteus as a client directly via CLI, please read ['tor_socks_client.md'](tor_socks_client.md) +- To run Proteus as a client via Termux in mobile, please read ['mobile_phone_setup.md'](mobile_phone_setup.md) + +--- diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..83488fb --- /dev/null +++ b/docs/install.md @@ -0,0 +1,53 @@ +# Installation + +This file documents the installation process of Proteus. +Follow the following steps to build proteus from source: + +## Prerequisites + +- For debian based OSes + +``` +sudo apt install -y build-essential pkg-config libssl-dev +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +- For arch based OSes + +``` +sudo pacman -S base-devel pkgconf openssl rustup +rustup toolchain install 1.87 +``` + +--- + +## Procedure + +1. Clone the repo and enter the repo directory + +``` +git clone https://github.com/unblockable/proteus.git +cd proteus +``` + +2. Build latest release of proteus + +``` +cargo build --release +``` + +or without release build + +``` +cargo build +``` + +3. Verify the installation + +``` +./target/release/proteus --help +``` + +This completes the installation process of Proteus. + +--- diff --git a/docs/mobile_phone_setup.md b/docs/mobile_phone_setup.md new file mode 100644 index 0000000..3b9dee8 --- /dev/null +++ b/docs/mobile_phone_setup.md @@ -0,0 +1,79 @@ +# Termux + +This document helps users in running Proteus in their mobila phones via termux. +We assume the user is at home (~) + +--- + +## Procedure + +1. First install the prerequisites + +``` +[~/] $ pkg install tor torsocks curl +``` + +2. Create a directory and enter (optional, recommended) + +``` +[~/] $ mkdir -p bridge +[~/] $ cd bridge +``` + +3. Install Proteus. Please follow the following steps instead of installation guide. + +``` +[~/bridge] $ pkg install git clang lld rust make pkg-config openssl +[~/bridge] $ git clone https://github.com/unblockable/proteus.git +[~/bridge] $ cd proteus +[~/bridge/proteus] $ cargo build --release +``` + +4. Go back to bridge directory and create torrc file + +``` +[~/bridge/proteus] $ cd .. +[~/bridge] $ nano torrc +``` + +5. Edit torrc and add the info: + +``` +ClientTransportPlugin proteus exec /data/data/com.termux/files/home/bridge/proteus/target/release/proteus pt +Bridge proteus xx.xx.xx.xx:yyyy psf=/data/data/com.termux/files/home/path/to/file.psf +SocksPort 127.0.0.1:9150 +DataDirectory /data/data/com.termux/files/home/bridge/data +``` + +Note that using "~" instead of `/data/data/com.termux/files/home/` will return errors while running torrc. +So, write full address instead of using ~ only. + +6. Create the data directory and edit permissions + +``` +[~/bridge] $ mkdir -p data +[~/bridge] $ chmod 700 data +``` + +7. Run torrc + +``` +tor -f torrc +``` + +8. Keep it running and test the connection in a new tab + +``` +export TORSOCKS_TOR_PORT=9150 +torsocks curl https://www.torproject.org/ +``` + +or + +``` +curl --socks5-hostname 127.0.0.1:9150 https://www.torproject.org/ +``` + +This completes the procedure. + +--- diff --git a/docs/post_bridge_setup.md b/docs/post_bridge_setup.md new file mode 100644 index 0000000..4c33b09 --- /dev/null +++ b/docs/post_bridge_setup.md @@ -0,0 +1,35 @@ +# Post Bridge + +This document helps bridge operators after the setup. + +--- + +## Fingerprint + +To view the fingerprint + +``` +cat ~/bridge/data/fingerprint +``` + +--- + +## Running + +After setup, operators can just run their bridge using one command only. + +``` +/usr/bin/tor -f ~/bridge/torrc +``` + +--- + +## Stopping + +To stop the bridge, either press Ctrl+C or kill the process + +``` +pkill -f "tor -f ~/bridge/torrc" +``` + +--- diff --git a/docs/standalone_client_setup.md b/docs/standalone_client_setup.md new file mode 100644 index 0000000..2fa5462 --- /dev/null +++ b/docs/standalone_client_setup.md @@ -0,0 +1,35 @@ +# Standalone Client Setup + +This document guides user for deploying Proteus as a standalone client proxy. +We used port 8099 for this guide, but users can pick any unused port. + +--- + +## Procedure + +1. Install Proteus using the [Installation Guide](install.md). + +2. Start Proteus client and choose a local listening address. + +``` +[~/bridge/proteus] $ ./target/release/proteus client /path/to/file.psf --connect xx.xx.xx.xx:yyyy --listen 127.0.0.1:8099 +``` + +2. Verify the use of proxy. + +``` +[~/] $ curl --socks5-hostname 127.0.0.1:8099 https://www.torproject.org/ +``` + +(or any other website of choice) + +3. Applications that support proxy settings can be configured with: + +``` +SOCKS5 proxy: 127.0.0.1 +SOCKS5 port: 8099 +``` + +This completes the standalone Proteus client setup. + +--- diff --git a/docs/standalone_proxy_setup.md b/docs/standalone_proxy_setup.md new file mode 100644 index 0000000..f911908 --- /dev/null +++ b/docs/standalone_proxy_setup.md @@ -0,0 +1,26 @@ +# Standalone Proxy Setup + +This document guides user for deploying Proteus as a standalone proxy server. +This setup is useful when testing Proteus without Tor Browser. + +--- + +## Procedure + +1. First, install Proteus using the [Installation Guide](install.md) file. + +2. Start Proteus server and use a PSF. + +``` +[~/bridge/proteus] $ ./target/release/proteus server /home/user/bridge/file.psf --listen 0.0.0.0:yyyy +``` + +Operators can also change logging level if they want logs: + +``` +[~/bridge/proteus] $ ./target/release/proteus --log-level debug server /home/user/bridge/file.psf --listen 0.0.0.0:yyyy +``` + +This completes the standalone Proteus proxy server setup. + +--- diff --git a/docs/tor_bridge_setup.md b/docs/tor_bridge_setup.md new file mode 100644 index 0000000..0156022 --- /dev/null +++ b/docs/tor_bridge_setup.md @@ -0,0 +1,54 @@ +# Tor Bridge Setup + +This document guides user for deploying Proteus as a Tor bridge. +We also provide the current directory info along with command to help better. + +--- + +## Procedure + +First, we assume that user is at `/home/user/` directory. + +1. Create a directory (optional, recommended) and enter it. + +``` +[~/] $ mkdir -p bridge +[~/] $ cd bridge +``` + +2. Install the Proteus inside the bridge directory. +Use [`Installation Guide`](install.md) for help. + +3. Add binding permissions to Proteus and Tor. +(required for ports <1024) + +``` +[~/bridge/proteus] $ sudo setcap cap_net_bind_service=+eip target/release/proteus +[~/bridge/proteus] $ sudo setcap cap_net_bind_service=+eip /usr/bin/tor +``` + +4. Go to bridge directory and create a new directory for data, then change the directory permissions. We name it data for convinience, users can pick any name. + +``` +[~/bridge/proteus] $ cd .. +[~/bridge] $ mkdir -p data +[~/bridge] $ chmod 700 ~/bridge/data +``` + +5. Create a torrc file and fill the details + +``` +[~/bridge] $ nano torrc +``` + +The details of torrc are given in [torrc.md](torrc.md) file. + +6. After writing the torrc, run it using + +``` +/usr/bin/tor -f ~/bridge/torrc +``` + +This completes the setup of Proteus as tor bridge. + +--- diff --git a/docs/tor_client_setup.md b/docs/tor_client_setup.md new file mode 100644 index 0000000..12b4006 --- /dev/null +++ b/docs/tor_client_setup.md @@ -0,0 +1,48 @@ +# Client Setup + +This document guides user for deploying Proteus as a Tor client. +We also provide the current directory info along with command to help better. + +--- + +## Procedure + +First, we assume that user is at `/home/user/` directory. + +1. Create a directory (optional, recommended) and enter it. + +``` +[~/] $ mkdir -p bridge +[~/] $ cd bridge +``` + +2. Install the Proteus inside the bridge directory. +Use [`Installation Guide`](install.md) for help. + +3. Find the torrc file of Tor browser + +``` +[~/bridge] find ~ -iname "torrc" 2>/dev/null +``` + +Note that the torrc file of Tor browser is different from `/etc/tor/torrc` + +4. Add Proteus usage to Torrc + +``` +ClientTransportPlugin proteus exec ~/bridge/proteus/target/release/proteus pt +``` + +5. Get a PSF and put it in bridge directory. We assume the psf is at bridge/ directory as "file.psf" + +6. Go to Tor browser and enter details manually for bridge + +``` +proteus :port psf=/home/user/bridge/file.psf +``` + +Connect to Tor and visit any site. + +This completes the client setup for tor. + +--- diff --git a/docs/tor_socks_client.md b/docs/tor_socks_client.md new file mode 100644 index 0000000..e43003a --- /dev/null +++ b/docs/tor_socks_client.md @@ -0,0 +1,51 @@ +# Tor SOCKS Client Setup + +This document guides user for testing a Proteus bridge through Tor's local +SOCKS5 proxy. +It may be helpful for those who don't want to change the Tor bundle and want to test Proteus directly via CLI. + +## Procedure + +We assume the user is at `/home/user` directory. + +1. Create a directory and enter it (optional, recommended) + +``` +[~/] $ mkdir -p bridge +[~/] $ cd bridge +``` + +2. Install Proteus using the [`Installation Guide`](install.md) inside bridge. + +3. Create a torrc. Note that we don't use systemwide torrc, because it doesn't work by default due to permission problems. + +``` +[~/bridge] $ touch torrc +[~/bridge] $ nano torrc +``` + +4. In the torrc file, add Proteus as Tor pluggable transport and also add the bridge line. +The port 9050 is already used by Tor, so we use port 9150. Add it to torrc. + +``` +ClientTransportPlugin proteus exec /home/user/bridge/proteus/target/release/proteus pt +Bridge proteus xx.xx.xx.xx:yyyy psf=/path/to/file.psf +SocksPort 127.0.0.1:9150 +``` + +5. Start the process and keep it running. + +``` +[~/] $ tor -f ~/bridge/torrc +``` + +6. In a new tab, test the connection with torsocks. For that, we first need to set port, then test site. + +``` +[~/bridge] $ export TORSOCKS_TOR_PORT=9150 +[~/bridge] $ torsocks curl https://www.torproject.org/ +``` + +This completes the Tor SOCKS client setup. + +--- diff --git a/docs/torrc.md b/docs/torrc.md new file mode 100644 index 0000000..9f5ab27 --- /dev/null +++ b/docs/torrc.md @@ -0,0 +1,72 @@ +# Torrc + +This file helps users in filling the torrc file for Proteus + +``` +ContactInfo User # Operator contact info +Nickname Proteus # Human-readable nickname + +Address xx.xx.xx.xx # IPv4 address +OutboundBindAddress xx.xx.xx.xx # Source address used for Tor's outgoing connections +ORPort xx.xx.xx.xx:yyyy # Address and port for Tor relay connections +AssumeReachable 1 # Skip self-reachability checks; advertise immediately + +ExitRelay 0 # Keep it 0 always for proteus bridge +ExitPolicy reject *:* # Reject exit traffic +SocksPort 0 # Tor's local SOCKS proxy port + +BridgeRelay 1 # Operate as a bridge +PublishServerDescriptor 0 # Do not publish bridge descriptor publicly +ExtORPort 0 # Extended ORPort +ServerTransportPlugin proteus exec /path/to/proteus pt # Launch Proteus as the server transport +ServerTransportListenAddr proteus xx.xx.xx.xx:443 # Have Proteus listen for bridge traffic on TCP 443 +ServerTransportOptions proteus psf=/path/to/file.psf # Write the PSF along with the address + +MaxMemInQueues x GB # Cap memory used by Tor's message queues +NumCPUs x # Number of CPU workers Tor should use +LogTimeGranularity x msec # Round log timestamps to x millisecond +ShutdownWaitLength x seconds # Wait up to x second during graceful shutdown + +DataDirectory /home/user/bridge/data # Directory for Tor state, keys, and cached data +PidFile /home/user/bridge/data/tor.pid # File containing Tor's process ID +Log notice file /home/user/bridge/data/notice.log # Write notice-and-higher priority logs to this file +``` + +--- + +## Example + +Users can fill the details using reference. +Please do NOT fill exact same details as following, only use as reference. + +``` +ContactInfo Ajay +Nickname Proteus + +Address 66.116.244.138 +OutboundBindAddress 66.116.244.138 +ORPort 66.116.244.138:9001 +AssumeReachable 1 + +ExitRelay 0 +ExitPolicy reject *:* +SocksPort 0 + +BridgeRelay 1 +PublishServerDescriptor 0 +ExtORPort 0 +ServerTransportPlugin proteus exec /home/ajay/bridge/proteus/target/release/proteus pt +ServerTransportListenAddr proteus 66.116.244.138:443 +ServerTransportOptions proteus psf=/home/ajay/bridge/proteus/tests/fixtures/tls_mimic.psf + +MaxMemInQueues 1 GB +NumCPUs 1 +LogTimeGranularity 1 msec +ShutdownWaitLength 1 seconds + +DataDirectory /home/ajay/bridge/data +PidFile /home/ajay/bridge/data/tor.pid +Log notice file /home/ajay/bridge/data/notice.log +``` + +---