Merge pull request #7 from Start9Labs/tor-setup

add instructions for tor setup on all systems and for firefox

source/_static/default.css

@@ -5,7 +5,7 @@ body, h1, h2, h3, h4, nav, .topbar, .topbar-main, .tocsection, .form-control, .b
 
 h1 {
     font-size: 2rem;
-    margin-top: 2rem;
+    margin-top: 3.5rem;
 }
 
 h2 {
@@ -25,7 +25,6 @@ p, nav a  {
     letter-spacing: 0.75px;
 }
 
-
 a, a:visited, .headerlink {
     color: #ff4961!important;
 }
@@ -60,13 +59,14 @@ h1, h2 {
     display: inline;
 }
 
-.main-content {
-    margin-top: 1rem;
+.bd-sidebar {
+    background: none;
 }
 
 @media (min-width: 768px) {
     .bd-sidebar {
         border-right: 1px solid #f8f8ff;
+        background: none;
     }
 }
 
@@ -163,4 +163,12 @@ nav.bd-links .fa-chevron-up:hover, nav.bd-links .fa-chevron-down:hover {
 
 nav.bd-links > ul.nav {
   padding-right: 8px;
+}
+
+.highlight > pre {
+  background-color: lightgray;
+}
+
+.set-padding {
+    padding-top: 75px!important;
 }

source/_static/js/main.js

@@ -9,3 +9,11 @@ $(document).ready(function () {
       $(this).parent().children(".admonition-title").toggleClass("open");
   })
 });
+// $(window).on('load', function () {
+//   console.log("loaded")
+
+//   $('a').click(function () {
+//     console.log('tag clicked')
+//     $("body.scrolled").addClass("set-padding")
+//     })
+// })

source/getting-started/introduction.rst

@@ -10,4 +10,4 @@ So what do you do with your Embassy? You use it to run services: Bitcoin, Lightn
 
 Every communication between you and your Embassy is end-to-end encrypted and onion routed over the Tor network. All services are open-source and self-hosted, meaning there are no trusted third parties of any kind.
 
-To get an Embassy, you can :ref:`purchase<purchase>` one directly from Start9 Labs, or you can :ref:`build one yourself<diy>`.
+To get an Embassy, you can :ref:`purchase<purchasing>` one directly from Start9 Labs, or you can :ref:`build one yourself<diy>`.

source/getting-started/purchase.rst

@@ -1,7 +0,0 @@
-.. _purchase:
-
-********
-Purchase
-********
-
-For maximum convenience, you can buy an Embassy directly from Start9 Labs through our `Shopify Store <https://store.start9labs.com>`_. The device comes fully-assembled and pre-installed with the latest version of EmbassyOS. We do its own hardware assembly and fulfillment, and we only collect the minimal information necessary to fulfil your order. And yes, we accept Bitcoin.

source/getting-started/purchasing.rst

@@ -0,0 +1,9 @@
+.. _purchasing:
+
+**********
+Purchasing
+**********
+
+For maximum convenience, you can purchase an Embassy device directly from Start9 Labs through our `Shopify Store <https://store.start9labs.com>`_. The device comes in a beutiful box, fully-assembled, and pre-installed with the latest version of EmbassyOS. We do our own hardware assembly and fulfillment, and we only collect the minimal information necessary to fulfill your order. And yes, we accept Bitcoin.
+
+If you prefer to build your own Embassy, you can follow the :ref:`DIY Guide <diy>`.

source/index.rst

@@ -11,15 +11,25 @@ Here you will find guidance and information about the Start9 Embassy personal se
   :caption: Getting Started
 
   getting-started/introduction
-  getting-started/purchase
+  getting-started/purchasing
   getting-started/diy
 
 .. toctree::
   :maxdepth: 2
-  :caption: User Manuals
+  :caption: User Manual
 
-  user-manuals/embassyos/index
-  user-manuals/available-services/index
+  user-manual/initial-setup
+  user-manual/connecting
+  user-manual/general/index
+  user-manual/managing-services/index
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Misc Guides
+
+  misc-guides/available-services
+  misc-guides/tor-os/index
+  misc-guides/tor-firefox/index
 
 .. toctree::
   :maxdepth: 2

source/misc-guides/available-services.rst

@@ -4,7 +4,7 @@
 Available Services
 ******************
 
-A list of currently released services for EmbassyOS. Links to the wrapper repository that contains advanced instructions and integration guides.
+A list of currently-available services for the Embassy.
 
 Bitcoin-related services
 ========================
@@ -20,6 +20,6 @@ Other services
 ==============
 
 * `Bitwarden <https://github.com/Start9Labs/bitwarden-wrapper/tree/master/docs>`_
+* `Burn After Reading <https://github.com/Start9Labs/burn-after-reading>`_
 * `Cups <https://github.com/Start9Labs/cups-wrapper/tree/master/docs>`_
-* `File Browser <https://github.com/Start9Labs/filebrowser-wrapper/tree/master/docs>`_
-* `Burn After Reading <https://github.com/Start9Labs/burn-after-reading>`_
+* `File Browser <https://github.com/Start9Labs/filebrowser-wrapper/tree/master/docs>`_

source/misc-guides/tor-firefox/android.rst

@@ -0,0 +1,46 @@
+.. _firefox-tor-android:
+
+**************************************
+Setting up Firefox with Tor on Android
+**************************************
+
+.. warning::
+  This guide assumes you have completed :ref:`setting up Tor for Android<tor-android>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
+
+Once Tor is setup on your system, you can proceed to setup Firefox.
+
+Download `Firefox Beta <https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta>`_ from the Play Store, or Fennec for F-Droid.
+
+Now, you need to download a `Proxy Auto Config` file that will use Orbot to resolve `.onion` URLs. We have one hosted `here <https://registry.start9labs.com/sys/proxy.pac>`_.
+
+Next, navigate to ``about:config`` in the Firefox URL bar:
+
+.. figure:: /_static/images/tor/about_config.png
+  :width: 50%
+  :alt: Firefox about config
+
+You are going to have to change a few options in here. First, type ``network.proxy.type`` into the search bar, and set the value to ``2``:
+
+.. figure:: /_static/images/tor/network_proxy_type.png
+  :width: 50%
+  :alt: Firefox network proxy type setting screenshot
+
+Then, search for ``network.proxy.autoconfig_url``, and set the value to ``file:///storage/emulated/0/Download/proxy.pac``:
+
+.. figure:: /_static/images/tor/autoconfig_url.png
+  :width: 50%
+  :alt: Firefox autoconfig url setting screenshot
+
+Next, search for ``network.proxy.socks_remote_dns``, and set the value to ``true``:
+
+.. figure:: /_static/images/tor/socks_remote_dns.png
+  :width: 50%
+  :alt: Firefox socks remote dns setting screenshot
+
+Next, search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``.
+
+.. figure:: /_static/images/tor/firefox_whitelist_mobile.png
+  :width: 50%
+  :alt: Firefox whitelist onions screenshot
+
+Restart Firefox, and you’re all set! You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Password Manager <https://play.google.com/store/apps/details?id=com.x8bit.bitwarden&hl=en_US&gl=US>`_ native application.

source/misc-guides/tor-firefox/index.rst

@@ -0,0 +1,18 @@
+.. _configure_firefox_tor:
+
+***************************
+Configuring Firefox for Tor
+***************************
+
+.. warning::
+  This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
+
+Once you have completed the above guide, select your device's operating system below:
+
+.. toctree::
+  :maxdepth: 1
+
+  MacOS <mac>
+  Windows <windows>
+  Linux <linux>
+  Android <android>

source/misc-guides/tor-firefox/linux.rst

@@ -0,0 +1,54 @@
+.. _firefox-tor-linux:
+
+************************************
+Setting up Firefox with Tor on Linux
+************************************
+
+.. warning::
+  This guide assumes you have completed :ref:`setting up Tor for Linux<tor-linux>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
+
+Open Firefox.
+
+Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
+
+Search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``.
+
+.. figure:: /_static/images/tor/firefox_whitelist.png
+  :width: 80%
+  :alt: Firefox whitelist onions screenshot
+
+Next, in order to tell Firefox which urls to use Tor for, you need a `Proxy Auto Config` file. We have one hosted `here <https://registry.start9labs.com/sys/proxy.pac>`_. To get it, you can run:
+
+.. code-block::
+
+  sudo wget -P /etc/tor https://registry.start9labs.com/sys/proxy.pac
+
+Now open your Firefox web browser, and select preferences:
+
+.. figure:: /_static/images/tor/firefox_preferences.png
+  :width: 80%
+  :alt: Firefox preferences screenshot
+
+  Select :menuselection:`Settings --> Preferences`
+
+Search for the term “proxy” in the search bar in the upper right, then select the button that says `Settings…`:
+
+.. figure:: /_static/images/tor/firefox_search.png
+  :width: 80%
+  :alt: Firefox search screenshot
+
+This should open a menu that will allow you to configure your proxy settings. Select `Automatic proxy configuration URL` and paste in:
+
+.. code-block::
+
+  file:///etc/tor/proxy.pac
+
+Then, check the box labeled `Proxy DNS when using SOCKS v5`:
+
+.. figure:: /_static/images/tor/firefox_proxy.png
+  :width: 80%
+  :alt: Firefox proxy settings screenshot
+
+Click ``OK`` and then restart Firefox for the changes to take effect.
+
+Now you’re all set! You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_.

source/misc-guides/tor-firefox/mac.rst

@@ -0,0 +1,62 @@
+.. _firefox-tor-mac:
+
+************************************
+Setting up Firefox with Tor on MacOS
+************************************
+
+.. warning::
+  This guide assumes you have completed :ref:`setting up Tor for MacOS<tor-mac>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
+
+Open Firefox.
+
+Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
+
+Search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``.
+
+.. figure:: /_static/images/tor/firefox_whitelist.png
+  :width: 80%
+  :alt: Firefox whitelist onions screenshot
+
+Now, open the `Terminal` App on your Mac. You can find it in your list of Applications.
+
+In order to tell Firefox which URLs to use Tor for, you need a `Proxy Auto Config` file. We have one hosted `here <https://registry.start9labs.com/sys/proxy.pac>`_. To get it, enter into the terminal:
+
+.. code-block::
+
+  brew install wget
+
+And then:
+
+.. code-block::
+
+  wget -P /usr/local/etc/tor https://registry.start9labs.com/sys/proxy.pac
+
+Now open your Firefox web browser, and select preferences:
+
+.. figure:: /_static/images/tor/firefox_preferences.png
+  :width: 80%
+  :alt: Firefox preferences screenshot
+
+  Select :menuselection:`Settings --> Preferences`
+
+Search for the term “proxy” in the search bar in the upper right, then select the button that says `Settings…`:
+
+.. figure:: /_static/images/tor/firefox_search.png
+  :width: 80%
+  :alt: Firefox search screenshot
+
+This should open a menu that will allow you to configure your proxy settings. Select `Automatic proxy configuration URL` and paste in:
+
+.. code-block::
+
+  file:///usr/local/etc/tor/proxy.pac
+
+Then, check the box labeled `Proxy DNS when using SOCKS v5`:
+
+.. figure:: /_static/images/tor/firefox_proxy.png
+  :width: 80%
+  :alt: Firefox proxy settings screenshot
+
+Click ``OK`` and then restart Firefox for the changes to take effect.
+
+Now you’re all set! You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_.

source/misc-guides/tor-firefox/windows.rst

@@ -0,0 +1,54 @@
+.. _firefox-tor-windows:
+
+**************************************
+Setting up Firefox with Tor on Windows
+**************************************
+
+.. warning::
+  This guide assumes you have completed :ref:`setting up Tor for Windows<tor-windows>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
+
+Open Firefox.
+
+Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
+
+Search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``.
+
+.. figure:: /_static/images/tor/firefox_whitelist.png
+  :width: 80%
+  :alt: Firefox whitelist onions screenshot
+
+Now, you need to download a `Proxy Auto Config` file that will use the Tor service to resolve .onion urls. We have one hosted `here <https://registry.start9labs.com/sys/proxy.pac>`_. Save it somewhere you won’t delete it. For this example:
+
+.. code-block::
+
+  C:\Program Files\Tor Browser\proxy.pac
+
+Now open your Firefox web browser, and select options:
+
+.. figure:: /_static/images/tor/firefox_options_windows.png
+  :width: 80%
+  :alt: Firefox options screenshot
+
+  Select :menuselection:`Settings --> Options`
+
+Search for the term “proxy” in the search bar in the upper right, then select the button that says `Settings…`:
+
+.. figure:: /_static/images/tor/firefox_search.png
+  :width: 80%
+  :alt: Firefox search screenshot
+
+This should open a menu that will allow you to configure your proxy settings. Select `Automatic proxy configuration URL` and paste in the path to your PAC file from earlier, prefixed with ``file://``. For example:
+
+.. code-block::
+
+  file://C:/Program Files/Tor Browser/proxy.pac
+
+Then, check the box labeled `Proxy DNS when using SOCKS v5`:
+
+.. figure:: /_static/images/tor/firefox_proxy.png
+  :width: 80%
+  :alt: Firefox proxy settings screenshot
+
+Click ``OK`` and then restart Firefox for the changes to take effect.
+
+Now you’re all set! You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_.

source/misc-guides/tor-os/android.rst

@@ -0,0 +1,70 @@
+.. _tor-android:
+
+**********************
+Running Tor on Android
+**********************
+
+.. warning::
+    Custom proxies are now only available in `Firefox Beta <https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta&hl=en_US&gl=US>`_ or `Firefox Nightly <https://play.google.com/store/apps/details?id=org.mozilla.fenix&hl=en_US&gl=US>`_ due to a breaking change by the Firefox team.
+
+First, install the Tor proxy service to your system. To do so, open the play store and download `Orbot <https://play.google.com/store/apps/details?id=org.torproject.android>`_. Once you have done so, launch Orbot.
+
+Next, open the kebab menu in the upper right hand corner and select `Settings`:
+
+.. figure:: /_static/images/tor/orbot_menu.png
+  :width: 50%
+  :alt: Orbot menu
+
+Then, make sure the options for `Start Orbot on Boot` and `Allow Background Starts` are checked:
+
+.. figure:: /_static/images/tor/orbot_settings.png
+  :width: 50%
+  :alt: Orbot settings
+
+Go back, and tap start:
+
+.. figure:: /_static/images/tor/orbot_start.png
+  :width: 50%
+  :alt: Orbot start
+
+Orbot will start up the Tor service. Once complete, you will see:
+
+.. figure:: /_static/images/tor/orbot_started.png
+  :width: 50%
+  :alt: Orbot started
+
+You can now close Orbot.
+
+Setting up Orbot VPN mode
+-------------------------
+
+Orbot's VPN mode allows certain applications to utilize it's Tor service.
+
+This process also applies for GrapheneOS.
+
+To setup, first disable Private DNS on your device. To do so, navigate to: ``Settings > Network & Internet > Advanced > Private DNS > Off``
+
+.. figure:: /_static/images/tor/private_dns_off.png
+  :width: 50%
+  :alt: Private DNS off
+  
+  Toggle Private DNS to "off"
+
+Next, launch Orbot and toggle VPN Mode on while on the main screen:
+
+.. figure:: /_static/images/tor/orbot_vpn.png
+  :width: 50%
+  :alt: Orbot vpn mode
+  
+  Toggle VPN Mode to "on"
+
+Under `Tor-Enabled Apps`, select the gear to add applications that need to be proxied through VPN mode to utilize Tor. 
+
+.. figure:: /_static/images/tor/orbot_apps.png
+  :width: 50%
+  :alt: Orbot apps
+  
+Examples of applications that need this feature are:
+
+- Bitwarden
+- Zap

source/misc-guides/tor-os/index.rst

@@ -0,0 +1,17 @@
+.. _running-tor:
+
+***********
+Running Tor
+***********
+
+Running Tor on your phone or computer enables apps that are not Tor-enabled to communicate over Tor.
+
+Select your operating system to get started:
+
+.. toctree::
+  :maxdepth: 1
+
+  MacOS<mac>
+  Windows<windows>
+  Linux<linux>
+  Android<android>

source/misc-guides/tor-os/linux.rst

@@ -0,0 +1,13 @@
+.. _tor-linux:
+
+********************
+Running Tor on Linux
+********************
+
+All you need to do is install the Tor proxy service to your system. To do so, open your terminal and run the following command:
+
+.. code-block::
+
+    sudo apt update && sudo apt install tor
+
+That's it! Your Linux machine is now setup to natively use Tor.

source/misc-guides/tor-os/mac.rst

@@ -0,0 +1,40 @@
+.. _tor-mac:
+
+********************
+Running Tor on MacOS
+********************
+
+First, you need to install the Tor proxy service to your system. This will require opening your Terminal. 
+
+To open your terminal, hold the command key ⌘ + spacebar. `Spotlight Search` will appear. Start typing "terminal" and select the program called `Terminal`.
+
+
+Paste in the following commands and hit <Enter>.
+
+.. code-block::
+
+    which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+    brew install tor
+    brew services start tor
+
+When this completes, you should see something like:
+
+.. code-block::
+
+    ==> Successfully started `tor` (label: homebrew.mxcl.tor)
+
+If you notice issues connecting to Tor websites, try restarting the Tor service. Open the terminal and run:
+
+.. code-block::
+
+    brew services restart tor
+
+After running this command, you should see something like:
+
+.. code-block::
+
+    Stopping `tor`... (might take a while)
+    ==> Successfully stopped `tor` (label: homebrew.mxcl.tor)
+    ==> Successfully started `tor` (label: homebrew.mxcl.tor)
+
+That's it! Your Mac is now setup to natively use Tor.

source/misc-guides/tor-os/windows.rst

@@ -0,0 +1,42 @@
+.. _tor-windows:
+
+**********************
+Running Tor on Windows
+**********************
+
+First, you need to install the Tor proxy service to your system. Unfortunately, `torproject.org` no longer publishes a standalone Tor binary for Windows, so the recommended way to get it is with the Tor Browser Bundle. You can download it `here <https://www.torproject.org/download/>`_.
+
+.. figure:: /_static/images/tor/tor_download_windows.png
+  :width: 80%
+  :alt: Tor download
+
+  Download Tor for Windows
+
+Once it is downloaded, go ahead and run the installer. If you want to install the program outside of your user directory, you will have to right click and select `Run as Administrator`. Once you have selected a language, you should see a menu like this:
+
+.. figure:: /_static/images/tor/tor_windows_install.png
+  :width: 80%
+  :alt: Tor install wizard
+
+  Note Tor destination folder when installing
+
+It does not matter where you set the destination folder, however you need to make note of it for later. Go ahead and finish the installation.
+
+Now you want to set up Tor to run as a service: to run in the background and keep itself running so you don’t have to worry about it again. To do so, you need to open your Command Prompt as an administrator.
+In Windows 10, you can simply type ``cmd`` in the Windows search bar, right click on the first result, and select `Run as Administrator`.
+Once it opens, you can run the following commands, inserting your destination folder in place of ``<PATH TO>``:
+
+.. code-block::
+
+    sc create tor start=auto binPath="<PATH TO>\Tor Browser\Browser\TorBrowser\Tor\tor.exe -nt-service"
+    sc start tor
+
+When you run this, it should look something like this:
+
+.. figure:: /_static/images/tor/tor_windows_terminal.png
+  :width: 80%
+  :alt: Tor windows terminal
+
+  Replace highlighted section with noted destination folder
+
+That's it! Your Windows computer is now setup to natively use Tor. 

source/user-manual/connecting.rst

@@ -12,7 +12,7 @@ If you accidentally leak your Embassy's addresses, do not worry. You Embassy is
 Tor
 ===
 
-Connecting to your Embassy over :ref:`tor` requires using a browser that supports *.onion* URLs.
+Connecting to your Embassy over :ref:`tor` requires using a browser that supports :code:`.onion` URLs.
 
 Currently, Tor is the default and our recommended approach for most users. It *just works*. The one drawback, however, is latency; onion-routed communications over Tor can be slow. For a lightning fast experience, you can connect to your Embassy over LAN (below), but this requires additional setup.
 
@@ -24,9 +24,12 @@ Below are a list of our recommended browsers for Tor:
 * `Tor Browser <https://torproject.org/download/>`_ (Mac, Windows, Linux, Android)
 * `Brave <https://brave.com/>`_ (Mac, Windows, Linux)
 
-.. seealso:: `Setting up Firefox to handle Tor addresses <https://medium.com/@start9labs/setting-up-your-firefox-web-browser-to-handle-onion-urls-b805391726e4>`_
-
-.. seealso:: `Announcing the Consulate Browser! <https://medium.com/@start9labs/announcing-the-consulate-browser-76d94a8599cb>`_
+.. seealso:: 
+    :ref:`Setting up Tor for browsers <running-tor>`
+    
+    :ref:`configure_firefox_tor`
+    
+    `Announcing the Consulate Browser! <https://medium.com/@start9labs/announcing-the-consulate-browser-76d94a8599cb>`_
 
 
 LAN

source/user-manual/managing-services/index.rst

@@ -1,6 +1,6 @@
-**************
-Using Services
-**************
+*****************
+Managing Services
+*****************
 
 Services are self-hosted, open source projects made compatible for EmbassyOS. Each service is has been independently developed by members of the open source community. The Embassy enables configuration, customization and a one click install.
 

source/user-manuals/embassyos/index.rst

@@ -1,11 +0,0 @@
-*********
-EmbassyOS
-*********
-
-.. toctree::
-  :maxdepth: 2
-
-  initial-setup
-  connecting
-  general/index
-  using-services/index