From ad867b16eae51f2e929d2dbb81b01935aab7e9a4 Mon Sep 17 00:00:00 2001
From: PromptPunksFauxCough
 <200402670+PromptPunksFauxCough@users.noreply.github.com>
Date: Sun, 2 Mar 2025 22:41:06 +0000
Subject: [PATCH] initiale

---
 docs/external-tor-usage.md | 414 +++++++++++++++++++++++++++++++++++++
 1 file changed, 414 insertions(+)
 create mode 100644 docs/external-tor-usage.md

diff --git a/docs/external-tor-usage.md b/docs/external-tor-usage.md
new file mode 100644
index 0000000000..37d01809f6
--- /dev/null
+++ b/docs/external-tor-usage.md
@@ -0,0 +1,414 @@
+# **Using External `tor` with `Haveno`**
+## *[How to install little-t-`tor`?](https://support.torproject.org/little-t-tor/#little-t-tor_install-little-t-tor)*
+
+The following `tor` installation instructions have are presented here for convenience.
+
+*  **For the most complete, up-to-date & authoritative steps, readers are encouraged to refer the [Tor Project's Official Homepage](https://www.torproject.org) linked in the header**
+
+* **Notes:**
+
+  For optimum compatibility with `Haveno` the running `tor` version should match that of the internal `Haveno` `tor` version
+
+  For best results, use a version of `tor` which supports the [Onion Service Proof of Work](https://onionservices.torproject.org/technology/security/pow)  (`PoW`) mechanism
+  * (IE: `GNU` build ot `tor`)
+
+---
+
+* **Note Regarding Admin Access:**
+
+  To install `tor` you need root privileges. Below all commands that need to be run as `root` user like `apt` and `dpkg` are prepended with `#`, while commands to be run as user with `$` resembling the standard prompt in a terminal.
+
+### macOS
+#### Install a Package Manager
+  Two of the most popular package managers for `macOS` are:
+
+  [`Homebrew`](https://brew.sh)
+
+  and
+
+  [`Macports`](https://www.macports.org)
+
+  (You can use the package manager of your choice)
+
+  + Install [`Homebrew`](https://brew.sh)
+
+    Follow the instructions on [brew.sh](https://brew.sh)
+
+  + Install [`Macports`](https://www.macports.org)
+
+    Follow the instructions on [macports.org](https://www.macports.org)
+
+#### Package Installation
+##### [`Homebrew`](https://brew.sh)
+  ```shell
+  # brew update && brew install tor
+  ```
+
+##### [`Macports`](https://www.macports.org)
+  ```shell
+  # port sync && port install tor
+  ```
+
+### Debian / Ubuntu
+* *Do **not** use the packages in Ubuntu's universe. In the past they have not reliably been updated. That means you could be missing stability and security fixes.*
+
+* Configure the [Official `Tor` Package Repository](https://deb.torproject.org/torproject.org)
+
+  Enable the [Official `Tor` Package Repository](https://deb.torproject.org/torproject.org) following these [instructions](https://support.torproject.org/apt/tor-deb-repo/)
+
+#### Package Installation
+```shell
+# apt update && apt install tor
+```
+
+### Fedora
+  * Configure the [Official `Tor` Package Repository](https://rpm.torproject.org/fedora)
+
+    Enable the [Official `Tor` Package Repository](https://rpm.torproject.org/fedora) by following these [instructions](https://support.torproject.org/rpm/tor-rpm-install)
+
+#### Package Installation
+```
+# dnf update && dnf install tor
+```
+
+### Arch Linux
+#### Package Installation
+```shell
+# pacman -Fy && pacman -Syu tor
+```
+
+### Installing `tor` from source
+#### Download Latest Release & Dependencies
+The latest release of `tor` can be found on the [download](https://www.torproject.org/download/tor) page
+
+* When building from source:
+
+  *First* install `libevent`,`openssl` & `zlib`
+
+  *(Including the -devel packages when applicable)*
+
+#### Install `tor`
+```shell
+$ tar -xzf tor-<version>.tar.gz; cd tor-<version>
+```
+
+* Replace \<version\> with the latest version of `tor`
+
+  > For example, `tor-0.4.8.12`
+
+```shell
+$ ./configure && make
+```
+
+* Now you can run `tor` (0.4.3.x and Later) locally like this:
+
+```shell
+$ ./src/app/tor
+```
+
+Or, you can run `make install` (as `root` if necessary) to install it globally into `/usr/local/`
+
+* Now you can run `tor` directly without absolute path like this:
+
+```shell
+$ tor
+```
+
+### Windows
+#### Download
+* Download the `Windows Expert Bundle` from the [Official `Tor` Project's Download page](https://www.torproject.org/download/tor)
+
+#### Extract
+* Extract Archive to Disk
+
+#### Open Terminal
+* Open PowerShell with Admin Privileges
+
+#### Change to Location of Extracted Archive
+* Navigate to `Tor` Directory
+
+#### Package Installation
+* v10
+```powershell
+PS C:\Tor\> tor.exe –-service install
+```
+
+* v11
+```powershell
+PS C:\Tor\> tor.exe –-service install
+```
+
+#### Create Service
+```powershell
+PS C:\Tor\> sc create tor start=auto binPath="<PATH TO>\Tor\tor.exe -nt-service"
+```
+
+#### Start Service
+```powershell
+PS C:\Tor\> sc start tor
+```
+
+### \* ***Optional*** \*
+#### [Set Up Your Onion Service](https://community.torproject.org/onion-services/setup)
+
+While not a *strict* requirement for use with `Haveno`, some users may wish to configure an [Onion Service](https://community.torproject.org/onion-services)
+
+  * ***Only Required When Using The `--hiddenServiceAddress` Option***
+
+Please see the [Official `Tor` Project's Documentation](https://community.torproject.org/onion-services/setup) for more information about configuration and usage of these services
+
+---
+
+## *`Haveno`'s Natively Aware `tor` Options*
+
+`Haveno` is a natively `tor` aware application and offers **many** flexible configuration options for use by privacy conscious users.
+
+While some are mutually exclusive, many are cross-applicable.
+
+Users are encouraged to experiment with options before use to determine which options best fit their personal threat profile.
+
+### Options
+#### `--hiddenServiceAddress`
+* Function:
+
+  This option configures a *static* Hidden Service Address to listen on  
+
+* Expected Input Format:
+
+  `<String>`
+
+  (`ed25519`)
+
+* Acceptable Values
+
+  `<v3 Onion Address Value>`
+
+* Default value:
+
+  `null`
+
+#### `--socks5ProxyXmrAddress`
+* Function:
+
+  A proxy address to be used for `monero` network
+
+* Expected Input Format:
+
+  `<String>`
+
+* Acceptable Values
+
+  `<Host:Port Value>`
+
+* Default value:
+
+  `null`
+
+#### `--torrcFile`
+* Function:
+
+  An existing `torrc`-file to be sourced for `tor`
+
+  **Note:**
+
+  `torrc`-entries which are critical to `Haveno`'s flawless operation (`torrc` options line, `torrc` option, ...) **can not** be overwritten
+
+* Expected Input Format:
+
+  `<String>`
+
+* Acceptable Values
+
+  `<Local File Location Value>`
+
+* Default value:
+
+  `null`
+
+#### `--torrcOptions`
+* Function:
+
+  A list of `torrc`-entries to amend to `Haveno`'s `torrc`
+
+    **Note:**
+
+    *`torrc`-entries which are critical to `Haveno`'s flawless operation (`torrc` options line, `torrc` option, ...) can **not** be overwritten*
+
+* Expected Input Format:
+
+  `<String>`
+
+* Acceptable Values
+
+  `<^([^\s,]+\s[^,]+,?\s*)+$>`
+
+* Default value:
+
+  `null`
+
+#### `--torControlHost`
++ Function
+
+  The control `hostname` or `IP` of an already running `tor` service to be used by `Haveno`
+
+* Expected Input Format
+
+  `<String>`
+
+  (`hostname`, `IPv4` or `IPv6`)
+
+* Acceptable Values
+
+  `<TorControl Host Value>`
+
+* Default Value
+
+  `null`
+
+#### `--torControlPort`
++ Function
+
+  The control port of an already running `tor` service to be used by `Haveno`
+
+* Expected Input Format
+
+  `<Numeric String>`
+
+* Acceptable Values
+
+  `<TorControlPort Value>`
+
+* Default Value
+
+  `-1`
+
+#### `--torControlPassword`
++ Function
+
+  The password for controlling the already running `tor` service
+
+* Expected Input Format
+
+  `<Alpha-Numeric-Special String>`
+
+* Acceptable Values
+
+  `<Passphrase Value>`
+
+* Default Value
+
+  `null`
+
+#### `--torControlCookieFile`
++ Function
+
+  The cookie file for authenticating against the already running `tor` service
+  * Used in conjunction with `--torControlUseSafeCookieAuth` option
+
+* Expected Input Format
+
+  `<Alpha-Numeric-Special String>`
+
+* Acceptable Values
+
+  `<Local File Location>`
+
+* Default Value
+
+  `null`
+
+#### `--torControlUseSafeCookieAuth`
++ Function
+
+  Use the `SafeCookie` method when authenticating to the already running `tor` service
+
+* Expected Input Format
+
+  `null`
+
+* Acceptable Values
+
+  `none`
+
+* Default Value
+
+  `off`
+
+#### `--torStreamIsolation`
++ Function
+
+  Use stream isolation for Tor
+  * This option is currently considered ***experimental***
+
+* Expected Input Format
+
+  `<Alpha String>`
+
+* Acceptable Values
+
+  `<on|off>`
+
+* Default Value
+
+  `off`
+
+#### `--useTorForXmr`
++ Function
+
+  Configure `tor` for `monero` connections with ***either***:
+
+  * after_sync
+
+    **or**
+
+  * off
+
+    **or**
+
+  * on
+
+* Expected Input Format
+
+  `<Alpha String>`
+
+* Acceptable Values
+
+  `<AFTER_SYNC|OFF|ON>`
+
+* Default Value
+
+  `AFTER_SYNC`
+
+#### `--socks5DiscoverMode`
++ Function
+
+  Specify discovery mode for `monero` nodes
+
+* Expected Input Format
+
+  `<mode[,...]>`
+
+* Acceptable Values
+
+  `ADDR, DNS, ONION, ALL`
+
+  One or more comma separated.
+
+  *(Will be **OR**'d together)*
+
+* Default Value
+
+  `ALL`
+
+---
+
+## *Examples*
+### Dynamic Onion Assignment via `--torControlPort`
+```shell
+$ /opt/haveno/bin/Haveno --torControlPort='9051' --torControlCookieFile='/var/run/tor/control.authcookie' --torControlUseSafeCookieAuth --useTorForXmr='on' --socks5ProxyXmrAddress='127.0.0.1:9050'
+```
+
+### Static Onion Assignment via `--hiddenServiceAddress`
+```shell
+$ /opt/haveno/bin/Haveno --socks5ProxyXmrAddress='127.0.0.1:9050' --useTorForXmr='on' --hiddenServiceAddress='2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion'
+```