Initial Docs Draft

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)
+
+---

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.
+
+---

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.
+
+---

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"
+```
+
+---

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.
+
+---

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.
+
+---

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.
+
+---

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 <ip_address>:port <psf_fingerprint> psf=/home/user/bridge/file.psf
+```
+
+Connect to Tor and visit any site.
+
+This completes the client setup for tor.
+
+---