mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-30 12:11:57 +00:00
restructure to account for new theme, add new build process, update readme
This commit is contained in:
Lucy Cifferello
@@ -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,21 +0,0 @@
|
||||
***********************
|
||||
Alternative Marketplace
|
||||
***********************
|
||||
|
||||
EmbassyOS supports accessing alternative marketplaces by configuring a system file. Start9 is not responsible for issues encountered by downloading services from alternative marketplaces.
|
||||
|
||||
After SSH-ing into the Embassy, run the following commands::
|
||||
|
||||
sudo systemctl stop agent
|
||||
sudo sh -c "echo '<alternative_marketplace_url>' > /root/agent/alt_registry_url.txt"
|
||||
sudo systemctl start agent
|
||||
|
||||
The Embassy is now able to connect to the provided alternative registry.
|
||||
|
||||
----
|
||||
|
||||
To revert this change, simply delete the file::
|
||||
|
||||
sudo systemctl stop agent
|
||||
sudo rm /root/agent/alt_registry_url.txt
|
||||
sudo systemctl start agent
|
||||
@@ -1,9 +0,0 @@
|
||||
*****************
|
||||
Developer Options
|
||||
*****************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ssh-setup
|
||||
alt-marketplace
|
||||
@@ -1,22 +0,0 @@
|
||||
.. _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.
|
||||
#. Paste in your SSH key.
|
||||
#. You can now access your Embassy from the command line using::
|
||||
|
||||
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
|
||||
@@ -1,19 +0,0 @@
|
||||
**************
|
||||
Config Options
|
||||
**************
|
||||
|
||||
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."
|
||||
|
||||
.. figure:: /_static/images/embassy_config.png
|
||||
:width: 90%
|
||||
:alt: Embassy Config View
|
||||
|
||||
.. _auto-update:
|
||||
|
||||
Automatic check for updates enables you to choose whether you want to be informed of EmbassyOS updates. Enabling this feature makes a request to the Start9 Marketplace to see if a new OS version has been released, and notifies you if so. This request is only made when you log into a new session or refresh your current session.
|
||||
|
||||
.. figure:: /_static/images/embassy_auto_check_updates.png
|
||||
:width: 90%
|
||||
:alt: Embassy Config View
|
||||
|
||||
View of Embassy Config
|
||||
@@ -1,74 +0,0 @@
|
||||
***************
|
||||
Forgot Password
|
||||
***************
|
||||
|
||||
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.
|
||||
|
||||
* SSH:
|
||||
|
||||
* Use the command line to gain SSH access to your Embassy::
|
||||
|
||||
ssh pi@start9-[network-id].local
|
||||
|
||||
* Check if you have sqlite3 installed. If not, install it::
|
||||
|
||||
which sqlite3
|
||||
sudo apt install sqlite3
|
||||
|
||||
* Access the sqlite3 terminal::
|
||||
|
||||
sudo sqlite3 /root/agent/start9_agent.sqlite3
|
||||
|
||||
* Run::
|
||||
|
||||
delete from account;
|
||||
.quit
|
||||
|
||||
* Exit the SSH session::
|
||||
|
||||
exit
|
||||
|
||||
* You can now use the Start9 Setup App to reclaim your Embassy and set a new password.
|
||||
|
||||
.. warning:: Running setup process will generate new certificate and Tor address for your Embassy.
|
||||
|
||||
* Linux computer:
|
||||
|
||||
* Shut down your Embassy, disconnect from power, and remove the microSD card.
|
||||
* Insert the microSD card into your Linux computer and mount the drive::
|
||||
|
||||
mount [drive] [mount folder]
|
||||
|
||||
* Check if you have sqlite3 installed. If not, install it::
|
||||
|
||||
which sqlite3
|
||||
sudo apt install sqlite3
|
||||
|
||||
* Access the sqlite3 terminal::
|
||||
|
||||
sudo sqlite3 /root/agent/start9_agent.sqlite3
|
||||
|
||||
* Run::
|
||||
|
||||
delete from account;
|
||||
.quit
|
||||
|
||||
* Un-mount the microSD card::
|
||||
|
||||
umount [mount folder]
|
||||
|
||||
* Return the microSD card to your Embassy and power it on.
|
||||
* You can now use the Start9 Setup App to reclaim your Embassy and set a new password.
|
||||
|
||||
.. warning:: Running setup process will generate new certificate and Tor address for your Embassy.
|
||||
|
||||
|
||||
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>`_.
|
||||
@@ -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,207 +0,0 @@
|
||||
.. _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>`.
|
||||
|
||||
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:
|
||||
|
||||
#. Check out this video: https://www.youtube.com/watch?v=9ECCB3bqNDQ
|
||||
#. Uninstall Bonjour completely via ``system settings -> remove programs``
|
||||
#. Reinstall Bonjour Printer Driver package (download at https://support.apple.com/kb/DL999?locale=en_US)
|
||||
#. Restart Windows
|
||||
#. Note: Uninstalling Bonjour via the setup package seems to be not enough to solve the issue. Bonjour must be uninstalled via windows system settings.
|
||||
|
||||
#. Visit your Embassy at its Tor Address.
|
||||
|
||||
#. 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 download icon
|
||||
|
||||
#. Select the option to save the *Embassy Local CA.crt* file.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/windows_download_cert.png
|
||||
:width: 90%
|
||||
:alt: LAN setup prompt
|
||||
|
||||
"Save file" when Opening Embassy Local CA.crt
|
||||
|
||||
#. On your computer, right-click the “Start” menu and select “Run”.
|
||||
|
||||
#. Type in “mmc” and click “OK”. When prompted on the “User Account Control” window, select “Yes” to allow this program to run.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/1_windows_mmc.png
|
||||
:width: 90%
|
||||
:alt: Windows MMC
|
||||
|
||||
Access the Windows Management Console
|
||||
|
||||
#. When the Management Console opens, navigate to *File > Add/Remove Snap-in*.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/2_windows_console_root.png
|
||||
:width: 90%
|
||||
:alt: Windows Console Root
|
||||
|
||||
Add Snap-in from Console Root
|
||||
|
||||
#. Select “Certificates” in the left side menu, then “Add”. This will open another window.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/3_windows_add_certificates.png
|
||||
:width: 90%
|
||||
:alt: Add Certificates
|
||||
|
||||
Add Certificates to selected snap-ins
|
||||
|
||||
#. Select “Computer account” and click “Next. Leave defaulted options on the next screen and click “Finish”.
|
||||
|
||||
#. When you return to the “Add or Remove Snap-ins” page, ensure “Certificates (Local Computer)” exists under “Console Root” in the “Selected snap-ins” section, then click “OK”.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/4_windows_selected_snapin.png
|
||||
:width: 90%
|
||||
:alt: Snap-in Selected
|
||||
|
||||
Certificates (Local Computer) is selected as snap-in
|
||||
|
||||
#. In the left hand menu of the Management Console, navigate to Certificates (Local Computer) > Trusted Root Certification Authorities > Certificates.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/5_windows_trusted_certificate_menu.png
|
||||
:width: 90%
|
||||
:alt: Certificates in Management Console
|
||||
|
||||
Access Certificates in Management Console
|
||||
|
||||
#. Right click on “Certificates”, then navigate to *All Tasks > Import*.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/6_windows_import_cert.png
|
||||
:width: 90%
|
||||
:alt: Import certificate
|
||||
|
||||
Select "Import" from Certificates sub-menu
|
||||
|
||||
#. Click “Next” on the first page of the Certificate Import Wizard, then browse to the location where you saved the downloaded certificate and click “Open”.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/7_windows_import_cert_wizard.png
|
||||
:width: 90%
|
||||
:alt: Import cert wizard
|
||||
|
||||
Add downloaded certificate int he Certificate Import Wizard
|
||||
|
||||
#. On the “Certificate Store” window, ensure that it says “Trusted Root Certificate Authorities” and click “Next”.
|
||||
|
||||
#. Select “OK” when the import is successful.
|
||||
|
||||
#. Verify the Embassy Local Root CA certificate is in the “Certificates” folder.
|
||||
|
||||
.. figure:: /_static/images/ssl/windows/8_windows_successful_cert_install.png
|
||||
:width: 90%
|
||||
:alt: Successful cert install
|
||||
|
||||
Embassy Local Root CA imported into Certificate folder
|
||||
|
||||
#. You can save the settings to the console if desired or cancel.
|
||||
|
||||
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <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>`.
|
||||
@@ -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,86 +0,0 @@
|
||||
******
|
||||
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!
|
||||
|
||||
iOS
|
||||
====
|
||||
|
||||
#. Navigate back to the `Start9 Setup App <https://apps.apple.com/us/app/start9-setup-app/id1528125889>`_.
|
||||
|
||||
#. Select your claimed Embassy to view the setup results.
|
||||
|
||||
#. Find the "LAN (advanced)" menu item at the bottom of the Setup App screen.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_setup_app_complete.png
|
||||
:width: 70%
|
||||
:alt: Setup app complete
|
||||
|
||||
Completed Setup App screen
|
||||
|
||||
#. Select the "Embassy Local Root CA" menu item. Clicking this will prompt you to “Save to device”.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_setup_app_advanced.png
|
||||
:width: 70%
|
||||
:alt: Setup app advanced menu
|
||||
|
||||
Setup App advanced menu
|
||||
|
||||
#. You will be directed to a page in your default browser indicating next steps and that the profile has been successfully downloaded.
|
||||
|
||||
.. note::
|
||||
If you have changed the default browser from Safari to Brave, the following auto save certificate to device flow will *not* work. Safari, Firefox, and Chrome work as expected. We recommend you temporarily use one of these browsers to complete this action.
|
||||
|
||||
#. Be sure to complete all steps in this process! These steps are also outlined below.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_certificate_install_page.png
|
||||
:width: 70%
|
||||
:alt: Certificate install page
|
||||
|
||||
Select "Allow" on the certificate install page
|
||||
|
||||
#. Go to Settings on your iOS device.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_ipad_general_settings.png
|
||||
:width: 70%
|
||||
:alt: General settings
|
||||
|
||||
General settings
|
||||
|
||||
#. Navigate to *General > Profile(s) > Downloaded Profile > Install*.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_ipad_profiles.png
|
||||
:width: 70%
|
||||
:alt: Profiles
|
||||
|
||||
Profiles view
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_ipad_install_profile.png
|
||||
:width: 70%
|
||||
:alt: Install profile
|
||||
|
||||
Select "Install" for Embassy Local Root CA
|
||||
|
||||
#. Select “yes” to any warning prompts.
|
||||
|
||||
#. Next, navigate to *General > About > Certificate Trust Settings*.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_ipad_cert_trust_settings.png
|
||||
:width: 70%
|
||||
:alt: Certificate trust settings
|
||||
|
||||
Select Certificate Trust Settings (scroll all the way down)
|
||||
|
||||
#. Enable full trust for root certificates.
|
||||
|
||||
.. figure:: /_static/images/ssl/mobile/ssl_ipad_cert_trust.png
|
||||
:width: 70%
|
||||
:alt: Enable full trust
|
||||
|
||||
Toggle to enable full trust for root certificates. "Continue" when warning prompts.
|
||||
|
||||
#. Test that this process worked successfully by navigating to the LAN address provided in the Setup App. You should no longer see warnings about the security of this site in your browser. We recommend using Start9’s own `Consulate browser <https://apps.apple.com/us/app/consulate/id1528124570>`_ for a faster and better experience.
|
||||
@@ -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.
|
||||
@@ -1,19 +0,0 @@
|
||||
***************
|
||||
Setting up WiFi
|
||||
***************
|
||||
|
||||
#. Click "WiFi".
|
||||
#. Click the ``+`` button in the lower right corner.
|
||||
#. Select the appropriate country.
|
||||
#. Enter your WiFi SSID and password.
|
||||
|
||||
.. figure:: /_static/images/embassy_wifi.png
|
||||
:width: 90%
|
||||
:alt: Add WiFi
|
||||
|
||||
Add WiFi Network options
|
||||
|
||||
#. 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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user