mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-30 12:11:57 +00:00
fix up navigation
This commit is contained in:
Lucy Cifferello
@@ -1,8 +1,13 @@
|
||||
**************
|
||||
Config Options
|
||||
**************
|
||||
.. _basic-config:
|
||||
|
||||
Click "Config". Here you can set custom configurations for your Embassy. Currently, you can change the "Device Name" and enable/disable "Auto Check for Updates."
|
||||
===================
|
||||
Basic Configuration - ***NEEDS UPDATE / SCREENS***
|
||||
===================
|
||||
|
||||
Set Device Name
|
||||
---------------
|
||||
|
||||
Here you can change the name of your Embassy!
|
||||
|
||||
.. figure:: /_static/images/embassy_config.png
|
||||
:width: 90%
|
||||
14
site/source/user-manual/configuration/index.rst
Normal file
14
site/source/user-manual/configuration/index.rst
Normal file
@@ -0,0 +1,14 @@
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Configuration, setup guides, and known limitations are provided here by device
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
basic-config
|
||||
tor-setup/index
|
||||
lan-setup/index
|
||||
wifi
|
||||
limitations/index
|
||||
16
site/source/user-manual/configuration/lan-setup/index.rst
Normal file
16
site/source/user-manual/configuration/lan-setup/index.rst
Normal file
@@ -0,0 +1,16 @@
|
||||
.. _lan-setup:
|
||||
|
||||
============
|
||||
Local Access
|
||||
============
|
||||
|
||||
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
|
||||
@@ -1,14 +1,8 @@
|
||||
******
|
||||
Mobile
|
||||
******
|
||||
|
||||
Android
|
||||
=======
|
||||
|
||||
Unfortunately, LAN addresses (URLs ending in `.local`) are not supported on Android devices. This is because Android does not yet natively support mDNS, which is used to access LAN addresses on mobile device browsers. As a result, you cannot access your Embassy's or service's LAN address from the browser on Android. We are tracking this issue `here <https://issuetracker.google.com/issues/140786115>`_, please star it to get more attention from the development team!
|
||||
.. _lan-ios:
|
||||
|
||||
===
|
||||
iOS
|
||||
====
|
||||
===
|
||||
|
||||
#. Navigate back to the `Start9 Setup App <https://apps.apple.com/us/app/start9-setup-app/id1528125889>`_.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
.. _lan-linux:
|
||||
|
||||
=====
|
||||
Linux
|
||||
=====
|
||||
|
||||
Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.
|
||||
|
||||
#. Visit your Embassy at its Tor Address.
|
||||
|
||||
#. Navigate to --> Embassy --> Connect Over LAN
|
||||
|
||||
.. figure:: /_static/images/embassy_lan_setup.png
|
||||
:width: 90%
|
||||
:alt: LAN setup menu item
|
||||
|
||||
Select the "Connect over LAN" menu item
|
||||
|
||||
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
|
||||
|
||||
.. figure:: /_static/images/secure_lan_setup_page.png
|
||||
:width: 90%
|
||||
:alt: LAN setup page
|
||||
|
||||
Select the "Root Certificate Authority" sub menu
|
||||
|
||||
Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
|
||||
65
site/source/user-manual/configuration/lan-setup/lan-mac.rst
Normal file
65
site/source/user-manual/configuration/lan-setup/lan-mac.rst
Normal file
@@ -0,0 +1,65 @@
|
||||
.. _lan-mac:
|
||||
|
||||
===
|
||||
Mac
|
||||
===
|
||||
|
||||
#. Visit your Embassy at its Tor Address.
|
||||
|
||||
#. Navigate to --> Embassy --> Connect Over LAN
|
||||
|
||||
.. figure:: /_static/images/embassy_lan_setup.png
|
||||
:width: 90%
|
||||
:alt: LAN setup menu item
|
||||
|
||||
Select the "Connect over LAN" menu item
|
||||
|
||||
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
|
||||
|
||||
.. figure:: /_static/images/secure_lan_setup_page.png
|
||||
:width: 90%
|
||||
:alt: LAN setup page
|
||||
|
||||
Select the "Root Certificate Authority" sub menu
|
||||
|
||||
#. Select the option to open your key with Keychain Access. If you choose to save file, double click on it once downloaded.
|
||||
|
||||
.. figure:: /_static/images/secure_lan_setup_prompt.png
|
||||
:width: 90%
|
||||
:alt: LAN setup prompt
|
||||
|
||||
Open with "Keychain Access" and select "OK"
|
||||
|
||||
#. Enter your computer password when prompted. It will be imported into your computer’s keychain.
|
||||
|
||||
.. figure:: /_static/images/ssl/macos/certificate_untrusted.png
|
||||
:width: 90%
|
||||
:alt: Keychain access import menu
|
||||
|
||||
Keychain access import menu
|
||||
|
||||
#. 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 and find the certificate entitled “Embassy Local Root CA”.
|
||||
|
||||
#. 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: 90%
|
||||
:alt: Keychain submenu
|
||||
|
||||
Select "Always trust" under SSL 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: 90%
|
||||
:alt: Keychain menu trusted certificate
|
||||
|
||||
Trusted Embassy Local CA certificate
|
||||
|
||||
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
|
||||
@@ -1,73 +1,8 @@
|
||||
.. _computer-setup:
|
||||
|
||||
Computer Setup
|
||||
==============
|
||||
|
||||
MacOS
|
||||
-----
|
||||
|
||||
#. Visit your Embassy at its Tor Address.
|
||||
|
||||
#. Navigate to --> Embassy --> Connect Over LAN
|
||||
|
||||
.. figure:: /_static/images/embassy_lan_setup.png
|
||||
:width: 90%
|
||||
:alt: LAN setup menu item
|
||||
|
||||
Select the "Connect over LAN" menu item
|
||||
|
||||
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
|
||||
|
||||
.. figure:: /_static/images/secure_lan_setup_page.png
|
||||
:width: 90%
|
||||
:alt: LAN setup page
|
||||
|
||||
Select the "Root Certificate Authority" sub menu
|
||||
|
||||
#. Select the option to open your key with Keychain Access. If you choose to save file, double click on it once downloaded.
|
||||
|
||||
.. figure:: /_static/images/secure_lan_setup_prompt.png
|
||||
:width: 90%
|
||||
:alt: LAN setup prompt
|
||||
|
||||
Open with "Keychain Access" and select "OK"
|
||||
|
||||
#. Enter your computer password when prompted. It will be imported into your computer’s keychain.
|
||||
|
||||
.. figure:: /_static/images/ssl/macos/certificate_untrusted.png
|
||||
:width: 90%
|
||||
:alt: Keychain access import menu
|
||||
|
||||
Keychain access import menu
|
||||
|
||||
#. 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 and find the certificate entitled “Embassy Local Root CA”.
|
||||
|
||||
#. 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: 90%
|
||||
:alt: Keychain submenu
|
||||
|
||||
Select "Always trust" under SSL 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: 90%
|
||||
:alt: Keychain menu trusted certificate
|
||||
|
||||
Trusted Embassy Local CA certificate
|
||||
|
||||
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
|
||||
.. _lan-windows:
|
||||
|
||||
=======
|
||||
Windows
|
||||
-------
|
||||
=======
|
||||
|
||||
#. Install `Bonjour Print Services <https://support.apple.com/kb/DL999>`_ on your Windows machine. This is necessary in order to visit .local addresses on Windows.
|
||||
#. If you are having issues running Bonjour after installing, you might have had Bonjour previously installed. To fix:
|
||||
@@ -179,29 +114,3 @@ Windows
|
||||
#. 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 <browser-setup>`.
|
||||
|
||||
|
||||
Linux
|
||||
-----
|
||||
|
||||
Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.
|
||||
|
||||
#. Visit your Embassy at its Tor Address.
|
||||
|
||||
#. Navigate to --> Embassy --> Connect Over LAN
|
||||
|
||||
.. figure:: /_static/images/embassy_lan_setup.png
|
||||
:width: 90%
|
||||
:alt: LAN setup menu item
|
||||
|
||||
Select the "Connect over LAN" menu item
|
||||
|
||||
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
|
||||
|
||||
.. figure:: /_static/images/secure_lan_setup_page.png
|
||||
:width: 90%
|
||||
:alt: LAN setup page
|
||||
|
||||
Select the "Root Certificate Authority" sub menu
|
||||
|
||||
Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
|
||||
16
site/source/user-manual/configuration/limitations/index.rst
Normal file
16
site/source/user-manual/configuration/limitations/index.rst
Normal file
@@ -0,0 +1,16 @@
|
||||
.. _limitations:
|
||||
|
||||
=================
|
||||
Known Limitations
|
||||
=================
|
||||
|
||||
The following pages describe functionality that is known to be missing from certain platforms. Please bother the appropriate company or developers until they have been remedied.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
lim-linux
|
||||
lim-mac
|
||||
lim-windows
|
||||
lim-android
|
||||
lim-ios
|
||||
@@ -0,0 +1,13 @@
|
||||
.. _lim-android:
|
||||
|
||||
=========================
|
||||
Android Known Limitations
|
||||
=========================
|
||||
|
||||
Local Access
|
||||
------------
|
||||
Android does not have native support for :ref:`mDNS<mdns>` and therefore cannot resolve ``.local`` addresses. This issue has been long known by Google, and can be tracked `here <https://issuetracker.google.com/issues/140786115>`_ (Google account required to view).
|
||||
|
||||
Workarounds
|
||||
...........
|
||||
An app developer can add mDNS support, and some projects, such as Chromium, have long `considered it <https://bugs.chromium.org/p/chromium/issues/detail?id=405925>`_, but the real solution is for support to occur at the OS level.
|
||||
@@ -0,0 +1,21 @@
|
||||
.. _lim-ios:
|
||||
|
||||
=====================
|
||||
iOS Known Limitations
|
||||
=====================
|
||||
|
||||
Tor
|
||||
---
|
||||
It is not currently possible to run Tor natively (in the background) on iOS. The best chance for this functionality coming to iOS is via the `iCepa Project <https://github.com/iCepa>`_.
|
||||
|
||||
Workarounds
|
||||
...........
|
||||
The only way to use Tor on iOS is with apps that come with Tor built-in, such as :ref:`Zap Wallet <zap>`.
|
||||
|
||||
Matrix
|
||||
------
|
||||
The lack of Tor support on iOS means that Element/Matrix cannot be run on an iPhone in conjunction with your Embassy Matrix server, as that currently requires a Tor connection. This will be fixed if `Element <https://github.com/vector-im/element-ios>` builds Tor into their app.
|
||||
|
||||
Workarounds
|
||||
...........
|
||||
None currently known.
|
||||
@@ -0,0 +1,7 @@
|
||||
.. _lim-linux:
|
||||
|
||||
=======================
|
||||
Linux Known Limitations
|
||||
=======================
|
||||
|
||||
Linux has no known limitations in regard to Embassy. Congratulations, Master Race...
|
||||
@@ -0,0 +1,7 @@
|
||||
.. _lim-mac:
|
||||
|
||||
=====================
|
||||
Mac Known Limitations
|
||||
=====================
|
||||
|
||||
MacOS has no known limitations in regard to Embassy.
|
||||
@@ -0,0 +1,5 @@
|
||||
.. _lim-windows:
|
||||
|
||||
=========================
|
||||
Windows Known Limitations
|
||||
=========================
|
||||
11
site/source/user-manual/configuration/tor-setup/index.rst
Normal file
11
site/source/user-manual/configuration/tor-setup/index.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
=========
|
||||
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
|
||||
@@ -0,0 +1,18 @@
|
||||
.. _tor-firefox:
|
||||
|
||||
====================
|
||||
Using Tor on 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 :ref:`Firefox<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
|
||||
@@ -0,0 +1,47 @@
|
||||
.. _torff-android:
|
||||
|
||||
=======
|
||||
Android - ***NEEDS UPDATED***
|
||||
=======
|
||||
|
||||
.. warning::
|
||||
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``.
|
||||
|
||||
.. 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, 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.
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
.. _torff-ios:
|
||||
|
||||
===
|
||||
iOS -***NEEDS UPDATED***
|
||||
===
|
||||
|
||||
NO TOR FOR YOU
|
||||
|
||||
.. _firefox-tor-ios:
|
||||
|
||||
**********************************
|
||||
Setting up Firefox with Tor on iOS
|
||||
**********************************
|
||||
|
||||
Unfortunately, Apple does not allow tor to be run natively on iOS. This means that Firefox cannot be configured to use tor. This leaves the following options for iOS users:
|
||||
|
||||
You can use Start9's own Consulate Browser, which is available `here <https://apps.apple.com/us/app/start9-consulate-browser/id1528124570>`_, or you can select another Tor Browser by searching the `App Store <https://www.apple.com/us/search/onion-browser?src=serp>`_.
|
||||
@@ -0,0 +1,95 @@
|
||||
.. _torff-linux:
|
||||
|
||||
=====
|
||||
Linux - ***NEEDS UPDATED***
|
||||
=====
|
||||
|
||||
|
||||
.. warning::
|
||||
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.
|
||||
|
||||
1. Open Firefox.
|
||||
|
||||
2. Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
|
||||
|
||||
3. 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
|
||||
|
||||
4. 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 the OS-specific instructions below:
|
||||
Windows:
|
||||
|
||||
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
|
||||
|
||||
Mac:
|
||||
|
||||
Open 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
|
||||
|
||||
Linux:
|
||||
|
||||
From a terminal, enter:
|
||||
|
||||
.. code-block::
|
||||
|
||||
sudo wget -P /etc/tor https://registry.start9labs.com/sys/proxy.pac
|
||||
|
||||
|
||||
5. Now open your Firefox web browser, and select options (Windows), or preferences (Mac/Linux):
|
||||
|
||||
.. figure:: /_static/images/tor/firefox_options_windows.png
|
||||
:width: 80%
|
||||
:alt: Firefox options screenshot
|
||||
|
||||
Select :menuselection:``Settings --> Options``
|
||||
|
||||
|
||||
6. 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
|
||||
|
||||
7. 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:
|
||||
Windows:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file://C:/Program Files/Tor Browser/proxy.pac
|
||||
|
||||
Mac:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file:///usr/local/etc/tor/proxy.pac
|
||||
|
||||
Linux:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file:///etc/tor/proxy.pac
|
||||
|
||||
8. 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
|
||||
|
||||
9. Click ``OK`` and then restart Firefox for the changes to take effect.
|
||||
|
||||
10. 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/>`_.
|
||||
@@ -0,0 +1,95 @@
|
||||
.. _torff-mac:
|
||||
|
||||
===
|
||||
Mac - ***NEEDS UPDATED***
|
||||
===
|
||||
|
||||
|
||||
.. warning::
|
||||
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.
|
||||
|
||||
1. Open Firefox.
|
||||
|
||||
2. Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
|
||||
|
||||
3. 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
|
||||
|
||||
4. 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 the OS-specific instructions below:
|
||||
Windows:
|
||||
|
||||
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
|
||||
|
||||
Mac:
|
||||
|
||||
Open 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
|
||||
|
||||
Linux:
|
||||
|
||||
From a terminal, enter:
|
||||
|
||||
.. code-block::
|
||||
|
||||
sudo wget -P /etc/tor https://registry.start9labs.com/sys/proxy.pac
|
||||
|
||||
|
||||
5. Now open your Firefox web browser, and select options (Windows), or preferences (Mac/Linux):
|
||||
|
||||
.. figure:: /_static/images/tor/firefox_options_windows.png
|
||||
:width: 80%
|
||||
:alt: Firefox options screenshot
|
||||
|
||||
Select :menuselection:``Settings --> Options``
|
||||
|
||||
|
||||
6. 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
|
||||
|
||||
7. 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:
|
||||
Windows:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file://C:/Program Files/Tor Browser/proxy.pac
|
||||
|
||||
Mac:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file:///usr/local/etc/tor/proxy.pac
|
||||
|
||||
Linux:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file:///etc/tor/proxy.pac
|
||||
|
||||
8. 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
|
||||
|
||||
9. Click ``OK`` and then restart Firefox for the changes to take effect.
|
||||
|
||||
10. 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/>`_.
|
||||
@@ -0,0 +1,96 @@
|
||||
.. _torff-windows:
|
||||
|
||||
=======
|
||||
Windows - *** NEEDS UPDATED***
|
||||
=======
|
||||
|
||||
|
||||
.. warning::
|
||||
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.
|
||||
|
||||
1. Open Firefox.
|
||||
|
||||
2. Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
|
||||
|
||||
3. 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
|
||||
|
||||
4. 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 the OS-specific instructions below:
|
||||
Windows:
|
||||
|
||||
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
|
||||
|
||||
Mac:
|
||||
|
||||
Open 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
|
||||
|
||||
Linux:
|
||||
|
||||
From a terminal, enter:
|
||||
|
||||
.. code-block::
|
||||
|
||||
sudo wget -P /etc/tor https://registry.start9labs.com/sys/proxy.pac
|
||||
|
||||
|
||||
5. Now open your Firefox web browser, and select options (Windows), or preferences (Mac/Linux):
|
||||
|
||||
.. figure:: /_static/images/tor/firefox_options_windows.png
|
||||
:width: 80%
|
||||
:alt: Firefox options screenshot
|
||||
|
||||
Select :menuselection:``Settings --> Options``
|
||||
|
||||
|
||||
6. 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
|
||||
|
||||
7. 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:
|
||||
Windows:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file://C:/Program Files/Tor Browser/proxy.pac
|
||||
|
||||
Mac:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file:///usr/local/etc/tor/proxy.pac
|
||||
|
||||
Linux:
|
||||
|
||||
.. code-block::
|
||||
|
||||
file:///etc/tor/proxy.pac
|
||||
|
||||
8. 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
|
||||
|
||||
9. Click ``OK`` and then restart Firefox for the changes to take effect.
|
||||
|
||||
10. 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/>`_.
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
.. _tor-os:
|
||||
|
||||
==================
|
||||
Using Tor Natively
|
||||
==================
|
||||
|
||||
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
|
||||
@@ -0,0 +1,83 @@
|
||||
.. _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 or Graphene device that enables communications over Tor.
|
||||
|
||||
1. Download 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>`_.
|
||||
|
||||
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. Certain apps, such as Firefox or DuckDuckGo will now just work. Other apps, however, require that Orbot be running VPN mode.
|
||||
|
||||
Orbot VPN mode
|
||||
--------------
|
||||
|
||||
To utilize Tor, most apps require that Orbot be running in VPN mode.
|
||||
|
||||
1. 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"
|
||||
|
||||
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
|
||||
- Zeus
|
||||
|
||||
You can also add the following browsers to the Tor-Enabled Apps list to easily access Tor addresses (`.onion` URLs):
|
||||
|
||||
- Chrome
|
||||
- Firefox
|
||||
@@ -0,0 +1,7 @@
|
||||
.. _tor-ios:
|
||||
|
||||
===
|
||||
iOS
|
||||
===
|
||||
|
||||
No Tor for you
|
||||
@@ -0,0 +1,25 @@
|
||||
.. _tor-linux:
|
||||
|
||||
=====
|
||||
Linux
|
||||
=====
|
||||
|
||||
Debian / Ubuntu
|
||||
---------------
|
||||
|
||||
For Debian and Debian-based systems, such as Mint, PopOS etc.
|
||||
|
||||
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
|
||||
|
||||
Arch
|
||||
----
|
||||
|
||||
Simply install Tor with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo pacman -S tor
|
||||
@@ -0,0 +1,98 @@
|
||||
.. _tor-mac:
|
||||
|
||||
===
|
||||
Mac - ***SIMPLIFY M1 INSTRUCTION***
|
||||
===
|
||||
|
||||
For macOS running on ARM chips (ie. newer macs):
|
||||
================================================
|
||||
|
||||
Install Homebrew
|
||||
----------------
|
||||
|
||||
.. warning:: macOS Homebrew running natively on M1/Apple Silicon/ARM has partial functionality. Therefore, some additional steps are needed to setup Homebrew.
|
||||
|
||||
#. Open a command line editor (Terminal), and run the following commands:
|
||||
|
||||
.. code-block::
|
||||
|
||||
softwareupdate --install-rosetta
|
||||
arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
|
||||
|
||||
Install Tor
|
||||
-----------
|
||||
|
||||
.. warning:: If you have the Tor Browser open, close it and quit the application.
|
||||
|
||||
#. In the command line, install Tor:
|
||||
|
||||
.. code-block::
|
||||
|
||||
arch -x86_64 brew install tor
|
||||
|
||||
#. Then start Tor:
|
||||
|
||||
.. code-block::
|
||||
|
||||
arch -x86_64 brew services start tor
|
||||
|
||||
This will start Tor and ensure that it is always running, even after a restart. See the `Tor Project <https://2019.www.torproject.org/docs/tor-doc-osx.html.en>`_ for more details.
|
||||
|
||||
For macOS Big Sur/Catalina:
|
||||
===========================
|
||||
|
||||
Install Homebrew
|
||||
----------------
|
||||
|
||||
1. If you do not have Homebrew installed, follow the installation instructions `here <https://brew.sh/>`_.
|
||||
|
||||
TLDR: Open the command line editor (Terminal) and paste the following line:
|
||||
|
||||
.. code-block::
|
||||
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
|
||||
|
||||
2. You will be prompted for your system password before installation; proceed with entering your password:
|
||||
|
||||
.. figure:: /_static/images/tor/install_homebrew.png
|
||||
:width: 80%
|
||||
:alt: Homebrew installation
|
||||
|
||||
Enter your password
|
||||
|
||||
3. 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
|
||||
-----------
|
||||
|
||||
.. warning:: 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 <https://2019.www.torproject.org/docs/tor-doc-osx.html.en>`_ for more details.
|
||||
@@ -0,0 +1,62 @@
|
||||
.. _tor-windows:
|
||||
|
||||
=======
|
||||
Windows
|
||||
=======
|
||||
|
||||
#. 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 (from above) in place of ``<PATH TO>``:
|
||||
|
||||
.. code-block::
|
||||
|
||||
sc create tor start= auto binPath= "<PATH TO>\Browser\TorBrowser\Tor\tor.exe -nt-service"
|
||||
|
||||
.. code-block::
|
||||
|
||||
sc start tor
|
||||
|
||||
.. 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.
|
||||
|
||||
.. note:: If you get the error "The specified service already exists," complete the following steps:
|
||||
|
||||
1. Run the command:
|
||||
|
||||
.. code-block::
|
||||
|
||||
sc delete tor
|
||||
|
||||
1. Uninstall the Tor Browser, following `these steps <https://tb-manual.torproject.org/uninstalling/>`_.
|
||||
2. Begin this guide again from the beginning.
|
||||
|
||||
#. 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.
|
||||
@@ -1,8 +1,10 @@
|
||||
***************
|
||||
Setting up WiFi
|
||||
***************
|
||||
.. _wifi:
|
||||
|
||||
#. Click "WiFi".
|
||||
===============
|
||||
Setting up WiFi - ***UPDATE SCREENS***
|
||||
===============
|
||||
|
||||
#. On the Embassy Tab, Under "Settings", Click "WiFi".
|
||||
#. Click the ``+`` button in the lower right corner.
|
||||
#. Select the appropriate country.
|
||||
#. Enter your WiFi SSID and password.
|
||||
@@ -16,4 +18,4 @@ Setting up WiFi
|
||||
#. Save
|
||||
* Clicking *Add* will save the network credentials but not try to connect immediately. This is useful, for example, if you are connected over Ethernet at home and want to add your office WiFi credentials.
|
||||
* `Add and Connect`.
|
||||
#. The saved network will appear in the list when successfully added. If you are successfully connected, the WiFi symbol will be green, at which point, you can safely disconnect the Embassy from your router.
|
||||
#. The saved network will appear in the list when successfully added. If you are successfully connected, the WiFi symbol will be green, at which point, you can safely disconnect the Embassy from your router.
|
||||
@@ -1,40 +0,0 @@
|
||||
.. _connecting:
|
||||
|
||||
**********
|
||||
Connecting
|
||||
**********
|
||||
|
||||
With the :ref:`initial-setup` complete, your Embassy is now privately hosted on the Internet and can be accessed right from a web browser. Your Embassy's addresses (its Tor and LAN URLs) are completely private; no one else even knows they exist.
|
||||
|
||||
If you accidentally leak your Embassy's addresses, do not worry. You Embassy is also protected by your password; so only you can log in.
|
||||
|
||||
|
||||
Tor
|
||||
===
|
||||
|
||||
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.
|
||||
|
||||
Below are a list of our recommended browsers for Tor:
|
||||
|
||||
* `Start9 Consulate <https://apps.apple.com/us/app/consulate/id1528124570>`_ (iOS)
|
||||
* `Firefox <https://mozilla.org/firefox/new/>`_ (Mac, Windows, Linux)
|
||||
* `Firefox Beta <https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta>`_ (Android)
|
||||
* `Tor Browser <https://torproject.org/download/>`_ (Mac, Windows, Linux, Android)
|
||||
* `Brave <https://brave.com/>`_ (Mac, Windows, Linux)
|
||||
|
||||
.. 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
|
||||
===
|
||||
|
||||
Connecting to your Embassy over :ref:`lan` has the benefit of being fast! It requires that your are connected to your home network and using a browser that supports *.local* URLs, which is true for most browsers.
|
||||
|
||||
.. seealso:: :ref:`Installing and trusting your Embassy's Root Certificate Authority SSL<ssl-setup>`
|
||||
@@ -1,9 +0,0 @@
|
||||
*****************
|
||||
Developer Options
|
||||
*****************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ssh-setup
|
||||
alt-marketplace
|
||||
@@ -1,17 +0,0 @@
|
||||
*******
|
||||
General
|
||||
*******
|
||||
|
||||
An overview of EmbassyOS general capabilities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
embassy-config
|
||||
updating
|
||||
wifi
|
||||
developer-options/index
|
||||
power
|
||||
notifications
|
||||
lan-setup/index
|
||||
forgot-password
|
||||
@@ -1,104 +0,0 @@
|
||||
.. _browser-setup:
|
||||
|
||||
Browser Setup
|
||||
=============
|
||||
|
||||
.. warning:: Make sure you have completed your :ref:`computer setup <computer-setup>` before continuing!
|
||||
|
||||
Select the browser you would like to configure to import the certificate from your desktop:
|
||||
|
||||
.. .. toctree::
|
||||
.. :hidden:
|
||||
|
||||
.. browser
|
||||
|
||||
- :ref:`Brave <brave>`
|
||||
- :ref:`Chrome <chrome>`
|
||||
- :ref:`Firefox <firefox>`
|
||||
- :ref:`Safari <safari>`
|
||||
|
||||
.. _brave:
|
||||
|
||||
Brave
|
||||
-----
|
||||
|
||||
#. Navigate to your Brave Settings in a new tab.
|
||||
|
||||
#. On the left hand sidebar, navigate to *Additional Settings > Privacy and Security*.
|
||||
|
||||
#. Add the bottom of the section, select "Manage Certificates".
|
||||
|
||||
.. figure:: /_static/images/ssl/browser/brave_security_settings.png
|
||||
:width: 90%
|
||||
:alt: Brave privacy and security settings page
|
||||
|
||||
#. If you see a trusted “Embassy Local Root CA”, open a new tab to apply the certificate. If this does not work, quit and restart Brave.
|
||||
|
||||
#. If you do not see a trusted “Embassy Local Root CA” certificate in the list, ensure the certificate is properly set up on your computer system.
|
||||
|
||||
.. figure:: /_static/images/ssl/browser/brave_view_certs.png
|
||||
:width: 90%
|
||||
:alt: Brave Manage Certificates sub-menu on MacOS
|
||||
|
||||
#. Obtain the LAN address provided in the Setup App and enter it in a new tab.
|
||||
|
||||
#. You can now securely navigate to your Embassy over HTTPS!
|
||||
|
||||
#. 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).
|
||||
|
||||
.. _chrome:
|
||||
|
||||
Chrome
|
||||
------
|
||||
|
||||
#. Once you have followed the steps to setup your device, open a new tab to apply the certificate. If this does not work, quit and restart Chrome.
|
||||
|
||||
#. Obtain the LAN address provided in the Setup App and enter it in the URL bar.
|
||||
|
||||
#. You can now securely navigate to your Embassy over HTTPS!
|
||||
|
||||
.. _firefox:
|
||||
|
||||
Firefox
|
||||
-------
|
||||
|
||||
#. Navigate to your Firefox Settings in a new tab.
|
||||
|
||||
#. 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: 90%
|
||||
: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 <ssl-setup>`.
|
||||
|
||||
#. When prompted, check “Trust this CA to identity websites” and select “OK”.
|
||||
|
||||
.. figure:: /_static/images/ssl/browser/firefox_security_settings.png
|
||||
:width: 90%
|
||||
:alt: Firefox import cert
|
||||
|
||||
Firefox import certificate page
|
||||
|
||||
#. Ensure the “Embassy Local Root CA” exists under “Start9 Labs”.
|
||||
|
||||
#. 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 in the Setup App.
|
||||
|
||||
#. You can now securely navigate to your Embassy over HTTPS!
|
||||
|
||||
.. _safari:
|
||||
|
||||
Safari
|
||||
------
|
||||
|
||||
Once you have completed the steps to install a SSL certificate 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!
|
||||
@@ -1,11 +0,0 @@
|
||||
*******
|
||||
Desktop
|
||||
*******
|
||||
|
||||
Enabling LAN connectivity for desktop involves configuring both your computer and your browser.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Computer Setup<computer-setup>
|
||||
Browser Setup<browser-setup>
|
||||
@@ -1,15 +0,0 @@
|
||||
.. _ssl-setup:
|
||||
|
||||
*********
|
||||
LAN Setup
|
||||
*********
|
||||
|
||||
You can securely access your Embassy over LAN while connected to the same network. This method of communicating with your Embassy is significantly faster than Tor, and it also serves as a fallback in case the Tor network is experiencing connectivity issues.
|
||||
|
||||
The guides below will walk you through the steps to install and trust your Embassy's SSL certificate, such that your communications are encrypted over HTTPS.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Desktop<desktop>
|
||||
Mobile<mobile>
|
||||
@@ -1,24 +0,0 @@
|
||||
*************
|
||||
Notifications
|
||||
*************
|
||||
|
||||
You can view and manage your Notifications inside the "Notifications" tab in the main menu. They include:
|
||||
|
||||
* successful or failed EmbassyOS updates
|
||||
* successful or failed service installations
|
||||
* successful or failed service backups
|
||||
* successful or failed service updates
|
||||
|
||||
To delete a notification, slide the notification to the left and click the *trash* icon.
|
||||
|
||||
.. figure:: /_static/images/embassy_notifications.png
|
||||
:width: 90%
|
||||
:alt: Embassy Notifications
|
||||
|
||||
All notifications View
|
||||
|
||||
.. figure:: /_static/images/embassy_notification.png
|
||||
:width: 90%
|
||||
:alt: Embassy notification alert
|
||||
|
||||
Example notification alerts
|
||||
@@ -1,18 +0,0 @@
|
||||
*****
|
||||
Power
|
||||
*****
|
||||
|
||||
Restart
|
||||
=======
|
||||
|
||||
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
|
||||
#. A gentle *bep* will sound when the Embassy is powered back on.
|
||||
#. A *chime* will sound when the Embassy is ready to use.
|
||||
|
||||
Shutdown
|
||||
========
|
||||
|
||||
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
|
||||
#. It is now safe to unplug the Embassy from power and the ethernet cable, if connected.
|
||||
|
||||
.. note:: After a shutdown, the *only* way to turn your Embassy back on is to unplug it and plug it back in. As such, we do not recommend shutting down your Embassy when you are not physically near it. Instead, you should use the restart option.
|
||||
@@ -1,11 +0,0 @@
|
||||
******************
|
||||
Updating EmbassyOS
|
||||
******************
|
||||
|
||||
#. Navigate to ``Menu > Embassy``
|
||||
#. Click "Check for Updates"
|
||||
#. If there is an update available, you will be prompted to install it.
|
||||
#. While updating, your Embassy will emit a gentle chime every 20 seconds.
|
||||
#. You can also enable automatic check for updates in the :ref:`Embassy config <auto-update>` tab.
|
||||
|
||||
.. note:: Ensure you have a stable Internet connection, and do not unplug your Embassy during an update. Updates usually complete within a few minutes, but depending on the size of the update and your Internet bandwidth, they can sometimes take up to an hour.
|
||||
@@ -0,0 +1,17 @@
|
||||
.. _dg-android:
|
||||
|
||||
=======
|
||||
Android
|
||||
=======
|
||||
|
||||
Tor Setup (Connectivity)
|
||||
------------------------
|
||||
|
||||
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-android>`_ to run natively (in the background) on your device. This will allow you to use applications on your Android via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
|
||||
|
||||
Tor Firefox Config (Connectivity)
|
||||
---------------------------------
|
||||
|
||||
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-android>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
|
||||
|
||||
.. note:: Please see Android's :ref:`Known Limitations<lim-android>` to understand what is currently not possible on these devices
|
||||
@@ -0,0 +1,12 @@
|
||||
.. _dg-ios:
|
||||
|
||||
===
|
||||
iOS
|
||||
===
|
||||
|
||||
LAN Setup (Connectivity, Performance)
|
||||
-------------------------------------
|
||||
|
||||
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-ios>`_ for a fast and secure connection while on your Embassy's local network.
|
||||
|
||||
.. note:: Please see iOS's :ref:`Known Limitations<lim-ios>` to understand what is currently not possible on these devices
|
||||
@@ -0,0 +1,22 @@
|
||||
.. _dg-linux:
|
||||
|
||||
============
|
||||
Linux Guides
|
||||
============
|
||||
|
||||
LAN Setup (Connectivity, Performance)
|
||||
-------------------------------------
|
||||
|
||||
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-linux>`_ for a fast and secure connection while on your Embassy's local network.
|
||||
|
||||
Tor Setup (Connectivity)
|
||||
------------------------
|
||||
|
||||
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-linux>`_ to run natively (in the background) on your device. This will allow you to use applications on your Linux machine via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
|
||||
|
||||
Tor Firefox Config (Connectivity)
|
||||
---------------------------------
|
||||
|
||||
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-linux>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
|
||||
|
||||
.. note:: Please see Linux's :ref:`Known Limitations<lim-linux>` to understand what is currently not possible on these devices
|
||||
@@ -0,0 +1,22 @@
|
||||
.. _dg-mac:
|
||||
|
||||
===
|
||||
Mac
|
||||
===
|
||||
|
||||
LAN Setup (Connectivity, Performance)
|
||||
-------------------------------------
|
||||
|
||||
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-mac>`_ for a fast and secure connection while on your Embassy's local network.
|
||||
|
||||
Tor Setup (Connectivity)
|
||||
------------------------
|
||||
|
||||
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-mac>`_ to run natively (in the background) on your device. This will allow you to use applications on your Mac via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
|
||||
|
||||
Tor Firefox Config (Connectivity)
|
||||
---------------------------------
|
||||
|
||||
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-mac>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
|
||||
|
||||
.. note:: Please see Mac's :ref:`Known Limitations<lim-mac>` to understand what is currently not possible on these devices
|
||||
@@ -0,0 +1,22 @@
|
||||
.. _dg-windows:
|
||||
|
||||
=======
|
||||
Windows
|
||||
=======
|
||||
|
||||
LAN Setup (Connectivity, Performance)
|
||||
-------------------------------------
|
||||
|
||||
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-windows>`_ for a fast and secure connection while on your Embassy's local network.
|
||||
|
||||
Tor Setup (Connectivity)
|
||||
------------------------
|
||||
|
||||
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-windows>`_ to run natively (in the background) on your device. This will allow you to use applications on your Windows machine via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
|
||||
|
||||
Tor Firefox Config (Connectivity)
|
||||
---------------------------------
|
||||
|
||||
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-windows>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
|
||||
|
||||
.. note:: Please see Window's :ref:`Known Limitations<lim-windows>` to understand what is currently not possible on these devices
|
||||
@@ -0,0 +1,14 @@
|
||||
======================
|
||||
Device-Specific Guides
|
||||
======================
|
||||
|
||||
An overview of EmbassyOS general capabilities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
dg-linux
|
||||
dg-mac
|
||||
dg-windows
|
||||
dg-android
|
||||
dg-ios
|
||||
13
site/source/user-manual/getting-started/index.rst
Normal file
13
site/source/user-manual/getting-started/index.rst
Normal file
@@ -0,0 +1,13 @@
|
||||
===============
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
Take your first steps!
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction
|
||||
purchasing
|
||||
initial-setup
|
||||
device-guides/index
|
||||
68
site/source/user-manual/getting-started/initial-setup.rst
Normal file
68
site/source/user-manual/getting-started/initial-setup.rst
Normal file
@@ -0,0 +1,68 @@
|
||||
.. _initial-setup:
|
||||
|
||||
=============
|
||||
Initial Setup - ***NEEDS COMPACTING / SIMPLIFYING***
|
||||
=============
|
||||
|
||||
.. youtube:: DmTlwp5_zvY
|
||||
|
||||
Power On
|
||||
--------
|
||||
|
||||
1. Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router.
|
||||
|
||||
.. tip:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router.
|
||||
|
||||
2. Plug in your external drive to one of the USB 3.0 (blue) ports on Embassy.
|
||||
|
||||
Embassy will initialize, which may take 10-15min. You will hear 2 distinct sounds:
|
||||
|
||||
* "bep" ‐ Starting up
|
||||
* "chime" ‐ Embassy is ready
|
||||
|
||||
Setup Your Embassy
|
||||
------------------
|
||||
|
||||
1. Ensure the device you are using (desktop/laptop or mobile) is connected to the same network as your router.
|
||||
|
||||
.. caution:: Sometmies a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet.
|
||||
|
||||
2. Visit ``embassy.local`` from your web browser. You will be prompted to enter your :ref:`Product Key`. This is found on the bottom side of your device.
|
||||
|
||||
.. admonition:: Explanation
|
||||
:class: toggle expand
|
||||
|
||||
The product key is used to discover your Embassy's IP address on the Local Area Network using a hashing function and a protocol named :ref:`MDNS (or Zeroconf) <mdns>`.
|
||||
|
||||
3. Create your *permanent* master password and complete setup.
|
||||
|
||||
.. admonition:: Explanation
|
||||
:class: toggle expand
|
||||
|
||||
In this step, the setup process will provide your Embassy with three pieces of critical information:
|
||||
|
||||
* An ed25519 private key. Used by the Embassy to create a .onion public address for encrypted and anonymous communication over Tor.
|
||||
* A 4096 bit RSA private key. Used by the Embassy to create a SSL certificate for encrypted communication over LAN.
|
||||
* A master password. Used by the Embassy to authenticate you as its owner.
|
||||
|
||||
All three secrets are packaged together and transmitted to the Embassy encrypted with its :ref:`Product Key<product-key>`.
|
||||
|
||||
.. warning:: There is also currently no way to change your password. Choose a strong master password. Write it down. Store it somewhere safe. DO NOT LOSE IT. If you lose this password, you may be forced to reset the device, resulting in permanent loss of data. **This one responsibility is the price of sovereignty.**
|
||||
|
||||
Enjoy!
|
||||
------
|
||||
|
||||
Your Embassy is now hosted on the private web! After setup is complete you will be presented with connection information. You can view and manage your Embassy by visiting its unique Tor Address from any Tor-enabled browser, or by accessing it's ``.local`` address from your LAN.
|
||||
|
||||
|
||||
.. admonition:: Troubleshooting
|
||||
|
||||
#. Confirm that the Embassy is plugged into both power and Ethernet, with the USB drive in a USB 3.0 (blue) slot.
|
||||
#. Confirm the Embassy emitted two sounds when powering on: a bep and a chime.
|
||||
#. Confirm you are entering the product key correctly and exactly.
|
||||
#. Confirm your device you are using is not connected to a "Guest" network
|
||||
#. Confirm your device is not using a VPN.
|
||||
#. Try to refresh the ``embassy.local`` page.
|
||||
#. Very rarely, a router may not support mDNS. In this case:
|
||||
* On your desktop or laptop computer, navigate to your router configuration settings within the browser. This is usually an IP address such as 192.168.1.1. A simple web search will usually reveal how to access the router configuration settings for a particular brand.
|
||||
* Once in the router config settings, find the section that lists the devices on your network. You should see an item labeled "embassy". Take note of the associated IP address and enter it into your browser's URL field to enter the setup.
|
||||
15
site/source/user-manual/getting-started/introduction.rst
Normal file
15
site/source/user-manual/getting-started/introduction.rst
Normal file
@@ -0,0 +1,15 @@
|
||||
.. _introduction:
|
||||
|
||||
============
|
||||
Introduction
|
||||
============
|
||||
|
||||
:ref:`Embassy<embassy>` is a new kind of personal computer - one that sits quietly on your shelf and runs all day and night. It has no screen and no keyboard. You access your Embassy from anywhere in the world in total, trustless privacy, simply by visiting its unique Tor address (.onion URL) right from the browser.
|
||||
|
||||
Embassy is composed of commonly available hardware components that can be sourced and assembled by anyone, anywhere, for a marginal fee. Embassy is powered by EmbassyOS, the open-source operating system by Start9.
|
||||
|
||||
So, what do you do with your Embassy? You use it to run services: Bitcoin, Lightning, personal cloud storage, P2P messaging, password management, etc. The list of available services is growing quickly and will eventually encompass the entirety of open-source, self-hosted software.
|
||||
|
||||
Every communication between you and your Embassy is end-to-end encrypted and onion routed over the :ref:`Tor network<tor>`. 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<purchasing>` one directly from :ref:`Start9<start9>`, or you can :ref:`build one yourself<diy>`.
|
||||
9
site/source/user-manual/getting-started/purchasing.rst
Normal file
9
site/source/user-manual/getting-started/purchasing.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
.. _purchasing:
|
||||
|
||||
==========
|
||||
Purchasing
|
||||
==========
|
||||
|
||||
For maximum convenience, you can purchase an Embassy device directly from Start9 through our `Shopify Store <https://store.start9.com>`_. The device comes in a beautiful box, fully-assembled, and pre-installed with the latest version of :ref:`EmbassyOS<embassy-os>`. 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, as well as Lightning payments.
|
||||
|
||||
If you prefer to build your own Embassy, you can follow the :ref:`DIY Guide <diy>`.
|
||||
@@ -1,21 +1,27 @@
|
||||
User Manual
|
||||
============
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:hidden:
|
||||
|
||||
general/index
|
||||
managing-services/index
|
||||
connecting
|
||||
initial-setup
|
||||
getting-started/index
|
||||
configuration/index
|
||||
troubleshooting/index
|
||||
tuning/index
|
||||
walkthrough/index
|
||||
services/index
|
||||
|
||||
.. panel-box::
|
||||
:title: Overview
|
||||
:id: "user-manual"
|
||||
:id: "getting-started"
|
||||
:class: my-panel
|
||||
|
||||
* :doc:`Initial Setup <initial-setup>` - How to setup your Embassy
|
||||
* :doc:`Connecting <connecting>` - Ways to connect to your Embassy
|
||||
* :doc:`Managing Services <managing-services/index>` - Working with the open source projects made compatible for the Embassy
|
||||
* :doc:`General <general/index>` - An overview of EmbassyOS general capabilities
|
||||
EmbassyOS is designed to work out of the box with a minimal setup and immediate practicality. That being said, there are a great many different use-cases and utilities that can be added at your convenience. You can get started right away with :ref:`Initial Setup <initial-setup>`. In the `User Manual <link>`, you will find information on what EmbassyOS can do for you, as well as configuration and customization options. Use our `Knowledgebase <link>` to learn more about the technologies behind Embassy, including Frequently Asked Questions. When you're ready to build, please check out our `Developer Docs <link>`. Please don't hestitate to `Contact Us <https://start9.com/contact>`_ if you have any issues, questions, or suggestions that are not covered here.
|
||||
|
||||
* :doc:`Getting Started <getting-started/index>` - Get started with understanding your Embassy device.
|
||||
* :doc:`Configuration Options <configuration/index>` - Configuration options for EmbassyOS.
|
||||
* :doc:`Troubleshooting <troubleshooting/index>` - Help to resolve common issues.
|
||||
* :doc:`Tuning <tuning/index>` - Customize with advanced configurations.
|
||||
* :doc:`Services <services/index>` - Overview of services available on EmbassyOS.
|
||||
* :doc:`Walkthrough <walkthrough/index>` - Overview of Embassy capabilities.
|
||||
|
||||
@@ -1,81 +0,0 @@
|
||||
.. _initial-setup:
|
||||
|
||||
*************
|
||||
Initial Setup
|
||||
*************
|
||||
|
||||
.. youtube:: DmTlwp5_zvY
|
||||
|
||||
Download the Setup App
|
||||
======================
|
||||
|
||||
`App Store <https://apps.apple.com/us/app/start9-setup-app/id1528125889>`_
|
||||
|
||||
`Google Play <https://play.google.com/store/apps/details?id=com.start9labs.setup>`_
|
||||
|
||||
`APK direct download <https://github.com/Start9Labs/setup-app/releases>`_
|
||||
|
||||
Power On
|
||||
========
|
||||
|
||||
Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router.
|
||||
|
||||
.. note:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router.
|
||||
|
||||
You will hear 2 distinct sounds:
|
||||
|
||||
* "bep" ‐ Powering on
|
||||
* "chime" ‐ Embassy is ready
|
||||
|
||||
Claim Your Embassy
|
||||
==================
|
||||
|
||||
1. Ensure your phone is connected to the same WiFi network as your router.
|
||||
|
||||
.. warning:: Sometmies a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet.
|
||||
|
||||
2. Inside the Setup App, enter the product key located on the bottom of your Embassy
|
||||
|
||||
.. admonition:: Explanation
|
||||
:class: toggle expand
|
||||
|
||||
The product key is used to discover your Embassy's IP address on the Local Area Network using a hashing function and a protocol named MDNS (or Zeroconf). Once in possession of the Embassy's local IP address, the Setup App can now communicate directly with the Embassy.
|
||||
|
||||
.. admonition:: Troubleshooting
|
||||
:class: toggle expand
|
||||
|
||||
#. Confirm that the Embassy is plugged into both power and Ethernet.
|
||||
#. Confirm the Embassy emitted two sounds when powering on: a bep and a chime.
|
||||
#. Confirm you are entering the correct product key.
|
||||
#. Confirm your phone is not connected to a "Guest" network
|
||||
#. Confirm your phone is not using a VPN.
|
||||
#. Close and reopen the Setup App and try again.
|
||||
#. Rarely, certain routers do not support mDNS. Please see the "Advanced" tab.
|
||||
|
||||
.. admonition:: Advanced
|
||||
:class: toggle expand
|
||||
|
||||
If your router does not support mDNS
|
||||
|
||||
* On your desktop or laptop computer, navigate to your router configuration settings within the browser. This is usually an IP address such as 192.168.1.1. A simple Google search will usually reveal how to access the router configuration settings for a particular brand.
|
||||
* Once in the router config settings, find the section that lists the devices on your network. You should see an item labeled "start9labs". Take note of the associated IP address and enter it into the Setup App in the "LAN IP Address" input field.
|
||||
|
||||
3. Create your *permanent* master password and complete setup.
|
||||
|
||||
.. admonition:: Explanation
|
||||
:class: toggle expand
|
||||
|
||||
In this step, the Setup App will provide your Embassy with three pieces of critical information:
|
||||
|
||||
* A ed25519 private key. Used by the Embassy to create a .onion public address for encrypted and anonymous communication over Tor.
|
||||
* A 4096 bit RSA private key. Used by the Embassy to create a SSL certificate for encrypted communication over LAN.
|
||||
* A master password. Used by the Embassy to authenticate you as its owner.
|
||||
|
||||
All three secrets are packaged together and transmitted to the Embassy encrypted with its product key.
|
||||
|
||||
.. warning:: There is also currently no way to change your password. Choose a strong master password. Write it down. Store it somewhere safe. DO NOT LOSE IT. If you lose this password, you may be forced to reset the device, resulting in permanent loss of data.
|
||||
|
||||
Setup Complete!
|
||||
===============
|
||||
|
||||
Your Embassy is now hosted on the private web. You can view and manage your Embassy by visiting its unique Tor Address from any Tor-enabled browser. The Setup App contains our recommendations for various devices.
|
||||
@@ -1,105 +0,0 @@
|
||||
*******
|
||||
Backups
|
||||
*******
|
||||
|
||||
Creating frequent service backups is critical. If anything happens to your Embassy, these backups are your only path to recovering your data.
|
||||
|
||||
.. warning:: Backups are encrypted using your Embassy master password. If you forget your password, you lose your backups.
|
||||
|
||||
|
||||
Creating A Backup
|
||||
=================
|
||||
|
||||
To begin the backup process:
|
||||
|
||||
1. Enter a USB drive with sufficient capacity into a USB port on the device. The blue ports are USB 3.0. The black ports are USB 2.0.
|
||||
2. Navigate to the `Services` sub menu from the main dashboard menu.
|
||||
3. Select the service to be backed-up.
|
||||
4. Select the floppy disc icon next to the `Last Backup` menu item. If a backup was never completed, this should say "never".
|
||||
|
||||
.. figure:: /_static/images/bitcoin_view.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin Core Service Sub Menu
|
||||
|
||||
Bitcoin Core Service Sub Menu
|
||||
|
||||
5. In the modal prompt, select the available disc space. If no option is marked as available, ensure the USB drive has enough space and that it is properly inserted.
|
||||
|
||||
.. figure:: /_static/images/bitcoin_backup_view_storage.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin Core Service Backup Storage
|
||||
|
||||
Backup menu with available storage space
|
||||
|
||||
.. figure:: /_static/images/bitcoin_backup_view_no_storage.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin Core Service Backup No Storage
|
||||
|
||||
Backup menu with no available storage disc
|
||||
|
||||
|
||||
6. Enter the master password to encrypt the backup.
|
||||
7. "Creating Backup..." will appear on the service sub menu while the backup is in process.
|
||||
|
||||
.. figure:: /_static/images/bitcoin_creating_backup.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin Core Service Backup No Storage
|
||||
|
||||
Creating Backup
|
||||
|
||||
8. A notification will emit when the backup has successfully completed.
|
||||
9. The `Last Backup` menu item in the service will now indicate the date and time at which the last backup was made.
|
||||
|
||||
|
||||
Restoring A Backup
|
||||
==================
|
||||
|
||||
To begin the backup restore process:
|
||||
|
||||
1. Enter the same USB stick used to originally backup the service.
|
||||
2. Navigate to the `Services` sub menu from the main dashboard menu.
|
||||
3. Select the service to be backed-up.
|
||||
4. Select the `Restore from backup` menu item.
|
||||
|
||||
.. figure:: /_static/images/restore_backup_menu.png
|
||||
:width: 90%
|
||||
:alt: Restore backup from Services tab
|
||||
|
||||
Restore backup from Services tab
|
||||
|
||||
5. In the modal prompt, select the same disc used to originally back up the service. If no option is marked as available, ensure the USB drive is properly inserted.
|
||||
|
||||
.. figure:: /_static/images/restore_backup_submenu.png
|
||||
:width: 90%
|
||||
:alt: Restore backup submenu
|
||||
|
||||
Restore backup sub-menu options
|
||||
|
||||
6. Note the warning that restoring will wipe current data.
|
||||
|
||||
.. figure:: /_static/images/backup_warning.png
|
||||
:width: 90%
|
||||
:alt: Backup warning message
|
||||
|
||||
Backup warning message
|
||||
|
||||
7. Enter the master password to decrypt the backup and select `Restore`.
|
||||
|
||||
.. figure:: /_static/images/decrypt_backup.png
|
||||
:width: 90%
|
||||
:alt: Decrypt backup
|
||||
|
||||
Decrypt backup view
|
||||
|
||||
8. "Restoring Backup..." will appear on the service sub menu while the restoration is in process.
|
||||
|
||||
.. note::
|
||||
The service might be momentarily unreachable as it starts back up. This is expected behavior.
|
||||
|
||||
.. figure:: /_static/images/restoring_backup.png
|
||||
:width: 90%
|
||||
:alt: Restoring backup
|
||||
|
||||
Restoring backup view
|
||||
|
||||
9. A notification will emit when the backup restoration has successfully completed.
|
||||
@@ -1,20 +0,0 @@
|
||||
.. _managing-services:
|
||||
|
||||
*****************
|
||||
Managing Services
|
||||
*****************
|
||||
|
||||
Services are self-hosted, open source projects made compatible for EmbassyOS. Each service has been independently developed by members of the open source community. The Embassy enables configuration, customization and a one click install.
|
||||
|
||||
.. note:: Some services require configuration before starting up. You can only connect to and use a service once it is in a *running* state.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installing
|
||||
instructions
|
||||
backups
|
||||
service-config
|
||||
properties
|
||||
logs
|
||||
managing-deps
|
||||
@@ -1,30 +0,0 @@
|
||||
*******************
|
||||
Install / Uninstall
|
||||
*******************
|
||||
|
||||
.. note:: Some services have :ref:`dependencies<managing-dependencies>` on other services. Adding, updating, or removing a service can sometimes have requirements or consequences for other services. Your Embassy will inform you of these issues along the way.
|
||||
|
||||
Installing
|
||||
==========
|
||||
|
||||
To add a new service, find it's listing inside the Service Marketplace: *Marketplace > [Service Name] > Install*.
|
||||
|
||||
Depending on the size of the service and your Internet connection, installation should take between 60 seconds and a few minutes.
|
||||
|
||||
After installation, you can view the service's instructions by navigating to *Services > [Service Name] > Instructions*
|
||||
|
||||
.. note:: You can only start and use a service once its dependencies are met, its :ref:`configuration<service-config>` complete, and is in a *running* state.
|
||||
|
||||
|
||||
Updating
|
||||
========
|
||||
|
||||
To see if an update is available for a service, you can click the *refresh* button inside the dashboard of the installed service or by visiting its listing in the Service Marketplace.
|
||||
|
||||
If an update is available, simply click "Update" and confirm the action.
|
||||
|
||||
|
||||
Uninstalling
|
||||
============
|
||||
|
||||
To remove a service, navigate to *Services > [Service Name] > Uninstall*.
|
||||
@@ -1,19 +0,0 @@
|
||||
************
|
||||
Instructions
|
||||
************
|
||||
|
||||
To view the instructions for a particular service, navigate to *Services > [Service Name] > Instructions*.
|
||||
|
||||
.. figure:: /_static/images/bitcoin_instructions.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin instructions menu item
|
||||
|
||||
Instructions menu item
|
||||
|
||||
.. figure:: /_static/images/bitcoin_instructions_view.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin instructions view
|
||||
|
||||
Instructions view
|
||||
|
||||
.. note:: For advanced instructions and integration guides, visit the wrapper repository for an :ref:`available service <available-services>`.
|
||||
@@ -1,7 +0,0 @@
|
||||
************
|
||||
Viewing Logs
|
||||
************
|
||||
|
||||
Naviage to *Services > [Service Name] > Logs*
|
||||
|
||||
Every service emits logs while it is in a *running* state. Logs give an *under-the-hood* glimpse of a service and can be extremely useful for debugging purposes. To a non-technical user, logs may look like gibberish, and sometimes there is nothing to see at all.
|
||||
@@ -1,13 +0,0 @@
|
||||
.. _managing-dependencies:
|
||||
|
||||
*********************
|
||||
Managing Dependencies
|
||||
*********************
|
||||
|
||||
Some services have dependencies on other services. A service may even require its dependency to be *configured* in a particular way.
|
||||
|
||||
Traditionally, managing dependencies was a massive headache and a huge barrier to running a personal server. But no more! The Embassy's revolutionary dependency management system makes the process transparent and simple.
|
||||
|
||||
If a service has one or more dependencies, or a dependency needs to be configured in a particular way, your Embassy will inform you and offer solutions.
|
||||
|
||||
Sometimes, a dependency can be satisfied in multiple ways. For example, Lightning has a dependency on Bitcoin. But that does not necessarily mean you need to have Bitcoin installed on your Embassy. You could just as easily configure Lightning to use another Bitcoin node located somewhere else!
|
||||
@@ -1,13 +0,0 @@
|
||||
**********
|
||||
Properties
|
||||
**********
|
||||
|
||||
Navigate to *Services > [Service Name] > Properties*
|
||||
|
||||
Properties are both static and dynamic information about a service. They could be almost anything: a default username/password, an invite code, or a list of peers - anything the service developer thought might be useful.
|
||||
|
||||
Properties may be accompanied by one or more of the following:
|
||||
|
||||
* a *help* icon for further explanation.
|
||||
* a *copy* icon for copying the value to your clipboard.
|
||||
* a *QR* icon for viewing the value as a QR code.
|
||||
@@ -1,13 +0,0 @@
|
||||
.. _service-config:
|
||||
|
||||
**************
|
||||
Service Config
|
||||
**************
|
||||
|
||||
Navigate to *Services > [Service Name] > Config*
|
||||
|
||||
After installation or update, some services require configuration before they can be started.
|
||||
|
||||
Traditionally, configuring services was a massive headache and a huge barrier to running a personal server. But no more! The Embassy's revolutionary service config system makes the process transparent, simple, and safe.
|
||||
|
||||
Config options are defined by the service developer and can be almost anything. They are represented as simple UI elements - such as toggles and drop downs - and they include explanations and validations, such that users understand their purpose and are prevented from making mistakes.
|
||||
13
site/source/user-manual/services/index.rst
Normal file
13
site/source/user-manual/services/index.rst
Normal file
@@ -0,0 +1,13 @@
|
||||
.. _services-index:
|
||||
|
||||
========
|
||||
Services - ***NEEDS UPDATING / SCREENS***
|
||||
========
|
||||
|
||||
An overview of EmbassyOS general capabilities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
marketplace
|
||||
managing-services
|
||||
124
site/source/user-manual/services/managing-services.rst
Normal file
124
site/source/user-manual/services/managing-services.rst
Normal file
@@ -0,0 +1,124 @@
|
||||
.. _managing-services:
|
||||
|
||||
=================
|
||||
Managing Services
|
||||
=================
|
||||
|
||||
.. _managing-dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
Some services have dependencies on other services. A service may even require its dependency to be *configured* in a particular way.
|
||||
|
||||
Traditionally, managing dependencies was a massive headache and a huge barrier to running a personal server. But no more! The Embassy's revolutionary dependency management system makes the process transparent and simple.
|
||||
|
||||
If a service has one or more dependencies, or a dependency needs to be configured in a particular way, your Embassy will inform you and offer solutions.
|
||||
|
||||
Sometimes, a dependency can be satisfied in multiple ways. For example, Lightning has a dependency on Bitcoin. But that does not necessarily mean you need to have Bitcoin installed on your Embassy. You could just as easily configure Lightning to use another Bitcoin node located somewhere else!
|
||||
|
||||
.. _installing:
|
||||
|
||||
.. note:: Some services have :ref:`dependencies<managing-dependencies>` on other services. Adding, updating, or removing a service can sometimes have requirements or consequences for other services. Your Embassy will inform you of these issues along the way.
|
||||
|
||||
Installing
|
||||
----------
|
||||
|
||||
To add a new service, find it's listing inside the Service Marketplace: *Marketplace > [Service Name] > Install*.
|
||||
|
||||
Depending on the size of the service and your Internet connection, installation should take between 60 seconds and a few minutes.
|
||||
|
||||
After installation, you can view the service's instructions by navigating to *Services > [Service Name] > Instructions*
|
||||
|
||||
.. note:: You can only start and use a service once its dependencies are met, its :ref:`configuration<service-config>` complete, and is in a *running* state.
|
||||
|
||||
.. _updates:
|
||||
|
||||
Updating
|
||||
--------
|
||||
|
||||
To see if an update is available for a service, you can click the *refresh* button inside the dashboard of the installed service or by visiting its listing in the Service Marketplace.
|
||||
|
||||
If an update is available, simply click "Update" and confirm the action.
|
||||
|
||||
.. _uninstalling:
|
||||
|
||||
Uninstalling
|
||||
------------
|
||||
|
||||
To remove a service, navigate to *Services > [Service Name] > Uninstall*.
|
||||
|
||||
.. _instructions:
|
||||
|
||||
Instructions
|
||||
------------
|
||||
|
||||
To view the instructions for a particular service, navigate to *Services > [Service Name] > Instructions*.
|
||||
|
||||
.. figure:: /_static/images/bitcoin_instructions.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin instructions menu item
|
||||
|
||||
Instructions menu item
|
||||
|
||||
.. figure:: /_static/images/bitcoin_instructions_view.png
|
||||
:width: 90%
|
||||
:alt: Bitcoin instructions view
|
||||
|
||||
Instructions view
|
||||
|
||||
.. note:: For advanced instructions and integration guides, visit the wrapper repository for an :ref:`available service <available-services>`.
|
||||
|
||||
.. _service-config:
|
||||
|
||||
Service Config
|
||||
--------------
|
||||
|
||||
Navigate to *Services > [Service Name] > Config*
|
||||
|
||||
After installation or update, some services require configuration before they can be started.
|
||||
|
||||
Traditionally, configuring services was a massive headache and a huge barrier to running a personal server. But no more! The Embassy's revolutionary service config system makes the process transparent, simple, and safe.
|
||||
|
||||
Config options are defined by the service developer and can be almost anything. They are represented as simple UI elements - such as toggles and drop downs - and they include explanations and validations, such that users understand their purpose and are prevented from making mistakes.
|
||||
|
||||
.. _properties:
|
||||
|
||||
Properties
|
||||
----------
|
||||
|
||||
Navigate to *Services > [Service Name] > Properties*
|
||||
|
||||
Properties are both static and dynamic information about a service. They could be almost anything: a default username/password, an invite code, or a list of peers - anything the service developer thought might be useful.
|
||||
|
||||
Properties may be accompanied by one or more of the following:
|
||||
|
||||
* a *help* icon for further explanation.
|
||||
* a *copy* icon for copying the value to your clipboard.
|
||||
* a *QR* icon for viewing the value as a QR code.
|
||||
|
||||
.. _actions:
|
||||
|
||||
Actions
|
||||
-------
|
||||
|
||||
.. _interfaces:
|
||||
|
||||
Interfaces
|
||||
----------
|
||||
|
||||
.. _logs:
|
||||
|
||||
Logs
|
||||
----
|
||||
|
||||
Naviage to *Services > [Service Name] > Logs*
|
||||
|
||||
Every service emits logs while it is in a *running* state. Logs give an *under-the-hood* glimpse of a service and can be extremely useful for debugging purposes. To a non-technical user, logs may look like gibberish, and sometimes there is nothing to see at all.
|
||||
|
||||
.. _donate:
|
||||
|
||||
Donate
|
||||
------
|
||||
|
||||
This link is provided by the developer so that you may donate to them or the developer of the service they packaged directly.
|
||||
10
site/source/user-manual/services/marketplace.rst
Normal file
10
site/source/user-manual/services/marketplace.rst
Normal file
@@ -0,0 +1,10 @@
|
||||
.. _service-marketplace:
|
||||
|
||||
===========
|
||||
Marketplace
|
||||
===========
|
||||
|
||||
LINK TO MARKETPLACE
|
||||
FIND A PLACE TO LINK S9 ALTWEB SERVICE MOST WANTED LIST
|
||||
|
||||
ROADMAP NEEDS A HOME
|
||||
13
site/source/user-manual/troubleshooting/index.rst
Normal file
13
site/source/user-manual/troubleshooting/index.rst
Normal file
@@ -0,0 +1,13 @@
|
||||
.. _troubleshooting:
|
||||
|
||||
===============
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
Sometimes things don't go as planned. Check here for solutions to common problems with your Embassy.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
shoot-connection
|
||||
shoot-embassy
|
||||
19
site/source/user-manual/troubleshooting/shoot-connection.rst
Normal file
19
site/source/user-manual/troubleshooting/shoot-connection.rst
Normal file
@@ -0,0 +1,19 @@
|
||||
.. _shoot-connection:
|
||||
|
||||
===========================
|
||||
Troubleshooting Connections
|
||||
===========================
|
||||
|
||||
During initial setup, I am unable to connect to ``embassy.local``.
|
||||
------------------------------------------------------------------
|
||||
Please ensure that the device you are attempting to connect with is on the same network as your Embassy. This cannot be a "Guest" network, or a WiFi network that is in any way separated from the network Embassy is on.
|
||||
|
||||
If you still cannot connect, you can log into your router (the directions for which can be founnd with a simple web search for your router model and 'how to log in'). Once you are in your router, find the device labeled 'Embassy,' and visit it's associated IP address, which will look something like: ``192.168.1.9``
|
||||
|
||||
I am unable to reach Embassy via it's ``embassy-xxxxxxxx.local`` (LAN) address
|
||||
------------------------------------------------------------------------------
|
||||
Make sure you have successfully followed the :ref:`LAN Setup<lan-setup>` instructions for your device. If you still cannot connect, make sure you are on the same network using the solution above. If you are able to visit your Embassy via its IP address, then something is wrong in your LAN Setup. Keep in mind that different devices have different methods of resolving ``.local`` addresses, and some devices, such as :ref:`Android<lim-android>`, lack the ability at an OS level.
|
||||
|
||||
I am unable to reach Embassy via it's ``xxxxxxxxxxxxxxxxxx.onion`` (Tor) address
|
||||
--------------------------------------------------------------------------------
|
||||
First, attmept to connect using :ref:`The Tor Browser<tor-browser>`. This is a good test because Tor Browser has Tor built in. If you cannot reach your ``.onion`` with Tor Browser, reboot the Embassy by unplugging power and plugging it back in. This will reset your Tor connection. If you can reach via Tor Browser, but not with another browser, then follow the setup guides to run Tor on your device :ref:`Natively<tor-os>` and/or to :ref:`Configure Your Browser<tor-firefox>`.
|
||||
25
site/source/user-manual/troubleshooting/shoot-embassy.rst
Normal file
25
site/source/user-manual/troubleshooting/shoot-embassy.rst
Normal file
@@ -0,0 +1,25 @@
|
||||
.. _shoot-embassy:
|
||||
|
||||
=======================
|
||||
Troubleshooting Embassy
|
||||
=======================
|
||||
|
||||
Hardware
|
||||
--------
|
||||
|
||||
Embassy is making noises
|
||||
........................
|
||||
The plug and play Embassy sold by Start9 has no moving parts, so the only noises it should ever make would come from its internal speaker. The following is a list of all possible sounds:
|
||||
|
||||
#.
|
||||
|
||||
Embassy will not boot
|
||||
.....................
|
||||
If the device will not power on at all (no lights whatsoever), then the only issues could be that the Pi is not getting the power it needs, or it is completely dead (extremely rare). If you sourced your own parts, please ensure that the power supply meets the minimum required specificiations in the `DIY Guide<diy>`. If you received your device from us and it will not power up at all, please `Contact us<contact>` for assistance.
|
||||
|
||||
Software
|
||||
--------
|
||||
|
||||
I'm having an issue with a particular Service
|
||||
.............................................
|
||||
If a Service is crashing or acting up in some way, check the `Documentation<services>` and `FAQ<faq-services>` for that particular Service. You can also check the `Logs` of a service, which might tell you what the problem is. If that is not helpful, try to restart the service to see if that clears up the issue. If you are still having issues, please reach out in one of our `Community Channels` for immediate assistance, or email support@start9labs.com for help during business hours.
|
||||
@@ -1,6 +1,6 @@
|
||||
***********************
|
||||
Alternative Marketplace
|
||||
***********************
|
||||
=======================
|
||||
Alternative Marketplace - ***NEEDS UPDATED***
|
||||
=======================
|
||||
|
||||
EmbassyOS supports accessing alternative marketplaces by configuring a system file. Start9 is not responsible for issues encountered by downloading services from alternative marketplaces.
|
||||
|
||||
@@ -18,4 +18,4 @@ To revert this change, simply delete the file::
|
||||
|
||||
sudo systemctl stop agent
|
||||
sudo rm /root/agent/alt_registry_url.txt
|
||||
sudo systemctl start agent
|
||||
sudo systemctl start agent
|
||||
11
site/source/user-manual/tuning/advanced-config/index.rst
Normal file
11
site/source/user-manual/tuning/advanced-config/index.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
======================
|
||||
Advanced Configuration
|
||||
======================
|
||||
|
||||
Custom options for folks that "know what they're doing."
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ssh-setup
|
||||
alt-marketplace
|
||||
@@ -1,13 +1,13 @@
|
||||
.. _ssh-setup:
|
||||
|
||||
*********
|
||||
=========
|
||||
SSH Setup
|
||||
*********
|
||||
=========
|
||||
|
||||
.. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause through SSH access.
|
||||
|
||||
Connecting via CLI
|
||||
==================
|
||||
------------------
|
||||
|
||||
#. Navigate to *Developer Options > SSH Keys*
|
||||
#. Click the ``+`` button in the lower right hand corner.
|
||||
@@ -17,6 +17,6 @@ Connecting via CLI
|
||||
ssh pi@<LAN URL>
|
||||
|
||||
Connecting via SSH on Windows, using PuTTY
|
||||
==========================================
|
||||
------------------------------------------
|
||||
|
||||
One of our community members, @brewsbitcoin, has put together this guide for connecting via PuTTY on Windows: https://medium.com/@brewsbitcoin/ssh-to-start9-embassy-from-windows-4a4e17891b5a
|
||||
93
site/source/user-manual/tuning/diy.rst
Normal file
93
site/source/user-manual/tuning/diy.rst
Normal file
@@ -0,0 +1,93 @@
|
||||
.. _diy:
|
||||
|
||||
=========
|
||||
DIY Guide
|
||||
=========
|
||||
|
||||
.. figure:: /_static/images/diy/pi.png
|
||||
:width: 40%
|
||||
:alt: Raspberry Pi
|
||||
|
||||
Raspberry Pi Board
|
||||
|
||||
By popular demand, we are pleased to present this "Do it Yourself" (DIY) guide for the Start9 Embassy personal server!
|
||||
|
||||
Motivation
|
||||
----------
|
||||
|
||||
There are four reasons you might prefer to build your own Embassy instead of purchasing one from us.
|
||||
|
||||
#. You already own the necessary hardware and would like to re-purpose it.
|
||||
|
||||
#. You live outside the US and want to save on shipping costs.
|
||||
|
||||
#. You do not trust Start9's supply chain.
|
||||
|
||||
#. You do not want to share your shipping address.
|
||||
|
||||
#. You just like building things.
|
||||
|
||||
Building an Embassy
|
||||
-------------------
|
||||
|
||||
Hardware: Components
|
||||
....................
|
||||
|
||||
#. `Raspberry Pi 4B (8GB) <https://raspberrypi.org/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-8gb>`_
|
||||
#. `Power supply for Raspberry Pi 4B <https://raspberrypi.org/products/type-c-power-supply/>`_ Make sure this is at minimum 15w and 3.5a.
|
||||
#. Case for Raspberry Pi 4B (`passive cooling recommended <https://www.amazon.com/Geekworm-Raspberry-Aluminum-Passive-Heatsink/dp/B07Z6FYHCH/>`_ `*`)
|
||||
#. A `16GB microSD card <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (no need for bigger). If you have ABSOLUTELY NO data to migrate, you may choose to re-use the card already in your Embassy.
|
||||
#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/>`_ (These often sell out, please let us know if this link needs to be refreshed)
|
||||
#. Ethernet cable
|
||||
#. MicroSD → USB adapter (or you may have a microSD port on your computer)
|
||||
#. An external drive (1TB minimum, 2TB SSD recommended), or an `internal drive <https://www.amazon.com/Crucial-MX500-NAND-SATA-Internal/dp/B078211KBB>`_ with an `USB enclosure <https://www.amazon.com/gp/product/B07T9D8F6C>`_, as sold with our upgrade kits. MUST CONNECT OVER USB 3.0
|
||||
|
||||
`*` If you use a fan, **DO NOT** use the official Raspberry Pi fan, as it requires the same GPIO pins as the audio speaker. Instead, we recommend `this fan <https://www.amazon.com/Raspberry-iUniker-30x30x7mm-Brushless-RetroFlag/dp/B076H3TKBP/>`_.
|
||||
|
||||
Hardware: Assembly Instructions
|
||||
...............................
|
||||
|
||||
#. Insert mini speaker/buzzer into GPIO pins 6/8/10/12 with the word "speaker" facing out, `away from the board`.
|
||||
|
||||
.. figure:: /_static/images/diy/pins.png
|
||||
:width: 60%
|
||||
:alt: Speaker board spec
|
||||
|
||||
#. Place the Raspberry Pi 4 board (with speaker attached), into its case.
|
||||
#. Plug in the external drive to one of the USB 3.0 (blue) slots
|
||||
|
||||
Getting EmbassyOS
|
||||
-----------------
|
||||
|
||||
Getting EmbassyOS: Purchasing
|
||||
.............................
|
||||
|
||||
You can purchase EmbassyOS `here <https://store.start9.com/collections/embassy/products/embassyos-software-download>`_. This is by far the easiest path to get up and running.
|
||||
|
||||
Depending on your Internet speed, the download should take between 5 and 30 minutes.
|
||||
|
||||
Getting EmbassyOS: Building from Source
|
||||
.......................................
|
||||
|
||||
***Placehodler for build guide - either link to GH or duplicate here. Probably duplicate to keep all docs centralized to this repo - https://github.com/Start9Labs/embassy-os/tree/integration/0.3.0/build***
|
||||
|
||||
Installing EmbassyOS
|
||||
--------------------
|
||||
|
||||
Whether you purchase EmbassyOS from us or build it yourself, you need to flash it onto a microSD card.
|
||||
|
||||
#. Download `balenaEtcher <https://www.balena.io/etcher/>`_ onto your Mac, Windows, or Linux computer.
|
||||
#. Insert the microSD card into your computer, either directly or using an adapter.
|
||||
#. Open balenaEtcher.
|
||||
#. Click `Select Image`, then find and select your copy of EmbassyOS.
|
||||
#. Click `Select Target`, then find and select your micro SD card.
|
||||
#. Click `Flash!` You may be asked to (1) approve the unusually large disk target or (2) enter your password. Both are normal.
|
||||
|
||||
.. figure:: /_static/images/diy/balena.png
|
||||
:width: 60%
|
||||
:alt: Balena Etcher Dashboard
|
||||
|
||||
#. Once the image is flashed and verified, you may remove the micro SD, insert it into your Embassy, and power up the device.
|
||||
#. The Embassy is now ready for use, and you may following the normal :ref:`setup <initial-setup>` instructions. ``*``
|
||||
|
||||
``*`` The first time you power it on, your Embassy will make more noises than future attempts, and it may take several minutes to finally complete.
|
||||
15
site/source/user-manual/tuning/embassy-os.rst
Normal file
15
site/source/user-manual/tuning/embassy-os.rst
Normal file
@@ -0,0 +1,15 @@
|
||||
.. _tune-embassy-os:
|
||||
|
||||
=====================
|
||||
Customizing EmbassyOS
|
||||
=====================
|
||||
|
||||
Rename Device
|
||||
-------------
|
||||
|
||||
Duplicate in walkthrough, probably move to here
|
||||
|
||||
Reorder Service Page
|
||||
--------------------
|
||||
|
||||
Customize Services layout
|
||||
14
site/source/user-manual/tuning/index.rst
Normal file
14
site/source/user-manual/tuning/index.rst
Normal file
@@ -0,0 +1,14 @@
|
||||
======
|
||||
Tuning
|
||||
======
|
||||
|
||||
Here, you can customize your Embassy with advanced configuration, setup external tools, migrate from old projects, or build your own Embassy from scratch.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
diy
|
||||
migrating
|
||||
advanced-config/index
|
||||
embassy-os
|
||||
service-guides/index
|
||||
21
site/source/user-manual/tuning/migrating.rst
Normal file
21
site/source/user-manual/tuning/migrating.rst
Normal file
@@ -0,0 +1,21 @@
|
||||
.. _migrating:
|
||||
|
||||
====================
|
||||
Migrating To Embassy
|
||||
====================
|
||||
|
||||
From Umbrel
|
||||
-----------
|
||||
|
||||
Dreadlocked
|
||||
|
||||
======================
|
||||
Migrating From Embassy
|
||||
======================
|
||||
|
||||
We hate to see you go, but respect your freedom to choose. If you decide to use your hardware with different software, here are some guidelines.
|
||||
|
||||
.. warning:: For obvious reasons, we cannot officially support anything that happens when you leave the Embassy ecosystem
|
||||
|
||||
To Umbrel
|
||||
---------
|
||||
63
site/source/user-manual/tuning/service-guides/bitcoin.rst
Normal file
63
site/source/user-manual/tuning/service-guides/bitcoin.rst
Normal file
@@ -0,0 +1,63 @@
|
||||
.. _bitcoin:
|
||||
|
||||
=======
|
||||
Bitcoin
|
||||
=======
|
||||
|
||||
Here you will find guides on how to connect different kinds of Bitcoin wallets (hardware and software) to your Embassy node, to complete your sovereign Bitcoin stack!
|
||||
|
||||
.. _bitcoin-cli:
|
||||
|
||||
Using Bitcoin-Cli
|
||||
-----------------
|
||||
|
||||
Instructions for accessing the bitcoind service in order to issue commands directly.
|
||||
|
||||
.. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause through SSH access.
|
||||
|
||||
1. First, you will need SSH access. Please see the :ref:`setup instructions <ssh-setup>` for details.
|
||||
2. Access your Embassy and then you can interact with the bitcoind docker container using the following syntax::
|
||||
|
||||
sudo docker exec bitcoind bitcoin-cli COMMAND
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
sudo docker exec bitcoind bitcoin-cli getnetworkinfo
|
||||
|
||||
A list of possible commands can be found `here <https://chainquery.com/bitcoin-cli>`_.
|
||||
|
||||
You can also drop into a shell using::
|
||||
|
||||
sudo docker exec -it bitcoind bash
|
||||
|
||||
and then enter ``bitcoin-cli`` commands. When you are finished, simply type ``exit``.
|
||||
|
||||
.. _electrum:
|
||||
|
||||
Electrum
|
||||
--------
|
||||
|
||||
.. _fully-noded:
|
||||
|
||||
FullyNoded
|
||||
----------
|
||||
|
||||
.. _sparrow:
|
||||
|
||||
Sparrow
|
||||
-------
|
||||
|
||||
.. _specter:
|
||||
|
||||
Specter
|
||||
-------
|
||||
|
||||
.. _trezor:
|
||||
|
||||
Trezor
|
||||
------
|
||||
|
||||
.. _ledger:
|
||||
|
||||
Ledger Live
|
||||
-----------
|
||||
13
site/source/user-manual/tuning/service-guides/index.rst
Normal file
13
site/source/user-manual/tuning/service-guides/index.rst
Normal file
@@ -0,0 +1,13 @@
|
||||
=======================
|
||||
Service-Specific Guides
|
||||
=======================
|
||||
|
||||
These guides will help you to setup external tools to connect or interact with specific :ref:`Services<services>`, such as a chat client or :ref:`Bitcoin<bitcoin>` wallet.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
vaultwarden
|
||||
matrix
|
||||
bitcoin
|
||||
lightning
|
||||
25
site/source/user-manual/tuning/service-guides/lightning.rst
Normal file
25
site/source/user-manual/tuning/service-guides/lightning.rst
Normal file
@@ -0,0 +1,25 @@
|
||||
.. _lightning:
|
||||
|
||||
=========
|
||||
Lightning
|
||||
=========
|
||||
|
||||
.. _rtl:
|
||||
|
||||
Ride the Lightning
|
||||
------------------
|
||||
|
||||
.. _thunderhub:
|
||||
|
||||
Thunderhub
|
||||
----------
|
||||
|
||||
.. _zap:
|
||||
|
||||
Zap
|
||||
---
|
||||
|
||||
.. _zeus:
|
||||
|
||||
Zeus
|
||||
----
|
||||
7
site/source/user-manual/tuning/service-guides/matrix.rst
Normal file
7
site/source/user-manual/tuning/service-guides/matrix.rst
Normal file
@@ -0,0 +1,7 @@
|
||||
.. _matrix:
|
||||
|
||||
======
|
||||
Matrix
|
||||
======
|
||||
|
||||
https://www.youtube.com/watch?v=PtwQsybFapo
|
||||
@@ -0,0 +1,7 @@
|
||||
.. _vaultwarden:
|
||||
|
||||
===========
|
||||
Vaultwarden
|
||||
===========
|
||||
|
||||
https://www.youtube.com/watch?v=YcxxVHpm9j0
|
||||
57
site/source/user-manual/walkthrough/backup.rst
Normal file
57
site/source/user-manual/walkthrough/backup.rst
Normal file
@@ -0,0 +1,57 @@
|
||||
.. _backup:
|
||||
|
||||
==================
|
||||
Backing Up Embassy
|
||||
==================
|
||||
|
||||
There are 2 options for backing up your Embassy and all its service data. You can setup a shared folder on a remote machine, such as a laptop or desktop, or you can backup to a local drive, which must be externally powered or plugged into a powered USB hub before plugging into Embassy.
|
||||
|
||||
Remote Backups
|
||||
--------------
|
||||
|
||||
Linux
|
||||
=====
|
||||
|
||||
#. IYKYK
|
||||
|
||||
Mac
|
||||
===
|
||||
|
||||
#. go to system settings
|
||||
#. click sharing
|
||||
#. click file sharing
|
||||
#. click the + under shared folders
|
||||
#. add a folder
|
||||
#. click options
|
||||
#. enable Windows file sharing for the user you would like to use to authenticate
|
||||
#. click done
|
||||
#. enter the name of your macbook, as shown in the computer name field at the top of the sharing page into the hostname field in embassy ui
|
||||
#. enter the name of the folder as shown in the shared folders section as the path
|
||||
#. enter your macbook username and password for the user that you enabled windows file sharing for
|
||||
|
||||
Windows
|
||||
=======
|
||||
|
||||
#. Create a folder
|
||||
#. Right click the folder
|
||||
#. select "properties"
|
||||
#. click the share tab
|
||||
#. click share...
|
||||
#. select a user you want to use for login, or select everyone
|
||||
#. click share
|
||||
#. enter your computer name into the hostname field in embassy ui (the name is shown after a \\ in the windows ui)
|
||||
#. enter the path that is shown after the hostname in the windows ui into the path field
|
||||
#. enter your username for the windows computer
|
||||
#. enter the password for the windows computer
|
||||
|
||||
Local Backups
|
||||
-------------
|
||||
|
||||
Linux
|
||||
=====
|
||||
|
||||
Mac
|
||||
===
|
||||
|
||||
Windows
|
||||
=======
|
||||
15
site/source/user-manual/walkthrough/index.rst
Normal file
15
site/source/user-manual/walkthrough/index.rst
Normal file
@@ -0,0 +1,15 @@
|
||||
.. _walkthrough:
|
||||
|
||||
===========
|
||||
Walkthrough
|
||||
===========
|
||||
|
||||
An overview of EmbassyOS general capabilities.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
updates
|
||||
backup
|
||||
password
|
||||
80
site/source/user-manual/walkthrough/overview.rst
Normal file
80
site/source/user-manual/walkthrough/overview.rst
Normal file
@@ -0,0 +1,80 @@
|
||||
.. _overview:
|
||||
|
||||
=====================
|
||||
Overview of EmbassyOS - ***NEED SCREENSHOTS / DETAILS***
|
||||
=====================
|
||||
|
||||
.. _services-tab:
|
||||
|
||||
Services Tab
|
||||
------------
|
||||
|
||||
The Services Tab will show you all of your currently installed :ref:`Services<services>`, or in the case of a fresh install, no Services.
|
||||
|
||||
Services
|
||||
========
|
||||
|
||||
.. _embassy-tab:
|
||||
|
||||
Embassy Tab
|
||||
-----------
|
||||
|
||||
The Embassy Tab is where you can perform :ref:`Backups<backups>`, get Insights into EOS, change some basic Settings, and Power cycle your device if necessary.
|
||||
|
||||
Backups
|
||||
=======
|
||||
|
||||
Do the backups
|
||||
|
||||
Insights
|
||||
========
|
||||
|
||||
Get the insights
|
||||
|
||||
Settings
|
||||
========
|
||||
|
||||
Set the things
|
||||
|
||||
Power
|
||||
=====
|
||||
|
||||
Restart
|
||||
.......
|
||||
|
||||
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
|
||||
#. A gentle *bep* will sound when the Embassy is powered back on.
|
||||
#. A *chime* will sound when the Embassy is ready to use. Please be patient as a Restart will take some time.
|
||||
|
||||
Shutdown
|
||||
........
|
||||
|
||||
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
|
||||
#. It is now safe to unplug the Embassy from power and the ethernet cable, if connected.
|
||||
|
||||
.. note:: After a shutdown, the *only* way to turn your Embassy back on is to unplug it and plug it back in. As such, we do not recommend shutting down your Embassy when you are not physically near it. Instead, you should use the restart option.
|
||||
|
||||
.. _marketplace-tab:
|
||||
|
||||
Marketplace Tab
|
||||
---------------
|
||||
|
||||
The Marketplace Tab is obviously the home of the Marketplace, where you can install new Services, or manange existing ones.
|
||||
|
||||
Marketplace
|
||||
===========
|
||||
|
||||
.. _notifications-tab:
|
||||
|
||||
Notifications Tab
|
||||
-----------------
|
||||
|
||||
The Notifications Tab is where you can view and manage Notifications produced by EOS and your Services
|
||||
|
||||
Notifications
|
||||
=============
|
||||
|
||||
* successful or failed EmbassyOS updates
|
||||
* successful or failed service installations
|
||||
* successful or failed service backups
|
||||
* successful or failed service updates
|
||||
@@ -1,11 +1,13 @@
|
||||
***************
|
||||
Forgot Password
|
||||
***************
|
||||
.. _forgot-password:
|
||||
|
||||
===============
|
||||
Forgot Password - ***NEEDS UPDATING***
|
||||
===============
|
||||
|
||||
There is currently no way to reset you Embassy master password through a standard UI flow.
|
||||
|
||||
SSH/Linux
|
||||
=========
|
||||
---------
|
||||
|
||||
If you already have :ref:`SSH keys registered with your Embassy<ssh-setup>` **OR** you have access to a Linux computer, you can reset your Embassy password without losing any data.
|
||||
|
||||
@@ -19,7 +21,7 @@ If you already have :ref:`SSH keys registered with your Embassy<ssh-setup>` **OR
|
||||
|
||||
which sqlite3
|
||||
sudo apt install sqlite3
|
||||
|
||||
|
||||
* Access the sqlite3 terminal::
|
||||
|
||||
sudo sqlite3 /root/agent/start9_agent.sqlite3
|
||||
@@ -69,6 +71,6 @@ If you already have :ref:`SSH keys registered with your Embassy<ssh-setup>` **OR
|
||||
|
||||
|
||||
No SSH/Linux
|
||||
============
|
||||
------------
|
||||
|
||||
You must factory reset your device by re-installing EmbassyOS, resulting in permanent loss of data. Visit the `image downloader <https://images.start9labs.com/download>`_ to obtain a new EmbassyOS image, then follow the `installation instructions </getting-started/diy.html#installing-embassyos>`_.
|
||||
32
site/source/user-manual/walkthrough/updates.rst
Normal file
32
site/source/user-manual/walkthrough/updates.rst
Normal file
@@ -0,0 +1,32 @@
|
||||
.. _updates:
|
||||
|
||||
========
|
||||
Updating
|
||||
========
|
||||
|
||||
Keeping current on Updates ensures a fast and secure system.
|
||||
|
||||
.. _update-eos:
|
||||
|
||||
Updating EmbassyOS
|
||||
------------------
|
||||
|
||||
When an Operating System update is available, a big, beautiful banner will appear in the Marketplace as an announcement. Simply click on this and follow the UI flow to update EmbassyOS. It is recommended to keep EOS up to date for the latest security and performance patches, as well as to take advantage of new features.
|
||||
|
||||
.. _auto-check-updates:
|
||||
|
||||
Enable Auto Check for Updates
|
||||
-----------------------------
|
||||
|
||||
#. Navigate to the ``Embassy`` tab -> ``Preferences``
|
||||
#. Click "Auto Check for Updates" and click Enable
|
||||
#. If there is an update available, you will be prompted to install it.
|
||||
#. While updating, your Embassy will emit a gentle chime every 20 seconds.
|
||||
#. You can also enable automatic check for updates in the :ref:`Embassy config <auto-update>` tab.
|
||||
|
||||
.. note:: Ensure you have a stable Internet connection, and do not unplug your Embassy during an update. Updates usually complete within a few minutes, but depending on the size of the update and your Internet bandwidth, they can sometimes take up to an hour.
|
||||
|
||||
Manually Checking Updates
|
||||
-------------------------
|
||||
|
||||
If you choose not to enable automatic updates, service updates will appear in the `Updates` tab of the Marketplace when ready.
|
||||
Reference in New Issue
Block a user