Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-30 12:11:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

re-arrange the user docs (#76)

Browse Source 
* re-arrange the user docs

* Minor description edit

* update styles

* fix service links

Co-authored-by: kn0wmad <kn0wmad@protonmail.com>
Co-authored-by: Lucy Cifferello <12953208+elvece@users.noreply.github.com>
This commit is contained in:
Matt Hill
2022-02-18 08:49:53 -07:00
committed by GitHub
parent c38d5c1a0c
commit aed86e7e6c
151 changed files with 500 additions and 781 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
site/source/user-manual/connecting/index.rst Normal file
View File

@@ -0,0 +1,40 @@
.. _connecting:
==========
Connecting
==========
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: LAN
:link: lan-setup
:icon: scylla-icon scylla-icon--home
:class: large-5
:anchor: Setup
Connect to Embassy over your Local Area Network.
.. topic-box::
:title: Tor
:link: tor-setup
:icon: scylla-icon scylla-icon--tor
:class: large-5
:anchor: Setup
Connect to Embassy over the Tor network.
.. raw:: html
</div></div>
.. toctree::
:maxdepth: 1
:hidden:
lan-setup/index
tor-setup/index

13
site/source/user-manual/connecting/lan-setup/index.rst Normal file
View File

@@ -0,0 +1,13 @@
.. _lan-setup:
=========
LAN Setup
=========
When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access<lan>` is much faster and will allow access to your data, even with no Internet connection. Begin by setting up :ref:`Devices<lan-os>` before setting up a :ref:`Browser<lan-browser>`.
.. toctree::
:maxdepth: 2
lan-os/index
lan-browser/index

17
site/source/user-manual/connecting/lan-setup/lan-browser/index.rst Normal file
View File

@@ -0,0 +1,17 @@
.. _lan-browser:
=============
LAN - Browser
=============
When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access<lan>` is much faster and will allow access to your data, even with no Internet connection.
.. caution:: You will first need to complete :ref:`LAN Setup<lan-os>` for your device before continuing.
.. toctree::
:maxdepth: 2
lan-brave
lan-chrome
lan-ff
lan-safari

46
site/source/user-manual/connecting/lan-setup/lan-browser/lan-brave.rst Normal file
View File

@@ -0,0 +1,46 @@
.. _lan-brave:
=====
Brave
=====
.. caution:: You will first need to complete :ref:`LAN Setup<lan-os>` for your device before continuing.
#. Open a new tab in Brave and Navigate to ``Settings`` from the top-right hamburger menu.
.. figure:: /_static/images/ssl/browser/brave_settings.png
:width: 30%
:alt: Brave settings page
#. On the left hand sidebar, select the Security and Privacy section, then the Security menu item.
.. figure:: /_static/images/ssl/browser/brave_security.png
:width: 60%
:alt: Brave Security and Privacy settings
#. At the bottom of the section, select "Manage Certificates".
.. figure:: /_static/images/ssl/browser/brave_security_settings.png
:width: 60%
:alt: Brave Security settings page
#. If you **EITHER** see "org-Start9" with a trusted “Embassy Local Root CA” listed under it, open a new tab to apply the certificate. If this does not work, quit and restart Chrome.
**OR**
#. If you do not see "org-Start9"in the list, ensure the certificate is properly set up on your computer system. Otherwise, click “Import” and open the downloaded ``Embassy Local Root CA.crt`` file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps <lan-os>`.
.. figure:: /_static/images/ssl/browser/brave_view_certs.png
:width: 60%
:alt: Brave Manage Certificates sub-menu on MacOS
Check the box for "Trust this certificate for identitying websites" and click "OK"
#. Obtain the LAN address that was provided at the end of your initial Embassy setup, or from the :ref:`Embassy tab<embassy-tab>` -> ``About`` (Under ``Insights``) and enter it in a new tab.
.. tip:: You may need to restart the browser
#. You will see a green padlock and ``https://`` to the left of the URL bar. You can now securely navigate to your Embassy on your :ref:`LAN<lan>` with :ref:`HTTPS<ssl>`!
.. note:: Additionally, you can start a Brave private window with Tor to visit the Tor address over HTTPS (unnecessary in principle, but will circumvent annoying browser warnings).

49
site/source/user-manual/connecting/lan-setup/lan-browser/lan-chrome.rst Normal file
View File

@@ -0,0 +1,49 @@
.. _lan-chrome:
======
Chrome
======
.. caution:: You will first need to complete :ref:`LAN Setup<lan-os>` for your device before continuing.
.. tip:: The following guide also works with Chromium and Vivaldi.
#. Open a new tab in Chrome and navigate to ``chrome://settings/certificates``.
.. figure:: /_static/images/ssl/browser/chrome_settings.png
:width: 60%
:alt: Chrome Certificates Settings page
#. Click on the "Authorities" tab.
.. figure:: /_static/images/ssl/browser/chrome_authorities.png
:width: 60%
:alt: Chrome Certificate Authorities page
#. You will **EITHER** see "org-Start9" with a trusted “Embassy Local Root CA” listed under it,
.. figure:: /_static/images/ssl/browser/chrome_s9ca.png
:width: 60%
:alt: Start9 Certificate Authority
in which case, open a new tab to apply the certificate. If this does not work, quit and restart Chrome.
**OR**
#. If you do not see "org-Start9"in the list, ensure the certificate is properly set up on your computer system. Otherwise, click “Import” and open the downloaded ``Embassy Local Root CA.crt`` file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps <lan-os>`.
.. figure:: /_static/images/ssl/browser/chrome_trust.png
:width: 60%
:alt: Trust the CA
Check the box for "Trust this certificate for identitying websites" and click "OK"
#. Obtain the LAN address that was provided at the end of your initial Embassy setup, or from the :ref:`Embassy tab<embassy-tab>` -> ``About`` (Under ``Insights``) and enter it in a new tab.
.. tip:: You may need to restart the browser
.. figure:: /_static/images/ssl/browser/chrome_https.png
:width: 60%
:alt: Success
#. You will see a green padlock and ``https://`` to the left of the URL bar. You can now securely navigate to your Embassy on your :ref:`LAN<lan>` with :ref:`HTTPS<ssl>`!

39
site/source/user-manual/connecting/lan-setup/lan-browser/lan-ff.rst Normal file
View File

@@ -0,0 +1,39 @@
.. _lan-ff:
=======
Firefox
=======
#. Open Firefox and in a new tab select ``Settings`` from the right-hand hamburger menu:
.. figure:: /_static/images/tor/os_ff_settings.png
:width: 30%
:alt: Firefox options screenshot
#. Select “Privacy and Security” from the left hand navigation menu.
#. Scroll all the way to the bottom of the page and select “View Certificates”.
.. figure:: /_static/images/ssl/browser/firefox_security_settings.png
:width: 80%
:alt: Firefox security settings
Firefox privacy and security settings page
#. Select the "Authorities" tab from the "Certificate Manager".
#. Click “Import” and open the downloaded ``Embassy Local Root CA.crt`` file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps <lan-setup>`.
#. When prompted, check “Trust this CA to identity websites” and select “OK”.
.. figure:: /_static/images/ssl/browser/firefox_view_certs.png
:width: 80%
:alt: Firefox import cert
Firefox import certificate page
#. Ensure the “Embassy Local Root CA” exists under “Start9 Labs”. Then click “OK” to save.
#. Open a new tab in Firefox to apply the changes. If this does not work, quit and restart Firefox.
#. Navigate to the LAN address provided at setup, or in the :ref:`Embassy tab<embassy-tab>` -> LAN. You can now securely navigate to your Embassy over HTTPS!

7
site/source/user-manual/connecting/lan-setup/lan-browser/lan-safari.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _lan-safari:
======
Safari
======
Once you have completed the :ref:`LAN Setup<lan-os>` steps on your device, simply open a new tab to apply the changes. If this does not work, quit and restart Safari. You can now securely navigate to the LAN address for your Embassy!

16
site/source/user-manual/connecting/lan-setup/lan-os/index.rst Normal file
View File

@@ -0,0 +1,16 @@
.. _lan-os:
============
LAN - Device
============
When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access<lan>` is much faster and will allow access to your data, even with no Internet connection.
.. toctree::
:maxdepth: 2
lan-linux
lan-mac
lan-windows
lan-android
lan-ios

33
site/source/user-manual/connecting/lan-setup/lan-os/lan-android.rst Normal file
View File

@@ -0,0 +1,33 @@
.. _lan-android:
=======
Android
=======
If you are running Android 12+ (not yet available on Calyx/Graphene), you can setup :ref:`Local Access<lan>`, please refer to :ref:`Android Limitations <lim-android>` for more details.
.. note:: You must download your certificate via desktop/laptop over Tor and then transfer it to your phone (Step 3)
#. Either use the Root CA you downloaded at the completion of :ref:`Initial Setup<initial-setup>`, or visit your Embassy at its Tor Address (for security purposes), and navigate to the :ref:`Embassy tab<embassy-tab>` -> LAN
.. figure:: /_static/images/ssl/embassy_lan_setup.png
:width: 60%
:alt: LAN setup menu item
#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine
.. figure:: /_static/images/ssl/embassy_lan_setup0.png
:width: 60%
:alt: LAN setup page
#. Send the cert to yourself via Signal, email, File Browser, etc and download onto your Android device
#. Go to Settings -> Security -> Advanced -> Encryption and Credentials -> Install a Certificate and select the cert you downloaded from the file system
.. figure:: /_static/images/ssl/android/droidLAN0.png
:width: 30%
:alt: Install certificate
#. To setup in Firefox Beta or Fennec, go to Settings -> About -> tap the logo several times until it says "Debug menu enabled." Then return to Settings -> Secret Settings and toggle on "Use third party CA certificates."
#. That's it! You may now browse the ``.local`` addresses on your Embassy.

75
site/source/user-manual/connecting/lan-setup/lan-os/lan-ios.rst Normal file
View File

@@ -0,0 +1,75 @@
.. _lan-ios:
===
iOS
===
.. note:: For security, this will need to be done using a Tor connection. Please use Onion Browser or Consulate to access your Embassy and complete the following steps.
#. You will first need to get your :ref:`LAN Certificate<lan-cert>`, which can be found either:
#. When completing your Embassy :ref:`Initial Setup<initial-setup>`, it is provided on the final screen
or:
#. In the ``Embassy`` tab in your Embassy, under ``Settings`` -> ``LAN``
.. figure:: /_static/images/ssl/embassy_lan_setup.png
:width: 60%
:alt: LAN setup menu item
#. Select ``Download Root CA``. Clicking this will prompt you to “Save to device”.
.. figure:: /_static/images/ssl/embassy_lan_setup0.png
:width: 60%
:alt: LAN setup page
#. You will be directed to a page in your default browser indicating next steps and that the profile has been successfully downloaded. Be sure to complete all steps in this process! These steps are also outlined below.
.. note::
If you have changed the default browser from Safari to Brave, the following auto save certificate to device flow will *not* work. Safari, Firefox, and Chrome work as expected. We recommend you temporarily use one of these browsers to complete this action.
.. figure:: /_static/images/ssl/ios/ssl_certificate_install_page.png
:width: 40%
:alt: Certificate install page
Select "Allow" on the certificate install page
#. Go to Settings on your iOS device.
.. figure:: /_static/images/ssl/ios/ssl_ipad_general_settings.png
:width: 40%
:alt: General settings
#. Navigate to *General > Profile(s) > Downloaded Profile > Install*.
.. figure:: /_static/images/ssl/ios/ssl_ipad_profiles.png
:width: 40%
:alt: Profiles
.. figure:: /_static/images/ssl/ios/ssl_ipad_install_profile.png
:width: 40%
:alt: Install profile
Select "Install" for Embassy Local Root CA
#. Select “Yes” to any warning prompts.
#. Next, navigate to *General > About > Certificate Trust Settings*.
.. figure:: /_static/images/ssl/ios/ssl_ipad_cert_trust_settings.png
:width: 40%
:alt: Certificate trust settings
Select Certificate Trust Settings (scroll all the way down)
#. Enable full trust for root certificates.
.. figure:: /_static/images/ssl/ios/ssl_ipad_cert_trust.png
:width: 40%
:alt: Enable full trust
Toggle to enable full trust for root certificates. "Continue" when warning prompts.
#. Test that this process worked successfully by navigating to the LAN address provided from one of the locations listed under Step 1 at the top of this page. You should not see warnings about the security of this site in your browser (if you do, setup was not successful).

25
site/source/user-manual/connecting/lan-setup/lan-os/lan-linux.rst Normal file
View File

@@ -0,0 +1,25 @@
.. _lan-linux:
=====
Linux
=====
Nothing specific needs to be configured for the Linux environment, so you just need to download the certificate from your Embassy.
#. Visit your Embassy at its Tor Address.
.. note:: Using this encrypted Tor connection is required for security reasons.
#. Navigate to the :ref:`Embassy tab<embassy-tab>` -> Settings -> LAN
.. figure:: /_static/images/ssl/embassy_lan_setup.png
:width: 60%
:alt: LAN setup menu item
#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/ssl/embassy_lan_setup0.png
:width: 60%
:alt: LAN setup page
Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <lan-browser>`.

55
site/source/user-manual/connecting/lan-setup/lan-os/lan-mac.rst Normal file
View File

@@ -0,0 +1,55 @@
.. _lan-mac:
===
Mac
===
#. Visit your Embassy at its Tor Address (for security purposes), and navigate to the :ref:`Embassy tab<embassy-tab>` -> LAN
.. figure:: /_static/images/ssl/embassy_lan_setup.png
:width: 60%
:alt: LAN setup menu item
#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/ssl/embassy_lan_setup0.png
:width: 60%
:alt: LAN setup page
#. Select the option to ``Open with`` "Keychain Access" and select ``OK``. If you choose to save the file, double click on it once downloaded.
.. figure:: /_static/images/ssl/embassy_lan_setup1.png
:width: 60%
:alt: LAN setup prompt
#. Enter your computer password when prompted. It will be imported into your mac's keychain.
.. figure:: /_static/images/ssl/macos/certificate_untrusted.png
:width: 60%
:alt: Keychain access import menu
Keychain access import menu
.. note:: If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it.
#. Navigate to the "System" tab on the left, find the certificate entitled “Embassy Local Root CA”, and double click on this certificate. A second window will pop up.
#. Open the “Trust” dropdown and select “Always Trust” from the dropdown next to “When using this certificate”.
.. figure:: /_static/images/ssl/macos/always_trust.png
:width: 60%
:alt: Keychain submenu
Select "Always trust" under the "Trust" dropdown for Embassy Local CA
#. Close this window and enter your password to apply the settings.
#. The “Embassy Local Root CA” cert will now read “This certificate is marked as trusted for all users” in Keychain Access.
.. figure:: /_static/images/ssl/macos/certificate_trusted.png
:width: 60%
:alt: Keychain menu trusted certificate
Trusted Embassy Local CA certificate
#. Open your favorite browser and follow the steps for :ref:`browser setup <lan-browser>` to complete LAN setup.

109
site/source/user-manual/connecting/lan-setup/lan-os/lan-windows.rst Normal file
View File

@@ -0,0 +1,109 @@
.. _lan-windows:
=======
Windows
=======
Unfortunately, Windows does not have mDNS support built-in, which is necessary in order to visit .local addresses, so we recommend using the Bonjour service. Check out this :ref:`FAQ answer<why-bonjour>` for details.
#. Install `Bonjour Print Services <https://support.apple.com/kb/DL999>`_ on your Windows machine.
.. tip:: If you are experiencing issues after installing Bonjour, you might have had a previous or failed install. To fix:
#. Check out this video: https://www.youtube.com/watch?v=9ECCB3bqNDQ
#. Uninstall Bonjour completely via ``system settings -> remove programs``
#. Reinstall Bonjour Printer Driver package (download at https://support.apple.com/kb/DL999?locale=en_US)
#. Restart Windows
#. Note: Uninstalling Bonjour via the setup package seems to be not enough to solve the issue. Bonjour must be uninstalled via windows system settings.
#. Visit your Embassy at its Tor Address.
.. note:: Using this encrypted Tor connection is required for security reasons.
#. Navigate to the :ref:`Embassy tab<embassy-tab>` -> Settings -> LAN
.. figure:: /_static/images/ssl/embassy_lan_setup.png
:width: 90%
:alt: LAN setup menu item
#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/ssl/embassy_lan_setup0.png
:width: 90%
:alt: LAN setup page
#. Back in Windows, right-click the “Start” menu and select “Run”.
#. Type in “mmc” and click “OK”. When prompted on the “User Account Control” window, select “Yes” to allow this program to run.
.. figure:: /_static/images/ssl/windows/1_windows_mmc.png
:width: 90%
:alt: Windows MMC
Access the Windows Management Console
#. When the Management Console opens, navigate to *File > Add/Remove Snap-in*.
.. figure:: /_static/images/ssl/windows/2_windows_console_root.png
:width: 90%
:alt: Windows Console Root
Add Snap-in from Console Root
#. Select “Certificates” in the left side menu, then “Add”. This will open another window.
.. figure:: /_static/images/ssl/windows/3_windows_add_certificates.png
:width: 90%
:alt: Add Certificates
Add Certificates to selected snap-ins
#. Select “Computer account” and click “Next. Leave defaulted options on the next screen and click “Finish”.
#. When you return to the “Add or Remove Snap-ins” page, ensure “Certificates (Local Computer)” exists under “Console Root” in the “Selected snap-ins” section, then click “OK”.
.. figure:: /_static/images/ssl/windows/4_windows_selected_snapin.png
:width: 90%
:alt: Snap-in Selected
Certificates (Local Computer) is selected as snap-in
#. In the left hand menu of the Management Console, navigate to Certificates (Local Computer) > Trusted Root Certification Authorities > Certificates.
.. figure:: /_static/images/ssl/windows/5_windows_trusted_certificate_menu.png
:width: 90%
:alt: Certificates in Management Console
Access Certificates in Management Console
#. Right click on “Certificates”, then navigate to *All Tasks > Import*.
.. figure:: /_static/images/ssl/windows/6_windows_import_cert.png
:width: 90%
:alt: Import certificate
Select "Import" from Certificates sub-menu
#. Click “Next” on the first page of the Certificate Import Wizard, then browse to the location where you saved the downloaded certificate and click “Open”.
.. figure:: /_static/images/ssl/windows/7_windows_import_cert_wizard.png
:width: 90%
:alt: Import cert wizard
Add downloaded certificate int he Certificate Import Wizard
#. On the “Certificate Store” window, ensure that it says “Trusted Root Certificate Authorities” and click “Next”.
#. Select “OK” when the import is successful.
#. Verify the Embassy Local Root CA certificate is in the “Certificates” folder.
.. figure:: /_static/images/ssl/windows/8_windows_successful_cert_install.png
:width: 90%
:alt: Successful cert install
Embassy Local Root CA imported into Certificate folder
#. You can save the settings to the console if desired or cancel.
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <lan-browser>`.

13
site/source/user-manual/connecting/tor-setup/index.rst Normal file
View File

@@ -0,0 +1,13 @@
.. _running-tor:
=========
Tor Setup
=========
Setup :ref:`Tor<tor>` to run on your devices, either natively (in the background), or by configuring an application, such as Firefox.
.. toctree::
:maxdepth: 2
tor-os/index
tor-firefox/index

18
site/source/user-manual/connecting/tor-setup/tor-firefox/index.rst Normal file
View File

@@ -0,0 +1,18 @@
.. _tor-firefox:
=============
Tor - Firefox
=============
.. caution:: This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
Once you have completed native :ref:`Tor Setup<tor-os>`, you can configure Firefox to use the Tor Network. This will allow you to visit both ``.onion`` and "normal" (.com, .net, etc) websites from within the same browser.
.. toctree::
:maxdepth: 2
torff-linux
torff-mac
torff-windows
torff-android
torff-ios

49
site/source/user-manual/connecting/tor-setup/tor-firefox/torff-android.rst Normal file
View File

@@ -0,0 +1,49 @@
.. _torff-android:
=======
Android
=======
.. caution::
This guide assumes you have completed :ref:`setting up Tor for Android<tor-android>`. Please visit this section before proceeding as it is required for Firefox to properly work with Tor.
Once Tor is setup on your system, you can proceed to setup Firefox:
1. Download `Firefox Beta <https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta>`_ from the Play Store, or `Fennec <https://f-droid.org/en/packages/org.mozilla.fennec_fdroid/>`_ from F-Droid.
2. Next, 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>`_.
3. Navigate to ``about:config`` in the Firefox URL bar.
.. figure:: /_static/images/tor/about_config.png
:width: 50%
:alt: Firefox about config
4. 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
5. Search for ``network.proxy.autoconfig_url``, and set the value to ``file:///storage/emulated/0/Download/proxy.pac``.
.. caution:: For some platforms, such as Calyx/Graphene on a Pixel 5/6, it may be necessary to place the file within the application's ``data`` folder, such as ``file:///storage/emulated/0/Android/data/org.mozilla.firefox_beta/files/Download/proxy.pac``. Furthermore, the stock file explorer app may not let you do this, so you might have to get a new one, such as `Explorer <https://play.google.com/store/apps/details?id=com.speedsoftware.explorer&hl=en_US&gl=US>`_. Please reach out to support if you have issues.
.. figure:: /_static/images/tor/autoconfig_url.png
:width: 50%
:alt: Firefox autoconfig url setting screenshot
6. 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
7. 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
8. 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, or other Embassy ``.onion`` addresses, as well as use the :ref:`Bitwarden<vaultwarden>` browser extension.

7
site/source/user-manual/connecting/tor-setup/tor-firefox/torff-ios.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _torff-ios:
===
iOS
===
Unforutnately, it is not currently possible to run Tor natively on iOS. This means that Firefox cannot be configured to use tor. Please see :ref:`iOS Limitations<lim-ios>` for details and workarounds.

51
site/source/user-manual/connecting/tor-setup/tor-firefox/torff-linux.rst Normal file
View File

@@ -0,0 +1,51 @@
.. _torff-linux:
=====
Linux
=====
.. caution::
This guide assumes you have completed :ref:`setting up Tor<running-tor>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
#. Open Firefox and 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: 60%
:alt: Firefox whitelist onions screenshot
#. Download a `Proxy Auto Config` file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file from a terminal, by using:
.. code-block::
sudo wget -P /etc/tor https://registry.start9labs.com/sys/proxy.pac
#. Now, back in your Firefox web browser, select ``Settings`` from the right-hand hamburger menu:
.. figure:: /_static/images/tor/os_ff_settings.png
:width: 30%
:alt: Firefox options screenshot
#. 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: 60%
: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:///etc/tor/proxy.pac
#. Then, check the box labeled ``Proxy DNS when using SOCKS v5``:
.. figure:: /_static/images/tor/firefox_proxy.png
:width: 60%
:alt: Firefox proxy settings screenshot
#. Click ``OK`` and then restart Firefox for the changes to take effect.
#. You're all set! You should now be able to navigate to ``.onion`` URLs in Firefox. This means you can access tor-only service :ref:`WebUIs <web-ui>`, such as Cups Messenger, and use your :ref:`Vaultwarden<vaultwarden>` Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_. You can test this by going to Start9's ``.onion`` homepage, `here <http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion/>`_.

56
site/source/user-manual/connecting/tor-setup/tor-firefox/torff-mac.rst Normal file
View File

@@ -0,0 +1,56 @@
.. _torff-mac:
===
Mac
===
.. caution::
This guide assumes you have completed :ref:`setting up Tor<running-tor>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
#. Open Firefox and 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: 60%
:alt: Firefox whitelist onions screenshot
#. Download a `Proxy Auto Config` file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file by opening the ``Terminal`` App on your Mac. You can find it in your list of Applications. In the terminal, enter:
.. code-block::
brew install wget
And then:
.. code-block::
wget -P /usr/local/etc/tor https://registry.start9labs.com/sys/proxy.pac
#. Now, back in your Firefox web browser, select ``Settings`` from the right-hand hamburger menu:
.. figure:: /_static/images/tor/os_ff_settings.png
:width: 30%
:alt: Firefox options screenshot
#. 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: 60%
: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:///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: 60%
:alt: Firefox proxy settings screenshot
#. Click ``OK`` and then restart Firefox for the changes to take effect.
#. You're all set! You should now be able to navigate to ``.onion`` URLs in Firefox. This means you can access tor-only service :ref:`WebUIs <web-ui>`, such as Cups Messenger, and use your :ref:`Vaultwarden<vaultwarden>` Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_. You can test this by going to Start9's ``.onion`` homepage, `here <http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion/>`_.

53
site/source/user-manual/connecting/tor-setup/tor-firefox/torff-windows.rst Normal file
View File

@@ -0,0 +1,53 @@
.. _torff-windows:
=======
Windows
=======
.. caution:: This guide assumes you have completed :ref:`setting up Tor<running-tor>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
#. Open Firefox and 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: 60%
:alt: Firefox whitelist onions screenshot
#. Download a `Proxy Auto Config` file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file by following instructions below:
- Click `here <https://registry.start9labs.com/sys/proxy.pac>`_ to get the file and save the file somewhere you won’t delete it. Please remember the location you save the file in if you do not use our example location. For this example:
.. code-block::
C:\Program Files\Tor Browser\proxy.pac
#. Now, back in your Firefox web browser, select ``Options`` from the right-hand hamburger menu:
.. figure:: /_static/images/tor/firefox_options_windows.png
:width: 60%
:alt: Firefox options screenshot
#. 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: 60%
: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: 60%
:alt: Firefox proxy settings screenshot
#. Click ``OK`` and then restart Firefox for the changes to take effect.
#. You're all set! You should now be able to navigate to ``.onion`` URLs in Firefox. This means you can access tor-only service :ref:`WebUIs <web-ui>`, such as Cups Messenger, and use your :ref:`Vaultwarden<vaultwarden>` Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_. You can test this by going to Start9's ``.onion`` homepage, `here <http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion/>`__.

16
site/source/user-manual/connecting/tor-setup/tor-os/index.rst Normal file
View File

@@ -0,0 +1,16 @@
.. _tor-os:
============
Tor - Device
============
Select your Operating System to setup Tor to run in the background (natively) of any device that you might want to use to access your Embassy with remotely.
.. toctree::
:maxdepth: 2
tor-linux
tor-mac
tor-windows
tor-android
tor-ios

85
site/source/user-manual/connecting/tor-setup/tor-os/tor-android.rst Normal file
View File

@@ -0,0 +1,85 @@
.. _tor-android:
=======
Android
=======
Some apps, such as :ref:`Tor Browser<tor-browser>`, have Tor built in. They do not require additional software or configurations to utilize Tor. Most apps, however, do not have Tor built in. They require an app called Orbot to be installed in order to utilize the Tor Network.
.. youtube:: b__mVfN-BP8
Running Orbot
-------------
Orbot is a system wide proxy for your Android device that enables communications over Tor.
1. Download and install Orbot from the `Play Store <https://play.google.com/store/apps/details?id=org.torproject.android>`_, or from `F-Droid <https://f-droid.org/packages/org.torproject.android>`_ (must open with F-Droid app).
.. tip:: When using F-Droid, you will want to activate the Guardian Project repository by visiting the ``Settings`` menu (bottom right) -> ``Repositories`` -> ``Guardian Project Official Releases``
2. Launch Orbot.
3. 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
4. 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
5. Go back, and tap start:
.. figure:: /_static/images/tor/orbot_start.png
:width: 50%
:alt: Orbot start
6. Orbot will start up the Tor service. Once complete, you will see:
.. figure:: /_static/images/tor/orbot_started.png
:width: 50%
:alt: Orbot started
7. That's it, you're now running a Tor client on your Android device! Certain apps, such as Firefox, Fennec, and DuckDuckGo will now just work. Other apps, however, require that Orbot be running VPN mode.
Orbot VPN mode
--------------
To utilize Tor, some apps require that Orbot be running in VPN mode. This means that you are sending your application's traffic across the Tor network via Orbot.
1. Disable Private DNS on your device. Note: This is not necessary if running GrapheneOS. To do edit Private DNS, 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"
2. Launch Orbot and toggle VPN Mode on:
.. figure:: /_static/images/tor/orbot_vpn.png
:width: 50%
:alt: Orbot vpn mode
Toggle VPN Mode to "on"
Under `Tor-Enabled Apps`, click the gear icon and add apps you want to utilize Tor.
.. figure:: /_static/images/tor/orbot_apps.png
:width: 50%
:alt: Orbot apps
Examples of applications that need this feature are:
- Bitwarden
- Element (Matrix)
You can also add the following browsers to the Tor-Enabled Apps list to easily access Tor addresses (`.onion` URLs):
- Chrome
- Vanadium

7
site/source/user-manual/connecting/tor-setup/tor-os/tor-ios.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _tor-ios:
===
iOS
===
Unforutnately, it is not currently possible to run Tor natively on iOS. Please see :ref:`iOS Limitations<lim-ios>` for details and workarounds.

87
site/source/user-manual/connecting/tor-setup/tor-os/tor-linux.rst Normal file
View File

@@ -0,0 +1,87 @@
.. _tor-linux:
=====
Linux
=====
.. tabs::
.. group-tab:: Debian / Ubuntu
For Debian and Debian-based systems, such as Mint, PopOS etc.
.. note:: The following install is for the LTS (Long Term Support) version of Tor from Debian. If you would like the latest stable release, The Tor Project maintain their own Debian repository. The instructions to connect to this can be found `here <https://support.torproject.org/apt/tor-deb-repo/>`_.
Install the Tor proxy service to your system. To do so, open your terminal and run the following command:
.. code-block:: bash
sudo apt update && sudo apt install tor
.. tip:: You can check that Tor is running with:
.. code-block:: bash
systemctl status tor
In the rare event that Tor is having connectivity issues, you can reset your connection with:
.. code-block:: bash
sudo systemctl restart tor
.. group-tab:: Arch / Garuda / Manjaro
Simply install Tor with:
.. code-block:: bash
sudo pacman -S tor
.. tip:: You can check that Tor is running with:
.. code-block:: bash
systemctl status tor
In the rare event that Tor is having connectivity issues, you can reset your connection with:
.. code-block:: bash
sudo systemctl restart tor
.. group-tab:: CentOS / RHEL / Fedora
#. Configure the Tor Package repository. Add the following to ``/etc/yum.repos.d/tor.repo``:
- CentOS / RHEL:
.. code-block:: bash
[Tor]
name=Tor for Enterprise Linux $releasever - $basearch
baseurl=https://rpm.torproject.org/centos/$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://rpm.torproject.org/centos/public_gpg.key
cost=100
- Fedora:
.. code-block:: bash
[Tor]
name=Tor for Fedora $releasever - $basearch
baseurl=https://rpm.torproject.org/fedora/$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://rpm.torproject.org/fedora/public_gpg.key
cost=100
#. Then install the Tor package:
.. code-block:: bash
sudo dnf install tor

59
site/source/user-manual/connecting/tor-setup/tor-os/tor-mac.rst Normal file
View File

@@ -0,0 +1,59 @@
.. _tor-mac:
===
Mac
===
Install Homebrew
----------------
#. If you do not have Homebrew installed, follow the installation instructions `here <https://brew.sh/>`_. TLDR: Open the Terminal and paste the following line:
.. code-block::
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
.. note:: On new (M1) Macs, you might need to be root for this in which case add ``sudo`` at the front of the command, with a space before ``/bin/bash``
#. You will be prompted for your system password before installation; proceed with entering your password. You may be asked more than once.
.. figure:: /_static/images/tor/install_homebrew.png
:width: 80%
:alt: Homebrew installation
#. You will be notified which directories Homebrew is going to create, hit :code:`RETURN`:
.. figure:: /_static/images/tor/install_homebrew1.png
:width: 80%
:alt: Homebrew installation
Homebrew creates the directories and downloads any other files it needs e.g. “Command Line Tool for Xcode” and “Homebrew”.
Wait a few minutes while it downloads and installs what it needs.
.. warning:: Surprisingly, Homebrew uses Google Analytics to collect anonymous usage data. You can deselect the option to share usage data by `opting out <https://docs.brew.sh/Analytics#opting-out>`_.
Install Tor
-----------
.. caution:: If you have the Tor Browser open, close it and quit the application.
#. In the command line, install Tor:
.. code-block::
brew install tor
Once it is finished you have the following options:
.. figure:: /_static/images/tor/install_tor.png
:width: 80%
:alt: Tor installation
#. Then run Tor with:
.. code-block::
brew services start tor
This will start Tor and ensure that it is always running, even after a restart. See the `Tor Project docs <https://2019.www.torproject.org/docs/tor-doc-osx.html.en>`_ for more details.

61
site/source/user-manual/connecting/tor-setup/tor-os/tor-windows.rst Normal file
View File

@@ -0,0 +1,61 @@
.. _tor-windows:
=======
Windows
=======
#. Unfortunately, `The Tor Project <https://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 (from above) in place of ``<PATH TO>``:
.. code-block::
sc create tor start= auto binPath= "<PATH TO>\Browser\TorBrowser\Tor\tor.exe -nt-service"
.. tip:: If you get the error "Access denied," please ensure you are running the command prompt in Administrator mode. You can tell because the prompt will show C:\\Users\\YOUR-USERNAME> if you are NOT in admin mode, and it will show C:\\WINDOWS\\system32 if you ARE in admin mode.
.. code-block::
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
.. note:: If you get the error "The specified service already exists," complete the following steps:
1. Run the command:
.. code-block::
sc delete tor
2. Uninstall the Tor Browser, following `these steps <https://tb-manual.torproject.org/uninstalling/>`_.
3. Begin this guide again from the beginning.
#. That's it! Your Windows computer is now setup to natively use Tor.