diff --git a/site/03-todo.md b/site/03-todo.md index d8453fc..917a4e7 100644 --- a/site/03-todo.md +++ b/site/03-todo.md @@ -1,20 +1,15 @@ # TODO - CIFS/LAN OS guides (screens) -- Add / verify ALL links in the **UI** go to the right place in docs - Fontawesome - Tor box (connecting) needs icon - device guides need OS icons -- Initial Setup +- Initial Setup Video - Lightning Guides (Zeus) - Vaultwarden guide (screens) - Refactor and update Roadmap - -# BLOCKED: -- Possible sounds in troubleshooting (and overview / update migrate with links) -- Alt Market Build Guide +- BLOCKED: Possible sounds in troubleshooting (and link in overview / upgrade pages) # AFTER PUBLISHING: -- Close all relevant issues (some await new processes in order to test) -- Add new video content +- Add any new video content - Breakout Bitcoin / Lightning integrations into their own individual pages - Create badges for device guide topic boxes -- Connecting LAN/Tor nesting isn't great - Migrate from other server projects / nodes (currently punted) +- Alt Market Build Guide (punted) diff --git a/site/source/_static/logo.png b/site/source/_static/logo.png index 63e10bd..0d0382a 100644 Binary files a/site/source/_static/logo.png and b/site/source/_static/logo.png differ diff --git a/site/source/conf.py b/site/source/conf.py index 04156d2..d5bfc81 100644 --- a/site/source/conf.py +++ b/site/source/conf.py @@ -95,7 +95,7 @@ html_theme_options = { "conf_py_path": "site/source/", "banner_button_text": "Learn more", "banner_button_url": "https://docs.start9.com/latest", - "banner_title_text": "EmbassyOS 0.3.0 is now released 🥳", + "banner_title_text": "EmbassyOS 0.3.0 is now available 🥳", "hide_banner": "false", "hide_edit_this_page_button": "false", "hide_sidebar_index": "true", diff --git a/site/source/diy.rst b/site/source/diy.rst new file mode 100644 index 0000000..254462f --- /dev/null +++ b/site/source/diy.rst @@ -0,0 +1,86 @@ +.. _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 several 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. + +Hardware +-------- + +The first thing you'll need to do is gather the hardware and assemble it. + +Parts +..... + +* `Raspberry Pi 4B (8GB) `_ +* `Power supply for Raspberry Pi 4B `_ Make sure this is at minimum 15w and 3.5a. +* Case for Raspberry Pi 4B (`passive cooling `_ is recommended). This means no moving parts and no noise. + + .. warning:: If you prefer to 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 `_. + +* A `16GB microSD card `_ (no need for bigger). +* `GPIO mini speaker/buzzer `_ (These often sell out, please let us know if this link needs to be refreshed) +* Ethernet cable +* MicroSD to USB adapter (or you may have a microSD port on your computer) +* SSD (minimum 1TB) that `connects over USB 3.0` This can be an `external drive `_, or an `internal drive `_ with an `USB enclosure `_. Currently the only tested and supported external drives are the Samsung T5 and T7 + +Assembly +........ + +#. 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 +----------------- + +After building your device, you need a copy of EmbassyOS. + +* **Purchasing from Start9** - You can purchase a copy of EmbassyOS `here `_. This is by far the easiest path to get up and running. + +* **Building from Source** - If you prefer to build EmbassyOS from source, Following `this guide `_. + +Installing EmbassyOS +-------------------- + +Whether you purchase EmbassyOS from us or build it yourself, you'll need to flash it onto a microSD card. + +#. Download `balenaEtcher `_ onto your Mac, Windows, or Linux computer. +#. Insert the microSD card into your computer, either directly or using an adapter. +#. Open balenaEtcher. + + .. figure:: /_static/images/diy/balena.png + :width: 60% + :alt: Balena Etcher Dashboard + +#. Click "Select Image" and select your downloaded copy of EmbassyOS. +#. Click "Select Target" and select your 16GB microSD card. + + .. warning:: Be certain you have selected the correct target microSD card. Whatever target you select will be completely erased and replaced with EmbassyOS. + +#. Click "Flash!". You may be asked to (1) approve the unusually large disk target or (2) enter your password. Both are normal. +#. After the flash completes, you may remove the micro SD, insert it into your Embassy, and continue to the :ref:`Initial Setup ` instructions. diff --git a/site/source/index.rst b/site/source/index.rst index 0eeca28..02cb923 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -10,7 +10,7 @@ :button_text: Purchase Embassy :image: /_static/img/eos_0.3.0.png - Here you will find information about Start9, EmbassyOS, and the era of sovereign computing. + Here you will find information about Start9, EmbassyOS, and the era of sovereign computing. Anyone can do it. No one can stop it. .. raw:: html @@ -33,7 +33,7 @@ .. topic-box:: :title: DIY - :link: user-manual/misc-guides/diy + :link: diy :icon: scylla-icon scylla-icon--integrations :class: large-4 :anchor: Get started @@ -116,6 +116,9 @@ :maxdepth: 3 :hidden: + Purchase + diy + Marketplace user-manual/index support/index learn/index diff --git a/site/source/learn/concepts/embassy.rst b/site/source/learn/concepts/embassy.rst index f57309a..315fd8f 100644 --- a/site/source/learn/concepts/embassy.rst +++ b/site/source/learn/concepts/embassy.rst @@ -38,7 +38,7 @@ The server-side software available on EmbassyOS are referred to as "Services." Session ------- -A session is simply a logged-in connection to your Embassy. You can view your :ref:`Active Sessions`, and kill one if you suspect it is not legitimate, or no longer use it. +A session is simply a logged-in connection to your Embassy. You can view your :ref:`Active Sessions`, and kill one if you suspect it is not legitimate, or no longer use it. .. _service-container: @@ -72,7 +72,7 @@ In EmbassyOS versions 0.2.x, each installed service received its own Tor hidden Certain services, such as Bitcoin, actually have multiple interfaces. Bitcoin has an RPC interface, a P2P interface, and could potentially even have a graphical interface, such as a dashboard displaying important node information. Using the same URL for these various interfaces is not only confusing, it could potentially pose a security vulnerability. For example, a user may want to share their P2P interface address with someone for peering but not want to give out their UI address, which is for private use only. -As such, EmbassyOS 0.3.0 permits services to have multiple interfaces, each receiving its own Tor address and/or LAN address. Users can then view and access all interfaces for a given service inside the new :ref:`Interfaces ` section of the service dashboard. +As such, EmbassyOS 0.3.0 permits services to have multiple interfaces, each receiving its own Tor address and/or LAN address. Users can then view and access all interfaces for a given service inside the "Interfaces" section of the service dashboard. .. _health-checks: diff --git a/site/source/learn/concepts/networks.rst b/site/source/learn/concepts/networks.rst index 2577477..829f9c3 100644 --- a/site/source/learn/concepts/networks.rst +++ b/site/source/learn/concepts/networks.rst @@ -14,7 +14,7 @@ Devices on a LAN are private and protected, such that only devices connected to Your Embassy hosts itself on the LAN and is reachable by visiting its ``embassy.local`` URL in the browser while also connected to the LAN. -.. note:: Any device connected to a LAN can inspect all communications on that LAN. To avoid snooping, your Embassy's LAN communications are encrypted using :ref:`ssl`, which requires :ref:`additional setup `. +.. note:: Any device connected to a LAN can inspect all communications on that LAN. To avoid snooping, your Embassy's LAN communications are encrypted using :ref:`ssl`, which requires :ref:`additional setup `. .. _lan-cert: @@ -50,7 +50,7 @@ We decided to have the Embassy act as a Certificate Authority. It creates a self When you setup SSL for your Embassy and device, the certificate communicates to the client (a browser) that the server (the Embassy) demonstrated ownership of the domain (the ``embassy-xxxxxxxx.local`` address) to the certificate authority (created on the Embassy) at the time of certificate issuance (during the setup process). The Embassy dashboard can then be accessed from a home network (LAN) using a secure HTTPS connection! -For more information on how to setup your devices to enable this feature visit :ref:`lan-setup`. +For more information on how to setup your devices to enable this feature visit :ref:`connecting-lan`. .. _tor: diff --git a/site/source/support/faq/faq-general.rst b/site/source/support/faq/faq-general.rst index bfc658e..0e8f1f4 100644 --- a/site/source/support/faq/faq-general.rst +++ b/site/source/support/faq/faq-general.rst @@ -62,7 +62,7 @@ It includes: * a custom application management layer, specialized for installing, running, and backing up .s9pk packaged services * a layer responsible for Embassy specific operations, such as Tor, Backups, and Notifications * a system of :ref:`Health Checks` for simple monitoring -* an SDK for developers, including an :ref:`Actions API` to simplify complex operations for the common user +* an SDK for developers, including an "Actions" API to simplify complex operations for the common user * and much, much more. Please see the corresponding :ref:`Concepts` section. The .s9pk extension is Start9's custom package format based on tar. It encompasses the necessary components to compress, host, and install a service on a Marketplace. diff --git a/site/source/support/faq/faq-troubleshooting.rst b/site/source/support/faq/faq-troubleshooting.rst index cea6c62..a49fd62 100644 --- a/site/source/support/faq/faq-troubleshooting.rst +++ b/site/source/support/faq/faq-troubleshooting.rst @@ -32,7 +32,7 @@ This is most likely a transient networking issue that will correct itself in a f 1. On Android/Orbot, the most common solution is to restart your Android device. -2. Access your Embassy over :ref:`LAN `, and restart it from the "Embassy" menu. +2. Access your Embassy over :ref:`LAN `, and restart it from the "Embassy" menu. 3. Restart your router. diff --git a/site/source/support/troubleshooting/shoot-connection.rst b/site/source/support/troubleshooting/shoot-connection.rst index 0711cb5..916a39e 100644 --- a/site/source/support/troubleshooting/shoot-connection.rst +++ b/site/source/support/troubleshooting/shoot-connection.rst @@ -12,7 +12,7 @@ If you still cannot connect, you can log into your router (the directions for wh I am unable to reach Embassy via it's ``embassy-xxxxxxxx.local`` (LAN) address ------------------------------------------------------------------------------ -Make sure you have successfully followed the :ref:`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`, lack the ability at an OS level. +Make sure you have successfully followed the :ref:`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`, lack the ability at an OS level. I am unable to reach Embassy via it's ``xxxxxxxxxxxxxxxxxx.onion`` (Tor) address -------------------------------------------------------------------------------- diff --git a/site/source/user-manual/alt-marketplaces.rst b/site/source/user-manual/alt-marketplaces.rst index bfa55df..0262ba9 100644 --- a/site/source/user-manual/alt-marketplaces.rst +++ b/site/source/user-manual/alt-marketplaces.rst @@ -4,14 +4,12 @@ Alt Marketplaces ================ -It is critical to Start9's mission that Start9 NOT be a central point of failure. The Marketplace is a critical piece of infrastructure and therefore EmbassyOS supports accessing alternative marketplaces. +It is critical to Start9's mission that Start9 is **not** a central point of failure. The Marketplace is a critical piece of infrastructure and therefore EmbassyOS supports accessing alternative marketplaces. -.. caution:: Start9 is not responsible for issues encountered when downloading services from alternative marketplaces, and cannot provide support for services that are not from our offical marketplace. Here be dragons!! +.. caution:: Start9 is not responsible for issues encountered when downloading services from alternative marketplaces, and cannot provide support for services that are not from our official marketplace. Here be dragons!! -.. note:: Currently this change will allow you to download services from a Marketplace of your choice. At this time, EmbassyOS updates on alternative Marketplaces are not supported. +.. note:: Currently this change will only permit the downloading of *services* from alternative marketplaces. EmbassyOS itself may only be obtained from Start9. -#. Go to Embassy -> Marketplace Settings +#. Go to *Embassy > Marketplace Settings*. -#. Click "Add Alternative Marketplace" and enter the URL of your desired Marketplace. You may connect immediately, or save for use later - -.. note:: Make sure you have the URL **EXACTLY CORRECT.** If you do not, your Embassy may crash. In this case, just reboot the device and try again. +#. Click "Add Alternative Marketplace" and enter the URL of your desired Marketplace. You may connect immediately, or save for later use. diff --git a/site/source/user-manual/backups/backup-create.rst b/site/source/user-manual/backups/backup-create.rst index 19d9751..3867395 100644 --- a/site/source/user-manual/backups/backup-create.rst +++ b/site/source/user-manual/backups/backup-create.rst @@ -1,44 +1,41 @@ .. _backup-create: -================ -Creating Backups -================ +============= +Backup Create +============= -There are 2 options for backing up your Embassy and service data: +Backing up your Embassy is easy and secure. Backups are encrypted with your master password. -1. Use a Shared Network Folder (recommended) on another device that connected to the same network as your Embassy, such as a laptop/desktop or external drive that is plugged into your laptop/desktop. -2. Use a physical drive, which must be externally powered or plugged into a powered USB hub. +Backup Using LAN Shared Folder +------------------------------ -LAN Backups ------------ +.. tip:: This is the recommended approach for creating backups. -This is the recommended approach for creating backups. +#. Follow instructions for creating a :ref:`LAN Shared Folder` on your laptop/desktop. -#. Follow instructions for creating a :ref:`Shared Network Folder` on your laptop/desktop. - -#. Go to the :ref:`Embassy tab`, then click on ``Create Backup``. +#. Go to *Embassy > Create Backup*. .. figure:: /_static/images/config/embassy_backup.png :width: 60% -#. Next, click on ``+ New Shared Folder`` to use your previously created backup folder. +#. Next, click on "New Shared Folder". .. figure:: /_static/images/config/embassy_backup0.png :width: 60% #. Fill in the following fields: - * Hostname - This is the hostname of the machine that your folder or drive is located on - * Path - This is the directory path to the shared folder. If you configured Samba yourself (Linux), this is the ``comment`` (name of the share in your samba config file) and not the path. + * Hostname - This is the hostname of the machine that your shared folder is located on + * Path - This is the directory path to the shared folder. If you configured Samba yourself (Linux), this is the "comment" (name of the share in your samba config file) and not the path. * Username - This is the user on the remote machine that you used to create the shared directory * Password - This is your user (from above) password .. figure:: /_static/images/config/embassy_backup1.png :width: 60% - Then click ``Save`` +#. Click "Save". -#. You will see a freshly created "cloud" backup location available, click it for options, and click ``Create Backup`` to begin. +#. You will see a freshly created "cloud" backup location available, click it, then click "Create Backup". .. figure:: /_static/images/config/embassy_backup2.png :width: 60% @@ -48,26 +45,28 @@ This is the recommended approach for creating backups. .. figure:: /_static/images/config/embassy_backup3.png :width: 60% -#. When the backup is complete you will be notified in the :ref:`Notifications tab`, and you will see the date and time of your most recent backup updated under ``Backups`` in the Embassy tab. +#. When the backup is complete you will receive a notification in the Notifications tab, and you will see the date and time of your most recent backup updated under "Backups" in the Embassy tab. .. figure:: /_static/images/config/embassy_backup4.png :width: 60% -Physical Backups ----------------- +Backup Using a Physical Drive +----------------------------- -You may use a drive by attaching to Embassy directly if you prefer. The recommended format at this time is ``exFAT``. +.. tip:: You can backup to a physical drive using the recommended method above, rather than plugging the drive directly into the Embassy, which can cause problems. .. caution:: If using the Raspberry Pi, you MUST use external power to attach a physical drive in order to prevent any data corruption due to power constraints. -#. First, go to ``Embassy`` -> ``Create Backup`` +#. Ensure your backup drive is properly formatted. The recommended format at this time is ``exFAT``. **Do not** use ``fat32``. + +#. If your drive is self-powered, you can plug it directly into your Embassy blue USB 3.0 slot. If not, first plug the drive into a powered USB hub, then plug the hub into your Embassy. Then you may power it up. + +#. Go to *Embassy > Create Backup* .. figure:: /_static/images/config/physical-backup0.png :width: 60% -#. Plug drive USB cable into Embassy. If your drive is self-powered, you can plug it directly into your Embassy USB 3.0 (blue) slot. If not, first plug the drive into a powered USB hub, then plug the hub into your Embassy USB 3.0 slot. Then you may power it up. - -#. Press ``Refresh`` in the top-right corner, and select your drive when it appears. +#. Select your drive. .. figure:: /_static/images/config/physical-backup1.png :width: 60% @@ -75,7 +74,7 @@ You may use a drive by attaching to Embassy directly if you prefer. The recomme .. figure:: /_static/images/config/physical-backup2.png :width: 60% -#. Enter your password to continue with the backup. +#. Enter your EmbassyOS master password. .. figure:: /_static/images/config/physical-backup3.png :width: 60% diff --git a/site/source/user-manual/backups/backup-restore.rst b/site/source/user-manual/backups/backup-restore.rst index b17feae..25c3e9d 100644 --- a/site/source/user-manual/backups/backup-restore.rst +++ b/site/source/user-manual/backups/backup-restore.rst @@ -1,30 +1,25 @@ .. _backup-restore: -=================== -Restore From Backup -=================== +============== +Backup Restore +============== -#. First, go to ``Embassy`` -> ``Restore From Backup``. +#. Go to *Embassy > Restore From Backup*. .. figure:: /_static/images/config/restore0.png :width: 60% -#. Select existing backup from either LAN or Physical. In this example, we'll select a LAN backup. +#. Select existing backup from either LAN or Physical. In this example, we'll select a LAN backup. .. figure:: /_static/images/config/restore1.png :width: 60% -#. Click ``Restore Backup`` and enter your Embassy password. +#. Click "Restore Backup" and enter your master password. .. figure:: /_static/images/config/restore2.png :width: 60% -#. Services that are available in the backup, and not already installed on your Embassy, will show in the following window. Select the service(s) you'd like to restore and click ``Restore Selected``. In the example, we'll be restoring 2 services from the available options. +#. Services that are available in the backup, and not already installed on your Embassy, will show in the following window. Select the service(s) you'd like to restore and click "Restore Selected". .. figure:: /_static/images/config/restore3.png :width: 60% - -#. That's it! The selected services will now install. After install, simply :ref:`configure` and start the service. - - .. figure:: /_static/images/config/restore4.png - :width: 60% diff --git a/site/source/user-manual/backups/cifs-setup/cifs-linux.rst b/site/source/user-manual/backups/cifs-setup/cifs-linux.rst index f9129f5..668ddfe 100644 --- a/site/source/user-manual/backups/cifs-setup/cifs-linux.rst +++ b/site/source/user-manual/backups/cifs-setup/cifs-linux.rst @@ -1,10 +1,8 @@ .. _cifs-linux: -===== -Linux -===== - -The following will guide you through the prerequisite configuration to backup to a Linux machine or an external drive that is attached to a Linux machine. +===================================== +Creating a LAN Shared Folder on Linux +===================================== .. tabs:: diff --git a/site/source/user-manual/backups/cifs-setup/cifs-mac.rst b/site/source/user-manual/backups/cifs-setup/cifs-mac.rst index ab690c0..83ef6aa 100644 --- a/site/source/user-manual/backups/cifs-setup/cifs-mac.rst +++ b/site/source/user-manual/backups/cifs-setup/cifs-mac.rst @@ -1,10 +1,8 @@ .. _cifs-mac: -=== -Mac -=== - -The following will guide you through the prerequisite configuration to backup to a Mac machine or an external drive that is attached to a Mac machine. +=================================== +Creating a LAN Shared Folder on Mac +=================================== #. Go to system settings diff --git a/site/source/user-manual/backups/cifs-setup/cifs-synology.rst b/site/source/user-manual/backups/cifs-setup/cifs-synology.rst index 54d06d1..86984e3 100644 --- a/site/source/user-manual/backups/cifs-setup/cifs-synology.rst +++ b/site/source/user-manual/backups/cifs-setup/cifs-synology.rst @@ -1,22 +1,17 @@ .. _cifs-synology: -======== -Synology -======== +======================================== +Creating a LAN Shared Folder on Synology +======================================== .. note:: This guide was created by a Start9 community member. This is not yet officially supported. Please report any feedback that may help improve the process. -The following will guide you through the prerequisite configuration to backup to a Synology NAS device. +#. In Synology UI, go to *Control Panel > Shared Folder* and select the folder you want to use. Click "Permissions" and make sure you have read/write permissions for the user you're going to be logging in as. Click "Save". -#. Go to the Synology UI > Control Panel > Shared Folder > select the folder you want to use > Permissions tab > make sure that you have read/write permissions for the user you're going to be logging in as > Save - -#. Then go to the Synology UI > Control Panel > File Services > SMB Tab > Click the SMB drop down button if it isn't already selected > Ensure that "Enable SMB service" is checked. +#. Back in Synology UI, go to *Control Panel > File Services > SMB* and click the SMB drop down button if it isn't already selected. Ensure that "Enable SMB service" is checked. .. note:: Under Advanced Settings on the same dropdown, "Min SMB protocol" was set to SMB2 and "Max SMB protocol set to SMB3" - this may or may not be necessary -#. On the same dropdown, under "Note" will be "PC (Windows Explorer): \". This DeviceAddressName is the "Hostname" within the Embassy New Shared Folder dialog, and note that it is case sensitive and that the \ have been removed. - -#. Go to Synology UI > File Station > navigate so that you can see the the desired destination folder > right click on it > Properties > General Tab, next to Location: will be an folder location of the format ///, the / portion (so without the volume label) is the "Path" within the Embassy New Shared Folder dialog. - -#. Fill in the Username and Password appropriately for the previously checked user. +#. In the same dropdown, under "Note" will be "PC (Windows Explorer): \". This DeviceAddressName is the "Hostname" within the Embassy New Shared Folder dialog, and note that it is case sensitive and that the \ have been removed. +#. Back in Synonogy UI, click "File Station" and navigate so that you can see the the desired destination folder. Right click the folder, then *Properties > General*. Next to "Location" will be a folder location of the format ///, the / portion (so without the volume label) is the "Path" within the Embassy New Shared Folder dialog. \ No newline at end of file diff --git a/site/source/user-manual/backups/cifs-setup/cifs-windows.rst b/site/source/user-manual/backups/cifs-setup/cifs-windows.rst index b02ebf5..73c2c5c 100644 --- a/site/source/user-manual/backups/cifs-setup/cifs-windows.rst +++ b/site/source/user-manual/backups/cifs-setup/cifs-windows.rst @@ -1,10 +1,8 @@ .. _cifs-windows: -======= -Windows -======= - -The following will guide you through the prerequisite configuration to backup to a Windows machine or an external drive that is attached to a Windows machine. +======================================= +Creating a LAN Shared Folder on Windows +======================================= #. Create a folder diff --git a/site/source/user-manual/backups/cifs-setup/index.rst b/site/source/user-manual/backups/cifs-setup/index.rst index e537931..b835eb4 100644 --- a/site/source/user-manual/backups/cifs-setup/index.rst +++ b/site/source/user-manual/backups/cifs-setup/index.rst @@ -1,15 +1,15 @@ .. _cifs-setup: -======================= -LAN Shared Folder Setup -======================= +============================ +Creating a LAN Shared Folder +============================ -Click your platform for detailed instructions on how to create a Shared Network Folder on your local network (:ref:`LAN`). +Click your platform for detailed instructions on how to create a LAN Shared Folder for creating backups. .. toctree:: :maxdepth: 2 - cifs-linux - cifs-mac - cifs-windows - cifs-synology + Linux + Mac + Windows + Synonogy diff --git a/site/source/user-manual/backups/index.rst b/site/source/user-manual/backups/index.rst index 9fef502..093e071 100644 --- a/site/source/user-manual/backups/index.rst +++ b/site/source/user-manual/backups/index.rst @@ -13,7 +13,7 @@ In addition to safekeeping of a good master password, maintaining good backups a
.. topic-box:: - :title: Create + :title: Create Backup :link: backup-create :icon: scylla-icon scylla-icon--memory-management :class: large-5 @@ -22,7 +22,7 @@ In addition to safekeeping of a good master password, maintaining good backups a Create an encrypted backup of Embassy. .. topic-box:: - :title: Restore + :title: Restore from Backup :link: backup-restore :icon: scylla-icon scylla-icon--comparison :class: large-5 diff --git a/site/source/user-manual/connecting/connecting-lan/index.rst b/site/source/user-manual/connecting/connecting-lan/index.rst new file mode 100644 index 0000000..85be29b --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/index.rst @@ -0,0 +1,50 @@ +.. _connecting-lan: + +=================== +Connecting Over LAN +=================== + +Whenever you are connected the same Local Area Network (LAN) as your Embassy (i.e. the same WiFi network), it is best to access your Embassy's LAN Address (.local URL). LAN connections are fast and secure and do not even require Internet access! + +.. note:: Your Embassy creates its own Certificate Authority (CA) to establish trust with client devices. + +Download Root CA +---------------- + +First, download your Embassy's Root CA. There are two way to accomplish this: + +Option 1 +........ + +Download it from html page you saved at the completion of :ref:`Initial Setup`. + +Option 2 +........ + +visit your Embassy over :ref:`Tor` and navigate to *Embassy > LAN*, then click "Download". + + .. figure:: /_static/images/ssl/embassy_lan_setup.png + :width: 60% + :alt: LAN setup menu item + +Trust Root CA +------------- + +First instruct your **operating system** to trust your Embassy's Root CA. + + .. toctree:: + :maxdepth: 2 + + lan-os/index + +Then instruct your **browser** to trust your Embassy's Root CA. + + .. toctree:: + :maxdepth: 2 + + lan-browser/index + +Access your Embassy LAN Address +------------------------------- + +With the Root CA downloaded and trusted by both your operating system and your browser, you can now visit your Embassy's LAN Address (.local URL) over secure https. Any service that offers a LAN URL will also be securely accessible! \ No newline at end of file diff --git a/site/source/user-manual/connecting/connecting-lan/lan-browser/index.rst b/site/source/user-manual/connecting/connecting-lan/lan-browser/index.rst new file mode 100644 index 0000000..7be8155 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-browser/index.rst @@ -0,0 +1,17 @@ +.. _lan-browser: + +================== +Trust CA - Browser +================== + +Instruct your **browser** to trust your Embassy's Root CA. + +.. caution:: You will first need to complete :ref:`lan-os` for your device before continuing. + +.. toctree:: + :maxdepth: 1 + + Firefox + Brave + Chrome + Safari diff --git a/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-brave.rst b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-brave.rst new file mode 100644 index 0000000..c8287b7 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-brave.rst @@ -0,0 +1,33 @@ +.. _lan-brave: + +========================= +Trust Embassy CA in Brave +========================= + +.. caution:: You will first need to complete :ref:`lan-os` for your device before continuing. + +#. Open a new tab in Brave and open to "Settings" from the top-right hamburger menu. + + .. figure:: /_static/images/ssl/browser/brave_settings.png + :width: 30% + :alt: Brave settings page + +#. On the left hand sidebar, select the "Security and Privacy" section, then the "Security" menu item. + + .. figure:: /_static/images/ssl/browser/brave_security.png + :width: 60% + :alt: Brave Security and Privacy settings + +#. At the bottom of the section, select "Manage Certificates". + + .. figure:: /_static/images/ssl/browser/brave_security_settings.png + :width: 60% + :alt: Brave Security settings page + +#. If you see "org-Start9" with a trusted “Embassy Local Root CA” listed under it, open a new tab to apply the certificate. If this does not work, quit and restart Brave. + +#. If you do not see "org-Start9" in the list, click "Import" and open the downloaded "Embassy Local Root CA.crt" file on your device. Check the box for "Trust this certificate for identifying websites" and click "OK". + + .. figure:: /_static/images/ssl/browser/brave_view_certs.png + :width: 60% + :alt: Brave Manage Certificates sub-menu on MacOS diff --git a/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-chrome.rst b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-chrome.rst new file mode 100644 index 0000000..4d79552 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-chrome.rst @@ -0,0 +1,33 @@ +.. _lan-chrome: + +============================= +Trusting Embassy CA in Chrome +============================= + +.. caution:: You will first need to complete :ref:`lan-os` for your device before continuing. + +.. tip:: The following guide also works with Chromium and Vivaldi. + +#. Open a new tab in Chrome and visit *chrome://settings/certificates* in the URL bar. + + .. figure:: /_static/images/ssl/browser/chrome_settings.png + :width: 60% + :alt: Chrome Certificates Settings page + +#. Click on the "Authorities" tab. + + .. figure:: /_static/images/ssl/browser/chrome_authorities.png + :width: 60% + :alt: Chrome Certificate Authorities page + +#. If you see "org-Start9" with a trusted “Embassy Local Root CA” listed under it, open a new tab to apply the certificate. If this does not work, quit and restart Chrome. + + .. figure:: /_static/images/ssl/browser/chrome_s9ca.png + :width: 60% + :alt: Start9 Certificate Authority + +#. If you do not see "org-Start9"in the list, click “Import” and open the downloaded "Embassy Local Root CA.crt" file on your device. Check the box for "Trust this certificate for identifying websites" and click "OK" + + .. figure:: /_static/images/ssl/browser/chrome_trust.png + :width: 60% + :alt: Trust the CA diff --git a/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-ff.rst b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-ff.rst new file mode 100644 index 0000000..a3aeff3 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-ff.rst @@ -0,0 +1,48 @@ +.. _lan-ff: + +============================== +Trusting Embassy CA in Firefox +============================== + +.. caution:: You will first need to complete :ref:`lan-os` for your device before continuing. + +Linux/Mac/Windows +----------------- + +#. Open Firefox and in a new tab select "Settings" from the right-hand hamburger menu: + + .. figure:: /_static/images/tor/os_ff_settings.png + :width: 30% + :alt: Firefox options screenshot + +#. Select “Privacy and Security” from the left hand navigation menu. + +#. Scroll all the way to the bottom of the page and select “View Certificates”. + + .. figure:: /_static/images/ssl/browser/firefox_security_settings.png + :width: 80% + :alt: Firefox security settings + +#. Select the "Authorities" tab from the "Certificate Manager". + +#. Click "Import" and open the downloaded "Embassy Local Root CA.crt" file on your device. + +#. When prompted, check "Trust this CA to identity websites" and select “OK”. + + .. figure:: /_static/images/ssl/browser/firefox_view_certs.png + :width: 80% + :alt: Firefox import cert + +#. Ensure the "Embassy Local Root CA" exists under "Start9 Labs". If it does not appear, you may need to close the Certificates pop-up and re-open to refresh the list. Then click “OK” to save. + +#. Open a new tab in Firefox to apply the changes. If this does not work, quit and restart Firefox. + +Android +------- + +#. To setup in Firefox Beta or Fennec, go to *Settings > About Firefox Beta* and tap the Firefox logo several times until it says "Debug menu enabled." Then return to *Settings > Secret Settings* and enable "Use third party CA certificates". + +iOS +--- + +No additional configuration for iOS is required. diff --git a/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-safari.rst b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-safari.rst new file mode 100644 index 0000000..fdb1691 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-browser/lan-safari.rst @@ -0,0 +1,7 @@ +.. _lan-safari: + +============================= +Trusting Embassy CA In Safari +============================= + +Once you have completed the :ref:`lan-os` steps on your device, simply open a new tab to apply the changes. If this does not work, quit and restart Safari. You can now securely navigate to the LAN address for your Embassy! diff --git a/site/source/user-manual/connecting/connecting-lan/lan-os/index.rst b/site/source/user-manual/connecting/connecting-lan/lan-os/index.rst new file mode 100644 index 0000000..68e91d6 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-os/index.rst @@ -0,0 +1,16 @@ +.. _lan-os: + +============= +Trust CA - OS +============= + +Instruct your **operating system** to trust your Embassy's Root CA. + +.. toctree:: + :maxdepth: 2 + + Linux + Mac + Windows + Android/Graphene/Calyx + iOS diff --git a/site/source/user-manual/connecting/connecting-lan/lan-os/lan-android.rst b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-android.rst new file mode 100644 index 0000000..b05765a --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-android.rst @@ -0,0 +1,13 @@ +.. _lan-android: + +============================== +Trusting Embassy CA on Android +============================== + +.. warning:: This is only possible on Android 12+, which is not yet available on Graphene/Calyx. + +#. On your Android device, go to *Settings > Security > Advanced > Encryption and Credentials > Install from Storage* and select your "Embassy Local Root CA" certificate. + + .. figure:: /_static/images/ssl/android/droidLAN0.png + :width: 30% + :alt: Install certificate diff --git a/site/source/user-manual/connecting/connecting-lan/lan-os/lan-ios.rst b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-ios.rst new file mode 100644 index 0000000..f36b5d8 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-ios.rst @@ -0,0 +1,31 @@ +.. _lan-ios: + +========================== +Trusting Embassy CA on iOS +========================== + +#. On your iOS device, go to *Settings > General > Profiles*. Under "Downloaded Profile", click "Embassy Local Root CA" + + .. figure:: /_static/images/ssl/ios/ssl_ipad_profiles.png + :width: 40% + :alt: Profiles + +#. Click "Install" + + .. tip:: You can safely click ``Yes`` for any warning prompts. + + .. figure:: /_static/images/ssl/ios/ssl_ipad_install_profile.png + :width: 40% + :alt: Install profile + +#. Next, navigate to *General > About > Certificate Trust Settings*. + + .. figure:: /_static/images/ssl/ios/ssl_ipad_cert_trust_settings.png + :width: 40% + :alt: Certificate trust settings + +#. Under "Enable full trust for root certificates", enable "Embassy Local Root CA". + + .. figure:: /_static/images/ssl/ios/ssl_ipad_cert_trust.png + :width: 40% + :alt: Enable full trust diff --git a/site/source/user-manual/connecting/connecting-lan/lan-os/lan-linux.rst b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-linux.rst new file mode 100644 index 0000000..d012c82 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-linux.rst @@ -0,0 +1,7 @@ +.. _lan-linux: + +============================ +Trusting Embassy CA on Linux +============================ + +Nothing specific needs to be configured for the Linux environment. diff --git a/site/source/user-manual/connecting/connecting-lan/lan-os/lan-mac.rst b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-mac.rst new file mode 100644 index 0000000..bf83e53 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-mac.rst @@ -0,0 +1,35 @@ +.. _lan-mac: + +========================== +Trusting Embassy CA on Mac +========================== + +#. Locate your Embassy's Root CA, right click, then click *Open with > Keychain Access*. + + .. figure:: /_static/images/ssl/embassy_lan_setup1.png + :width: 60% + :alt: LAN setup prompt + +#. Enter your computer password when prompted. It will be imported into your mac's keychain. + + .. figure:: /_static/images/ssl/macos/certificate_untrusted.png + :width: 60% + :alt: Keychain access import menu + + .. note:: If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it. + +#. Navigate to the "System" tab on the left, find the certificate named "Embassy Local Root CA", and double click on this certificate. A second window will pop up. + +#. Open the "Trust" dropdown and select "Always Trust" from the dropdown next to "When using this certificate". + + .. figure:: /_static/images/ssl/macos/always_trust.png + :width: 60% + :alt: Keychain submenu + +#. Close this window and enter your password to apply the settings. + +#. The "Embassy Local Root CA" cert will now read "This certificate is marked as trusted for all users" in Keychain Access. + + .. figure:: /_static/images/ssl/macos/certificate_trusted.png + :width: 60% + :alt: Keychain menu trusted certificate diff --git a/site/source/user-manual/connecting/lan-setup/lan-os/lan-windows.rst b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-windows.rst similarity index 81% rename from site/source/user-manual/connecting/lan-setup/lan-os/lan-windows.rst rename to site/source/user-manual/connecting/connecting-lan/lan-os/lan-windows.rst index 7687628..ccfeab0 100644 --- a/site/source/user-manual/connecting/lan-setup/lan-os/lan-windows.rst +++ b/site/source/user-manual/connecting/connecting-lan/lan-os/lan-windows.rst @@ -1,37 +1,21 @@ .. _lan-windows: -======= -Windows -======= +============================== +Trusting Embassy CA On Windows +============================== -Unfortunately, Windows does not have mDNS support built-in, which is necessary in order to visit .local addresses, so we recommend using the Bonjour service. Check out this :ref:`FAQ answer` for details. +Unfortunately, Windows does not have mDNS support built-in, which is necessary in order to visit .local addresses, so we recommend using the Bonjour service. Check out this :ref:`FAQ answer` for details. #. Install `Bonjour Print Services `_ on your Windows machine. .. tip:: If you are experiencing issues after installing Bonjour, you might have had a previous or failed install. To fix: #. Check out this video: https://www.youtube.com/watch?v=9ECCB3bqNDQ - #. Uninstall Bonjour completely via ``system settings -> remove programs`` + #. Uninstall Bonjour completely via *system settings > remove programs* #. Reinstall Bonjour Printer Driver package (download at https://support.apple.com/kb/DL999?locale=en_US) #. Restart Windows #. Note: Uninstalling Bonjour via the setup package seems to be not enough to solve the issue. Bonjour must be uninstalled via windows system settings. -#. Visit your Embassy at its Tor Address. - - .. note:: Using this encrypted Tor connection is required for security reasons. - -#. Navigate to the :ref:`Embassy tab` -> Settings -> LAN - - .. figure:: /_static/images/ssl/embassy_lan_setup.png - :width: 90% - :alt: LAN setup menu item - -#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine. - - .. figure:: /_static/images/ssl/embassy_lan_setup0.png - :width: 90% - :alt: LAN setup page - #. Back in Windows, right-click the “Start” menu and select “Run”. #. Type in “mmc” and click “OK”. When prompted on the “User Account Control” window, select “Yes” to allow this program to run. @@ -105,5 +89,3 @@ Unfortunately, Windows does not have mDNS support built-in, which is necessary i 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 `. diff --git a/site/source/user-manual/connecting/connecting-tor/index.rst b/site/source/user-manual/connecting/connecting-tor/index.rst new file mode 100644 index 0000000..940001b --- /dev/null +++ b/site/source/user-manual/connecting/connecting-tor/index.rst @@ -0,0 +1,42 @@ +.. _connecting-tor: + +=================== +Connecting Over Tor +=================== + +You can connect to your Embassy from anywhere in the world, privately and anonymously, by using its unique Tor Address (.onion URL). + +.. note:: Tor connection can sometimes be unreliable and have higher latency than normal internet connections. + +Using a Tor Browser +------------------- + +The fastest, easiest way to connect to your Embassy over Tor is to download a Tor-enabled browser and visit your Embassy's .onion URL. We recommend: + +* Linux, Mac, Windows, Android + + * `Tor Browser `_ + * `Brave `_ (requires using Tor tabs) + +* iOS + + * `Onion Browser `_ + +Using Firefox +------------- + +.. tip:: This is recommended way to connect to your Embassy over Tor, but it requires some additional steps. + +#. Run Tor on your connecting device. + + .. toctree:: + :maxdepth: 2 + + tor-os/index + +#. Configure Firefox + + .. toctree:: + :maxdepth: 2 + + tor-firefox/index diff --git a/site/source/user-manual/connecting/tor-setup/tor-firefox/index.rst b/site/source/user-manual/connecting/connecting-tor/tor-firefox/index.rst similarity index 69% rename from site/source/user-manual/connecting/tor-setup/tor-firefox/index.rst rename to site/source/user-manual/connecting/connecting-tor/tor-firefox/index.rst index b7fbe1d..d920feb 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-firefox/index.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-firefox/index.rst @@ -4,15 +4,15 @@ Tor - Firefox ============= -.. caution:: This guide assumes you are already :ref:`running Tor on your phone or computer`. +.. caution:: This guide assumes you are already :ref:`running Tor on your phone or computer`. Once you have completed native :ref:`Tor Setup`, you can configure Firefox to use the Tor Network. This will allow you to visit both ``.onion`` and "normal" (.com, .net, etc) websites from within the same browser. .. toctree:: :maxdepth: 2 - torff-linux - torff-mac - torff-windows - torff-android - torff-ios + Linux + Mac + Windows + Android/Graphene/Calyx + iOS diff --git a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-android.rst b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-android.rst similarity index 95% rename from site/source/user-manual/connecting/tor-setup/tor-firefox/torff-android.rst rename to site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-android.rst index a5261fd..e497d3c 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-android.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-android.rst @@ -1,8 +1,8 @@ .. _torff-android: -======= -Android -======= +====================================== +Configuring Firefox for Tor on Android +====================================== .. caution:: This guide assumes you have completed :ref:`setting up Tor for Android`. Please visit this section before proceeding as it is required for Firefox to properly work with Tor. diff --git a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-ios.rst b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-ios.rst similarity index 67% rename from site/source/user-manual/connecting/tor-setup/tor-firefox/torff-ios.rst rename to site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-ios.rst index f0d0a32..24aacf2 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-ios.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-ios.rst @@ -1,7 +1,7 @@ .. _torff-ios: -=== -iOS -=== +================================== +Configuring Firefox for Tor on iOS +================================== Unforutnately, it is not currently possible to run Tor natively on iOS. This means that Firefox cannot be configured to use tor. Please see :ref:`iOS Limitations` for details and workarounds. diff --git a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-linux.rst b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-linux.rst similarity index 87% rename from site/source/user-manual/connecting/tor-setup/tor-firefox/torff-linux.rst rename to site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-linux.rst index d947d9b..fc23ccf 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-linux.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-linux.rst @@ -1,11 +1,11 @@ .. _torff-linux: -===== -Linux -===== +==================================== +Configuring Firefox for Tor on Linux +==================================== .. caution:: - This guide assumes you have completed :ref:`setting up Tor`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor. + This guide assumes you have completed :ref:`setting up Tor`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor. #. Open Firefox and enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings. diff --git a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-mac.rst b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-mac.rst similarity index 88% rename from site/source/user-manual/connecting/tor-setup/tor-firefox/torff-mac.rst rename to site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-mac.rst index f5ea9ba..f206d4d 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-mac.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-mac.rst @@ -1,11 +1,11 @@ .. _torff-mac: -=== -Mac -=== +================================== +Configuring Firefox for Tor on Mac +================================== .. caution:: - This guide assumes you have completed :ref:`setting up Tor`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor. + This guide assumes you have completed :ref:`setting up Tor`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor. #. Open Firefox and enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings. diff --git a/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-windows.rst b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-windows.rst new file mode 100644 index 0000000..82c913e --- /dev/null +++ b/site/source/user-manual/connecting/connecting-tor/tor-firefox/torff-windows.rst @@ -0,0 +1,52 @@ +.. _torff-windows: + +====================================== +Configuring Firefox for Tor on Windows +====================================== + +.. caution:: This guide assumes you have completed :ref:`setting up Tor`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor. + +#. Open Firefox and enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings. + +#. Search for ``dom.securecontext.whitelist_onions`` and set the value to "true". + + .. figure:: /_static/images/tor/firefox_whitelist.png + :width: 60% + :alt: Firefox whitelist onions screenshot + +#. Download a *Proxy Auto Config* file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file by following instructions below: + + - Click `here `_ to get the file and save the file somewhere you will not delete it. Remember where you save the file. For this example: + + .. code-block:: + + C:\Program Files\Tor Browser\proxy.pac + +#. Now, back in your Firefox web browser, select "Options" from the right-hand hamburger menu: + + .. figure:: /_static/images/tor/firefox_options_windows.png + :width: 60% + :alt: Firefox options screenshot + +#. Search for the term "proxy" in the search bar in the upper right, then select the button that says "Settings": + + .. figure:: /_static/images/tor/firefox_search.png + :width: 60% + :alt: Firefox search screenshot + +#. This should open a menu that will allow you to configure your proxy settings. Select "Automatic proxy configuration URL" and paste in the path to your PAC file from earlier, prefixed with ``file://``. For example: + + .. code-block:: + + file://C:/Program Files/Tor Browser/proxy.pac + +#. Then, check the box labeled "Proxy DNS when using SOCKS v5": + + .. figure:: /_static/images/tor/firefox_proxy.png + :width: 60% + :alt: Firefox proxy settings screenshot + +#. Click "OK" and then restart Firefox for the changes to take effect. + +#. You're all set! You should now be able to navigate to ".onion" URLs in Firefox. You can test this by going to Start9's ``.onion`` homepage, `here `__. + diff --git a/site/source/user-manual/connecting/tor-setup/tor-os/index.rst b/site/source/user-manual/connecting/connecting-tor/tor-os/index.rst similarity index 58% rename from site/source/user-manual/connecting/tor-setup/tor-os/index.rst rename to site/source/user-manual/connecting/connecting-tor/tor-os/index.rst index 9f8758d..0d97ea6 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-os/index.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-os/index.rst @@ -1,16 +1,16 @@ .. _tor-os: -============ -Tor - Device -============ +======== +Tor - OS +======== 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 + Linux + Mac + Windows + Android/Graphene/Calyx + iOS diff --git a/site/source/user-manual/connecting/tor-setup/tor-os/tor-android.rst b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-android.rst similarity index 97% rename from site/source/user-manual/connecting/tor-setup/tor-os/tor-android.rst rename to site/source/user-manual/connecting/connecting-tor/tor-os/tor-android.rst index 52769a1..f4fff82 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-os/tor-android.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-android.rst @@ -1,8 +1,8 @@ .. _tor-android: -======= -Android -======= +====================== +Running Tor on Android +====================== Some apps, such as :ref:`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. diff --git a/site/source/user-manual/connecting/connecting-tor/tor-os/tor-ios.rst b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-ios.rst new file mode 100644 index 0000000..a38afd9 --- /dev/null +++ b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-ios.rst @@ -0,0 +1,7 @@ +.. _tor-ios: + +================== +Running Tor on iOS +================== + +Unfortunately, it is not currently possible to run Tor natively on iOS. Please see :ref:`iOS Limitations` for details and workarounds. diff --git a/site/source/user-manual/connecting/tor-setup/tor-os/tor-linux.rst b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-linux.rst similarity index 97% rename from site/source/user-manual/connecting/tor-setup/tor-os/tor-linux.rst rename to site/source/user-manual/connecting/connecting-tor/tor-os/tor-linux.rst index b356b47..fa42dbb 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-os/tor-linux.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-linux.rst @@ -1,8 +1,8 @@ .. _tor-linux: -===== -Linux -===== +==================== +Running Tor on Linux +==================== .. tabs:: diff --git a/site/source/user-manual/connecting/tor-setup/tor-os/tor-mac.rst b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-mac.rst similarity index 97% rename from site/source/user-manual/connecting/tor-setup/tor-os/tor-mac.rst rename to site/source/user-manual/connecting/connecting-tor/tor-os/tor-mac.rst index 2f72b7f..416357d 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-os/tor-mac.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-mac.rst @@ -1,8 +1,8 @@ .. _tor-mac: -=== -Mac -=== +================== +Running Tor on Mac +================== Install Homebrew ---------------- diff --git a/site/source/user-manual/connecting/tor-setup/tor-os/tor-windows.rst b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-windows.rst similarity index 97% rename from site/source/user-manual/connecting/tor-setup/tor-os/tor-windows.rst rename to site/source/user-manual/connecting/connecting-tor/tor-os/tor-windows.rst index 7d92bb3..bfd4308 100644 --- a/site/source/user-manual/connecting/tor-setup/tor-os/tor-windows.rst +++ b/site/source/user-manual/connecting/connecting-tor/tor-os/tor-windows.rst @@ -1,8 +1,8 @@ .. _tor-windows: -======= -Windows -======= +====================== +Running Tor on Windows +====================== #. Unfortunately, `The Tor Project `_ 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 `_. diff --git a/site/source/user-manual/connecting/index.rst b/site/source/user-manual/connecting/index.rst index 59feb6e..456d0ec 100644 --- a/site/source/user-manual/connecting/index.rst +++ b/site/source/user-manual/connecting/index.rst @@ -11,22 +11,22 @@ Connecting
.. topic-box:: - :title: LAN - :link: lan-setup + :title: Connecting Over LAN + :link: connecting-lan :icon: scylla-icon scylla-icon--home :class: large-5 :anchor: Setup - Connect to Embassy over your Local Area Network. + Local Area Network connections are fast and secure and do not even require Internet access. .. topic-box:: - :title: Tor - :link: tor-setup + :title: Connecting Over Tor + :link: connecting-tor :icon: scylla-icon scylla-icon--tor :class: large-5 :anchor: Setup - Connect to Embassy over the Tor network. + Leverage Tor to connect to your Embassy privately and anonymously from anywhere in the world. .. raw:: html @@ -36,5 +36,5 @@ Connecting :maxdepth: 2 :hidden: - lan-setup/index - tor-setup/index + Lan + Tor diff --git a/site/source/user-manual/connecting/lan-setup/index.rst b/site/source/user-manual/connecting/lan-setup/index.rst deleted file mode 100644 index 651c8a7..0000000 --- a/site/source/user-manual/connecting/lan-setup/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _lan-setup: - -========= -LAN Setup -========= - -When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access` is much faster and will allow access to your data, even with no Internet connection. Begin by setting up :ref:`Devices` before setting up a :ref:`Browser`. - -.. toctree:: - :maxdepth: 2 - - lan-os/index - lan-browser/index diff --git a/site/source/user-manual/connecting/lan-setup/lan-browser/index.rst b/site/source/user-manual/connecting/lan-setup/lan-browser/index.rst deleted file mode 100644 index f40c5a7..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-browser/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _lan-browser: - -============= -LAN - Browser -============= - -When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access` is much faster and will allow access to your data, even with no Internet connection. - -.. caution:: You will first need to complete :ref:`LAN Setup` for your device before continuing. - -.. toctree:: - :maxdepth: 2 - - lan-brave - lan-chrome - lan-ff - lan-safari diff --git a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-brave.rst b/site/source/user-manual/connecting/lan-setup/lan-browser/lan-brave.rst deleted file mode 100644 index 48a1b92..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-brave.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _lan-brave: - -===== -Brave -===== - -.. caution:: You will first need to complete :ref:`LAN Setup` for your device before continuing. - -#. Open a new tab in Brave and Navigate to ``Settings`` from the top-right hamburger menu. - - .. figure:: /_static/images/ssl/browser/brave_settings.png - :width: 30% - :alt: Brave settings page - -#. On the left hand sidebar, select the Security and Privacy section, then the Security menu item. - - .. figure:: /_static/images/ssl/browser/brave_security.png - :width: 60% - :alt: Brave Security and Privacy settings - -#. At the bottom of the section, select "Manage Certificates". - - .. figure:: /_static/images/ssl/browser/brave_security_settings.png - :width: 60% - :alt: Brave Security settings page - -#. If you **EITHER** see "org-Start9" with a trusted “Embassy Local Root CA” listed under it, open a new tab to apply the certificate. If this does not work, quit and restart Chrome. - - **OR** - -#. If you do not see "org-Start9"in the list, ensure the certificate is properly set up on your computer system. Otherwise, click “Import” and open the downloaded ``Embassy Local Root CA.crt`` file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps `. - - - .. figure:: /_static/images/ssl/browser/brave_view_certs.png - :width: 60% - :alt: Brave Manage Certificates sub-menu on MacOS - - Check the box for "Trust this certificate for identitying websites" and click "OK" - -#. Obtain the LAN address that was provided at the end of your initial Embassy setup, or from the :ref:`Embassy tab` -> ``About`` (Under ``Insights``) and enter it in a new tab. - - .. tip:: You may need to restart the browser - -#. You will see a green padlock and ``https://`` to the left of the URL bar. You can now securely navigate to your Embassy on your :ref:`LAN` with :ref:`HTTPS`! - -.. note:: Additionally, you can start a Brave private window with Tor to visit the Tor address over HTTPS (unnecessary in principle, but will circumvent annoying browser warnings). diff --git a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-chrome.rst b/site/source/user-manual/connecting/lan-setup/lan-browser/lan-chrome.rst deleted file mode 100644 index 046bdb8..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-chrome.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _lan-chrome: - -====== -Chrome -====== - -.. caution:: You will first need to complete :ref:`LAN Setup` for your device before continuing. - -.. tip:: The following guide also works with Chromium and Vivaldi. - -#. Open a new tab in Chrome and navigate to ``chrome://settings/certificates``. - - .. figure:: /_static/images/ssl/browser/chrome_settings.png - :width: 60% - :alt: Chrome Certificates Settings page - -#. Click on the "Authorities" tab. - - .. figure:: /_static/images/ssl/browser/chrome_authorities.png - :width: 60% - :alt: Chrome Certificate Authorities page - -#. You will **EITHER** see "org-Start9" with a trusted “Embassy Local Root CA” listed under it, - - .. figure:: /_static/images/ssl/browser/chrome_s9ca.png - :width: 60% - :alt: Start9 Certificate Authority - - in which case, open a new tab to apply the certificate. If this does not work, quit and restart Chrome. - - **OR** - -#. If you do not see "org-Start9"in the list, ensure the certificate is properly set up on your computer system. Otherwise, click “Import” and open the downloaded ``Embassy Local Root CA.crt`` file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps `. - - .. figure:: /_static/images/ssl/browser/chrome_trust.png - :width: 60% - :alt: Trust the CA - - Check the box for "Trust this certificate for identitying websites" and click "OK" - -#. Obtain the LAN address that was provided at the end of your initial Embassy setup, or from the :ref:`Embassy tab` -> ``About`` (Under ``Insights``) and enter it in a new tab. - - .. tip:: You may need to restart the browser - - .. figure:: /_static/images/ssl/browser/chrome_https.png - :width: 60% - :alt: Success - -#. You will see a green padlock and ``https://`` to the left of the URL bar. You can now securely navigate to your Embassy on your :ref:`LAN` with :ref:`HTTPS`! diff --git a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-ff.rst b/site/source/user-manual/connecting/lan-setup/lan-browser/lan-ff.rst deleted file mode 100644 index 6b61d86..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-ff.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _lan-ff: - -======= -Firefox -======= - -#. Open Firefox and in a new tab select ``Settings`` from the right-hand hamburger menu: - - .. figure:: /_static/images/tor/os_ff_settings.png - :width: 30% - :alt: Firefox options screenshot - -#. Select “Privacy and Security” from the left hand navigation menu. - -#. Scroll all the way to the bottom of the page and select “View Certificates”. - - .. figure:: /_static/images/ssl/browser/firefox_security_settings.png - :width: 80% - :alt: Firefox security settings - - Firefox privacy and security settings page - -#. Select the "Authorities" tab from the "Certificate Manager". - -#. Click “Import” and open the downloaded ``Embassy Local Root CA.crt`` file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps `. - -#. When prompted, check “Trust this CA to identity websites” and select “OK”. - - .. figure:: /_static/images/ssl/browser/firefox_view_certs.png - :width: 80% - :alt: Firefox import cert - - Firefox import certificate page - -#. Ensure the “Embassy Local Root CA” exists under “Start9 Labs”. If it does not appear, you may need to close the Certificates pop-up and re-open to refresh the list. Then click “OK” to save. - -#. Open a new tab in Firefox to apply the changes. If this does not work, quit and restart Firefox. - -#. Navigate to the LAN address provided at setup, or in the :ref:`Embassy tab` -> LAN. You can now securely navigate to your Embassy over HTTPS! diff --git a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-safari.rst b/site/source/user-manual/connecting/lan-setup/lan-browser/lan-safari.rst deleted file mode 100644 index e668af4..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-browser/lan-safari.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _lan-safari: - -====== -Safari -====== - -Once you have completed the :ref:`LAN Setup` steps on your device, simply open a new tab to apply the changes. If this does not work, quit and restart Safari. You can now securely navigate to the LAN address for your Embassy! diff --git a/site/source/user-manual/connecting/lan-setup/lan-os/index.rst b/site/source/user-manual/connecting/lan-setup/lan-os/index.rst deleted file mode 100644 index 647d933..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-os/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _lan-os: - -============ -LAN - Device -============ - -When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access` 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 diff --git a/site/source/user-manual/connecting/lan-setup/lan-os/lan-android.rst b/site/source/user-manual/connecting/lan-setup/lan-os/lan-android.rst deleted file mode 100644 index 0b361c3..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-os/lan-android.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _lan-android: - -======= -Android -======= - -If you are running Android 12+ (not yet available on Calyx/Graphene), you can setup :ref:`Local Access`, please refer to :ref:`Android Limitations ` for more details. - -.. note:: You must download your certificate via desktop/laptop over Tor and then transfer it to your phone (Step 3) - -#. Either use the Root CA you downloaded at the completion of :ref:`Initial Setup`, or visit your Embassy at its Tor Address (for security purposes), and navigate to the :ref:`Embassy tab` -> LAN - - .. figure:: /_static/images/ssl/embassy_lan_setup.png - :width: 60% - :alt: LAN setup menu item - -#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine - - .. figure:: /_static/images/ssl/embassy_lan_setup0.png - :width: 60% - :alt: LAN setup page - -#. Send the cert to yourself via Signal, email, File Browser, etc and download onto your Android device - -#. Go to Settings -> Security -> Advanced -> Encryption and Credentials -> Install a Certificate and select the cert you downloaded from the file system - - .. figure:: /_static/images/ssl/android/droidLAN0.png - :width: 30% - :alt: Install certificate - -#. To setup in Firefox Beta or Fennec, go to Settings -> About -> tap the logo several times until it says "Debug menu enabled." Then return to Settings -> Secret Settings and toggle on "Use third party CA certificates." - -#. That's it! You may now browse the ``.local`` addresses on your Embassy. diff --git a/site/source/user-manual/connecting/lan-setup/lan-os/lan-ios.rst b/site/source/user-manual/connecting/lan-setup/lan-os/lan-ios.rst deleted file mode 100644 index 1c7a9e4..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-os/lan-ios.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _lan-ios: - -=== -iOS -=== - -.. note:: For security, this will need to be done using a Tor connection. Please use Onion Browser or Consulate to access your Embassy and complete the following steps. - -#. You will first need to get your :ref:`LAN Certificate`, which can be found either: - - #. When completing your Embassy :ref:`Initial Setup`, it is provided on the final screen - - or: - - #. In the ``Embassy`` tab in your Embassy, under ``Settings`` -> ``LAN`` - - .. figure:: /_static/images/ssl/embassy_lan_setup.png - :width: 60% - :alt: LAN setup menu item - -#. Select ``Download Root CA``. Clicking this will prompt you to “Save to device”. - - .. figure:: /_static/images/ssl/embassy_lan_setup0.png - :width: 60% - :alt: LAN setup page - -#. You will be directed to a page in your default browser indicating next steps and that the profile has been successfully downloaded. Be sure to complete all steps in this process! These steps are also outlined below. - - .. note:: - If you have changed the default browser from Safari to Brave, the following auto save certificate to device flow will *not* work. Safari, Firefox, and Chrome work as expected. We recommend you temporarily use one of these browsers to complete this action. - - .. figure:: /_static/images/ssl/ios/ssl_certificate_install_page.png - :width: 40% - :alt: Certificate install page - - Select "Allow" on the certificate install page - -#. Go to Settings on your iOS device. - - .. figure:: /_static/images/ssl/ios/ssl_ipad_general_settings.png - :width: 40% - :alt: General settings - -#. Navigate to *General > Profile(s) > Downloaded Profile > Install*. - - .. figure:: /_static/images/ssl/ios/ssl_ipad_profiles.png - :width: 40% - :alt: Profiles - - .. figure:: /_static/images/ssl/ios/ssl_ipad_install_profile.png - :width: 40% - :alt: Install profile - - Select "Install" for Embassy Local Root CA - -#. Select “Yes” to any warning prompts. - -#. Next, navigate to *General > About > Certificate Trust Settings*. - - .. figure:: /_static/images/ssl/ios/ssl_ipad_cert_trust_settings.png - :width: 40% - :alt: Certificate trust settings - - Select Certificate Trust Settings (scroll all the way down) - -#. Enable full trust for root certificates. - - .. figure:: /_static/images/ssl/ios/ssl_ipad_cert_trust.png - :width: 40% - :alt: Enable full trust - - Toggle to enable full trust for root certificates. "Continue" when warning prompts. - -#. Test that this process worked successfully by navigating to the LAN address provided from one of the locations listed under Step 1 at the top of this page. You should not see warnings about the security of this site in your browser (if you do, setup was not successful). - diff --git a/site/source/user-manual/connecting/lan-setup/lan-os/lan-linux.rst b/site/source/user-manual/connecting/lan-setup/lan-os/lan-linux.rst deleted file mode 100644 index 4f20bdc..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-os/lan-linux.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _lan-linux: - -===== -Linux -===== - -Nothing specific needs to be configured for the Linux environment, so you just need to download the certificate from your Embassy. - -#. Visit your Embassy at its Tor Address. - - .. note:: Using this encrypted Tor connection is required for security reasons. - -#. Navigate to the :ref:`Embassy tab` -> Settings -> LAN - - .. figure:: /_static/images/ssl/embassy_lan_setup.png - :width: 60% - :alt: LAN setup menu item - -#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine. - - .. figure:: /_static/images/ssl/embassy_lan_setup0.png - :width: 60% - :alt: LAN setup page - -Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup `. diff --git a/site/source/user-manual/connecting/lan-setup/lan-os/lan-mac.rst b/site/source/user-manual/connecting/lan-setup/lan-os/lan-mac.rst deleted file mode 100644 index c2bb2cd..0000000 --- a/site/source/user-manual/connecting/lan-setup/lan-os/lan-mac.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _lan-mac: - -=== -Mac -=== - -#. Visit your Embassy at its Tor Address (for security purposes), and navigate to the :ref:`Embassy tab` -> LAN - - .. figure:: /_static/images/ssl/embassy_lan_setup.png - :width: 60% - :alt: LAN setup menu item - -#. Click "Download Root CA". This will prompt a download to save the certificate file to your machine. - - .. figure:: /_static/images/ssl/embassy_lan_setup0.png - :width: 60% - :alt: LAN setup page - -#. Select the option to ``Open with`` "Keychain Access" and select ``OK``. If you choose to save the file, double click on it once downloaded. - - .. figure:: /_static/images/ssl/embassy_lan_setup1.png - :width: 60% - :alt: LAN setup prompt - -#. Enter your computer password when prompted. It will be imported into your mac's keychain. - - .. figure:: /_static/images/ssl/macos/certificate_untrusted.png - :width: 60% - :alt: Keychain access import menu - - Keychain access import menu - - .. note:: If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it. - -#. Navigate to the "System" tab on the left, find the certificate entitled “Embassy Local Root CA”, and double click on this certificate. A second window will pop up. - -#. Open the “Trust” dropdown and select “Always Trust” from the dropdown next to “When using this certificate”. - - .. figure:: /_static/images/ssl/macos/always_trust.png - :width: 60% - :alt: Keychain submenu - - Select "Always trust" under the "Trust" dropdown for Embassy Local CA - -#. Close this window and enter your password to apply the settings. - -#. The “Embassy Local Root CA” cert will now read “This certificate is marked as trusted for all users” in Keychain Access. - - .. figure:: /_static/images/ssl/macos/certificate_trusted.png - :width: 60% - :alt: Keychain menu trusted certificate - - Trusted Embassy Local CA certificate - -#. Open your favorite browser and follow the steps for :ref:`browser setup ` to complete LAN setup. diff --git a/site/source/user-manual/connecting/tor-setup/index.rst b/site/source/user-manual/connecting/tor-setup/index.rst deleted file mode 100644 index 31fcdb4..0000000 --- a/site/source/user-manual/connecting/tor-setup/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _running-tor: - -========= -Tor Setup -========= - -Setup :ref:`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 diff --git a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-windows.rst b/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-windows.rst deleted file mode 100644 index 03c5f28..0000000 --- a/site/source/user-manual/connecting/tor-setup/tor-firefox/torff-windows.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _torff-windows: - -======= -Windows -======= - -.. caution:: This guide assumes you have completed :ref:`setting up Tor`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor. - -#. Open Firefox and enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings. - -#. Search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``. - - .. figure:: /_static/images/tor/firefox_whitelist.png - :width: 60% - :alt: Firefox whitelist onions screenshot - -#. Download a `Proxy Auto Config` file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file by following instructions below: - - - Click `here `_ to get the file and save the file somewhere you won’t delete it. Please remember the location you save the file in if you do not use our example location. For this example: - - .. code-block:: - - C:\Program Files\Tor Browser\proxy.pac - -#. Now, back in your Firefox web browser, select ``Options`` from the right-hand hamburger menu: - - .. figure:: /_static/images/tor/firefox_options_windows.png - :width: 60% - :alt: Firefox options screenshot - - -#. Search for the term “proxy” in the search bar in the upper right, then select the button that says ``Settings…``: - - .. figure:: /_static/images/tor/firefox_search.png - :width: 60% - :alt: Firefox search screenshot - -#. This should open a menu that will allow you to configure your proxy settings. Select ``Automatic proxy configuration URL`` and paste in the path to your PAC file from earlier, prefixed with ``file://``. For example: - - .. code-block:: - - file://C:/Program Files/Tor Browser/proxy.pac - -#. Then, check the box labeled ``Proxy DNS when using SOCKS v5``: - - .. figure:: /_static/images/tor/firefox_proxy.png - :width: 60% - :alt: Firefox proxy settings screenshot - -#. Click ``OK`` and then restart Firefox for the changes to take effect. - -#. You're all set! You should now be able to navigate to ``.onion`` URLs in Firefox. This means you can access tor-only service :ref:`WebUIs `, such as Cups Messenger, and use your :ref:`Vaultwarden` Tor address in the `Bitwarden Firefox Plugin `_. You can test this by going to Start9's ``.onion`` homepage, `here `__. - diff --git a/site/source/user-manual/connecting/tor-setup/tor-os/tor-ios.rst b/site/source/user-manual/connecting/tor-setup/tor-os/tor-ios.rst deleted file mode 100644 index 85a806b..0000000 --- a/site/source/user-manual/connecting/tor-setup/tor-os/tor-ios.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _tor-ios: - -=== -iOS -=== - -Unforutnately, it is not currently possible to run Tor natively on iOS. Please see :ref:`iOS Limitations` for details and workarounds. diff --git a/site/source/user-manual/customize.rst b/site/source/user-manual/customize.rst index 9cc02f1..27728b2 100644 --- a/site/source/user-manual/customize.rst +++ b/site/source/user-manual/customize.rst @@ -4,45 +4,31 @@ Customize ========= -.. _device-name: - Name Your Device ---------------- -Here you can change the name of your Embassy! - -#. Go to the ``Embassy`` tab on the main menu on the left side of the UI - - .. figure:: /_static/images/config/basic-config0.png - :width: 60% - :alt: Embassy Tab - -#. Under the ``Settings`` section, click ``Preferences`` +#. Go to the *Embassy > Preferences*. .. figure:: /_static/images/config/basic-config1.png :width: 60% :alt: Preferences -#. Then click ``Device Name``, set to desired name, and click ``Save`` +#. Click "Device Name", set to desired name, and click ``Save`` .. figure:: /_static/images/config/basic-config2.png :width: 60% :alt: Rename Embassy -.. _reorder: - Reorder Services ---------------- -You may customize the layout of your Services by re-arranging them to your liking. - -#. Simply visit the ``Services`` tab on the main menu on the left side of the UI, and select ``Reorder`` in the top right. +#. In the "Services" tab, click "Reorder" in the top right. .. figure:: /_static/images/walkthrough/reorder0.png :width: 60% :alt: Reorder Button -#. You can now click and drag on each service to create the ordered list you desire. When satisfied, click ``Done`` in the top right to save. +#. Drag each service to its desired position. When satisfied, click "Done". .. figure:: /_static/images/walkthrough/reorder1.png :width: 60% diff --git a/site/source/user-manual/dashboard-overview.rst b/site/source/user-manual/dashboard-overview.rst index 0f27013..e12c8b1 100644 --- a/site/source/user-manual/dashboard-overview.rst +++ b/site/source/user-manual/dashboard-overview.rst @@ -4,27 +4,18 @@ Dashboard Overview ================== -.. _services-tab: - Services Tab ------------ -The Services Tab will show you all of your currently installed :ref:`Services`, or in the case of a fresh install, no Services. You can reorder this layout to your liking with the ``Reorder`` button in the top right. You can see a demo of this :ref:`here`. +Use this tab to view and access your installed services. .. figure:: /_static/images/walkthrough/servicestab.png :width: 60% -Click on any service in order to see its :ref:`Service Page`. - - .. figure:: /_static/images/walkthrough/servicepage.png - :width: 60% - -.. _embassy-tab: - Embassy Tab ----------- -The Embassy Tab is where you can perform :ref:`Backups`, get Insights into EOS, change some basic Settings, and Power cycle your device if necessary. +Use this tab to customize and manage your Embassy. .. figure:: /_static/images/walkthrough/embassytab.png :width: 60% @@ -32,57 +23,55 @@ The Embassy Tab is where you can perform :ref:`Backups`, get Insights i Backups ======= -One of the most important actions you can do on your Embassy is to keep a regular backup of your data. See the page on :ref:`Backups`, and select your device for more details. In this section, you can create, and restore from, backups. +The Backups section allows you to create and restore :ref:`Embassy backups `. + +Settings +======== + +The Settings section gives you access to :ref:`EmbassyOS Updates `, Device Preferences, :ref:`connecting-lan`, :ref:`ssh`, :ref:`wifi`, and :ref:`alt-marketplaces`. Insights ======== The Insights section gives you basic information on your Embassy, monitoring of system resources / temperature, and logs for debugging. -Settings -======== +Support +======= -The Settings section lets you change preferences, and manage `Connectivity` and Active Sessions. See the documentation on :ref:`Configuration` for more details. - -.. _power: +The Support section provides links to frequently asked questions as well as Start9 and community contact information. Power ===== -Restart -....... +* **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. + * 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 -........ +* **Shutdown** -#. Be patient while services shut down, it may take some minutes. 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. + .. caution:: 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. -.. 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. + * Be patient while services shut down, it may take some minutes. 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. -.. _marketplace-tab: +* **System Rebuild** + + This action will tear down all service containers and rebuild them from scratch. No data will be deleted. This action is useful if your system gets into a bad state, and it should only be performed if you are experiencing general performance or reliability issues. It may take multiple minutes to complete. During this time, you will lose all connectivity to your Embassy. Marketplace Tab --------------- -The Marketplace Tab is obviously the home of the Marketplace, where you can search out and install new Services, or manange existing ones. You can view our live Marketplace `here `_. +Use this tab to access your preferred Marketplace, where you can discover and install new services, or update existing services. Check out the `live Marketplace `_. .. figure:: /_static/images/walkthrough/markettab.png :width: 60% -Marketplace -=========== - -.. _notifications-tab: - Notifications Tab ----------------- -The Notifications Tab is where you can view and manage information produced by EOS and your Services that may need your attention. You can clear these individually, or all at once with ``Delete All`` in the top right. +Notifications issued by EmbassyOS will appear in this tab. You can delete these notifications individually or all at once by clicking "Delete All". .. figure:: /_static/images/walkthrough/notiftab.png :width: 60% diff --git a/site/source/user-manual/device-guides/dg-android.rst b/site/source/user-manual/device-guides/dg-android.rst index e1fb077..4370a4d 100644 --- a/site/source/user-manual/device-guides/dg-android.rst +++ b/site/source/user-manual/device-guides/dg-android.rst @@ -8,6 +8,6 @@ To optimize your device for use with your Embassy, it is recommended to complete .. tip:: Please see Android's :ref:`Known Limitations` to understand what is currently not possible on these devices -* :ref:`Connecting over LAN ` - For a fast and secure connection while on your Embassy's local network -* :ref:`Connecting over Tor ` - Run Tor natively (in the background) on your device. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. -* :ref:`Tor Firefox Config ` - Configure Firefox to use the Tor Network so that you can reach ``.onion`` sites without needing to change browsers. +* :ref:`lan-android` - Trust your Embassy's Root Certificate Authority in order to securely connect over LAN. +* :ref:`tor-android` - Run Tor natively (in the background) on your Android device. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. +* :ref:`torff-android` - Configure Firefox to use the Tor Network so that you can reach ".onion" sites without needing to change browsers. diff --git a/site/source/user-manual/device-guides/dg-ios.rst b/site/source/user-manual/device-guides/dg-ios.rst index 6dcc926..f1f2f39 100644 --- a/site/source/user-manual/device-guides/dg-ios.rst +++ b/site/source/user-manual/device-guides/dg-ios.rst @@ -8,4 +8,4 @@ To optimize your device for use with your Embassy, it is recommended to complete .. tip:: Please see iOS's :ref:`Known Limitations` to understand what is currently not possible on these devices -* :ref:`Connecting over LAN ` - For a fast and secure connection while on your Embassy's local network +* :ref:`lan-ios` - Trust your Embassy's Root Certificate Authority in order to securely connect over LAN. diff --git a/site/source/user-manual/device-guides/dg-linux.rst b/site/source/user-manual/device-guides/dg-linux.rst index 99a6940..082f64a 100644 --- a/site/source/user-manual/device-guides/dg-linux.rst +++ b/site/source/user-manual/device-guides/dg-linux.rst @@ -8,7 +8,6 @@ To optimize your device for use with your Embassy, it is recommended to complete .. tip:: Please see Linux's :ref:`Known Limitations` to understand what is currently not possible on these devices -* :ref:`Connecting over LAN ` - For a fast and secure connection while on your Embassy's local network -* :ref:`Connecting over Tor ` - Run Tor natively (in the background) on your device. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. -* :ref:`Tor Firefox Config ` - Configure Firefox to use the Tor Network so that you can reach ``.onion`` sites without needing to change browsers. -* :ref:`LAN Shared Folder Setup ` - Configure a Shared Network Folder on your laptop/desktop (or an external drive plugged into your laptop/desktop) in order to use it for Embassy backups. +* :ref:`tor-linux` - Run Tor natively (in the background) on your Linux machine. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. +* :ref:`torff-linux` - Configure Firefox to use the Tor Network so that you can reach ".onion" sites without needing to change browsers. +* :ref:`cifs-linux` - Configure a LAN Shared Folder on your Linux machine (or an external drive plugged into your Linux Machine) in order to use it for Embassy backups. diff --git a/site/source/user-manual/device-guides/dg-mac.rst b/site/source/user-manual/device-guides/dg-mac.rst index 6142d52..f5b20e2 100644 --- a/site/source/user-manual/device-guides/dg-mac.rst +++ b/site/source/user-manual/device-guides/dg-mac.rst @@ -8,7 +8,7 @@ To optimize your device for use with your Embassy, it is recommended to complete .. tip:: Please see Mac's :ref:`Known Limitations` to understand what is currently not possible on these devices -* :ref:`Connecting over LAN ` - For a fast and secure connection while on your Embassy's local network -* :ref:`Connecting over Tor ` - Run Tor natively (in the background) on your device. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. -* :ref:`Tor Firefox Config ` - Configure Firefox to use the Tor Network so that you can reach ``.onion`` sites without needing to change browsers. -* :ref:`LAN Shared Folder Setup ` - Configure a Shared Network Folder on your laptop/desktop (or an external drive plugged into your laptop/desktop) in order to use it for Embassy backups. +* :ref:`lan-mac` - Trust your Embassy's Root Certificate Authority in order to securely connect over LAN. +* :ref:`tor-mac` - Run Tor natively (in the background) on your Mac. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. +* :ref:`torff-mac` - Configure Firefox to use the Tor Network so that you can reach ".onion" sites without needing to change browsers. +* :ref:`cifs-mac` - Configure a LAN Shared Folder on your Mac (or an external drive plugged into your Mac in order to use it for Embassy backups. diff --git a/site/source/user-manual/device-guides/dg-windows.rst b/site/source/user-manual/device-guides/dg-windows.rst index 9fc507a..e6c9439 100644 --- a/site/source/user-manual/device-guides/dg-windows.rst +++ b/site/source/user-manual/device-guides/dg-windows.rst @@ -8,7 +8,7 @@ To optimize your device for use with your Embassy, it is recommended to complete .. tip:: Please see Window's :ref:`Known Limitations` to understand what is currently not possible on these devices. -* :ref:`Connecting over LAN ` - For a fast and secure connection while on your Embassy's local network -* :ref:`Connecting over Tor ` - Run Tor natively (in the background) on your device. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. -* :ref:`Tor Firefox Config ` - Configure Firefox to use the Tor Network so that you can reach ``.onion`` sites without needing to change browsers. -* :ref:`LAN Shared Folder Setup ` - Configure a Shared Network Folder on your laptop/desktop (or an external drive plugged into your laptop/desktop) in order to use it for Embassy backups. +* :ref:`lan-windows` - Trust your Embassy's Root Certificate Authority in order to securely connect over LAN. +* :ref:`tor-windows` - Run Tor natively (in the background) on your Windows computer. This will allow you to use applications on your machine via the Tor Network so they can communicate with your Embassy. +* :ref:`torff-windows` - Configure Firefox to use the Tor Network so that you can reach ".onion" sites without needing to change browsers. +* :ref:`cifs-windows` - Configure a LAN Shared Folder on your Windows computer (or an external drive plugged into your Windows computer) in order to use it for Embassy backups. diff --git a/site/source/user-manual/diy.rst b/site/source/user-manual/diy.rst deleted file mode 100644 index 9ed27de..0000000 --- a/site/source/user-manual/diy.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _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 several 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 -------------------- - -The first thing you'll need to do is gather the hardware and assemble it. - -Hardware: Components -.................... - -#. `Raspberry Pi 4B (8GB) `_ -#. `Power supply for Raspberry Pi 4B `_ Make sure this is at minimum 15w and 3.5a. -#. Case for Raspberry Pi 4B (`passive cooling `_ is recommended). This means no moving parts and no noise, as a fan is not required. - - .. caution:: If you prefer to 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 `_. - -#. A `16GB microSD card `_ (no need for bigger). If you have ABSOLUTELY NO data to migrate (from an Embassy v0.2.x), you may choose to re-use the card already in your Embassy. -#. `GPIO mini speaker/buzzer `_ (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 `_ with an `USB enclosure `_, as sold with our upgrade kits. MUST CONNECT OVER USB 3.0! - - - Currently the only tested and supported external drives are the Samsung T5 and T7 - - .. tip:: Alternatively, you may build with the Geekworm setup and internal M.2 drive as described in this `guide `_, which has been tested to work, but is not currently supported. - -Hardware: Assembly -.................. - -#. 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 ------------------ - -After building your device, you need a copy of EmbassyOS. - -Purchase from Start9 -............................. - -- You can purchase a copy of EmbassyOS `here `_. 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. - -Build from Source -....................................... - -- If you prefer to build EmbassyOS from source, you can do so following our guide on the `Start9 GitHub `_. - -Installing EmbassyOS --------------------- - -Whether you purchase EmbassyOS from us or build it yourself, you'll need to flash it onto a microSD card. - -#. Download `balenaEtcher `_ 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. - - .. warning:: BE CERTAIN YOU SELECT THE CORRECT DISK AS IT WILL BE ERASED AND WRITTEN OVER - -#. 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 continue following the normal :ref:`Initial Setup ` instructions. - - .. note:: The first time you power on your Embassy it may take 10-20 minutes to initialize. diff --git a/site/source/user-manual/forgot-password.rst b/site/source/user-manual/forgot-password.rst index 08045bc..2722e64 100644 --- a/site/source/user-manual/forgot-password.rst +++ b/site/source/user-manual/forgot-password.rst @@ -4,21 +4,18 @@ Forgot Password =============== -There is currently no way to reset you Embassy master password through a standard UI flow. +.. note:: There is currently no way to reset you Embassy master password through a standard UI flow. -SSH/Linux +Using SSH --------- -If you already have :ref:`SSH keys registered with your Embassy` **OR** you have access to a Linux computer, you can reset your Embassy password without losing any data. - -SSH -=== +.. note:: Resetting you password with SSH only possible if you have already :ref:`set up SSH` on your Embassy. #. Use the command line to gain SSH access to your Embassy, replacing ``[network-id]`` with your Embassy's unique ID: .. code-block:: bash - ssh pi@embassy-[network-id].local + ssh root@embassy-[network-id].local #. Check if you have sqlite3 installed (with ``which``). If not, install it (with ``apt``): @@ -48,10 +45,10 @@ SSH .. warning:: Running setup process will generate new certificate and Tor address for your Embassy. -#. You can now visit ``embassy.local`` to reclaim your Embassy and set a new password. +#. You can now visit http://embassy.local to reclaim your Embassy and set a new password. -Linux -===== +Using a 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:: @@ -80,7 +77,7 @@ Linux .. warning:: Running setup process will generate new certificate and Tor address for your Embassy. -#. You can now visit ``embassy.local`` to reclaim your Embassy and set a new password. +#. You can now visit http://embassy.local to reclaim your Embassy and set a new password. No SSH/Linux ------------ diff --git a/site/source/user-manual/index.rst b/site/source/user-manual/index.rst index 9cfcdb9..4b1619a 100644 --- a/site/source/user-manual/index.rst +++ b/site/source/user-manual/index.rst @@ -17,13 +17,11 @@ Welcome to the EmbassyOS user manual. Here you will discover all that you Embass backups/index forgot-password customize - managing-services/index + managing-services service-guides/index sessions wifi ssh - diy alt-marketplaces - migrate-02 - recover-03 device-guides/index + upgrade-02 diff --git a/site/source/user-manual/initial-setup.rst b/site/source/user-manual/initial-setup.rst index 5016b3b..49d0190 100644 --- a/site/source/user-manual/initial-setup.rst +++ b/site/source/user-manual/initial-setup.rst @@ -4,95 +4,88 @@ Initial Setup ============= -Powering On ------------ - Check out our quick setup video below, and follow along with the steps in this guide: .. youtube:: DmTlwp5_zvY -1. Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router. +Powering On +----------- -.. tip:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router. +#. Connect your Embassy to power and Ethernet. -2. Plug in your external drive to one of the USB 3.0 (blue) ports on Embassy. + .. tip:: To avoid networking issues, it is recommended to use your `primary` router, not an extender or mesh router. -Embassy will initialize, which may take 10-15min. You will hear 2 distinct sounds: +#. Insert your external drive to one of the blue USB 3.0 ports on Embassy. -* "bep" - Starting up -* "chime" - Embassy is ready +#. You will hear 2 distinct sounds: -Connecting ----------- + * "bep" - Starting up + * "chime" - Embassy is ready + + .. caution:: If you followed the DIY guide and built EmbassyOS from source code, it may take up to 20 minutes to first initialize. -1. Ensure the device you are using (desktop/laptop or mobile) is connected to the same network as your router. +Claiming your Device +-------------------- -.. caution:: Sometimes a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet. +#. Ensure the device you are using (desktop/laptop or mobile) is connected to the same network as your Embassy. -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. + .. caution:: Sometimes a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet. -.. figure:: /_static/images/setup/setup0.png - :width: 60% - :alt: Enter Product Key +#. Visit http://embassy.local from your web browser. You will be prompted to enter your :ref:`Product Key`. If you purchased a device from Start9, your Product Key is engraved on the bottom of your device. -.. admonition:: Explanation - :class: toggle expand + .. figure:: /_static/images/setup/setup0.png + :width: 60% + :alt: Enter Product Key - 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) `. + .. note:: -3. Next, select "Start Fresh" if this is your first time using an Embassy. If you'd like to "Recover" from an existing Embassy, please follow the guide for :ref:`versions 0.2.x ` or :ref:`versions 0.3.x `. + 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) `. -.. figure:: /_static/images/setup/setup1.png - :width: 60% - :alt: Fresh Install +#. Select "Start Fresh" -4. Select your storage drive. You should only have one drive plugged into your Embassy at this time, but always verify it is what you expect before clicking (such as, is it a 1TB drive?) + .. figure:: /_static/images/setup/setup1.png + :width: 60% + :alt: Fresh Install -.. figure:: /_static/images/setup/setup2.png - :width: 60% - :alt: Select Drive + .. note:: The "Recover" button is used for :ref:`migrating from 0.2.x ` and :ref:`restoring from backup `. -5. Create your *permanent* master password and complete setup. +#. Select your storage drive. You should only have one drive plugged into your Embassy at this time, but always verify it is what you expect before clicking (such as, is it a 1TB drive?) -.. figure:: /_static/images/setup/setup3.png - :width: 60% - :alt: Enter a New Password + .. figure:: /_static/images/setup/setup2.png + :width: 60% + :alt: Select Drive -.. admonition:: Explanation - :class: toggle expand +#. Create your *permanent* master password and click "Finish". - In this step, the setup process will provide your Embassy with three pieces of critical information: + .. warning:: There is 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.** - * 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. + .. figure:: /_static/images/setup/setup3.png + :width: 60% + :alt: Enter a New Password - All three secrets are packaged together and transmitted to the Embassy encrypted with its :ref:`Product Key`. +#. Your Embassy is now a private website on the private web! Continue to the section on :ref:`connecting` to learn more about using your Embassy over Tor and LAN. -.. 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.** + .. tip:: Click "Download This Page" to save your Embassy address and certificate info on your computer. -6. That's it! - -.. figure:: /_static/images/setup/setup4.png - :width: 60% - :alt: Setup Complete - -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 (see :ref:`LAN Setup` for assistance). + .. figure:: /_static/images/setup/setup4.png + :width: 60% + :alt: Setup Complete Troubleshooting --------------- -Try these steps if you have any issues with setup. +If you are experiencing issues with setup, try the following: - #. 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: +#. Confirm that the Embassy is plugged into both power and Ethernet +#. Confirm your SSD is plugged into one of the blue USB 3.0 slots. +#. Confirm the Embassy emitted two sounds when powering on: a bep and a chime. +#. Confirm you are entering the correct product key. +#. Confirm your connecting device is **not** connected to a "Guest" network. +#. Confirm your connecting device is not using a VPN. +#. Refresh the embassy.local browser 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. -If you are still having issues, please reach out to us for :ref:`Assistance`. +If you are still having issues, please :ref:`contact support `. diff --git a/site/source/user-manual/managing-services.rst b/site/source/user-manual/managing-services.rst new file mode 100644 index 0000000..eb6652b --- /dev/null +++ b/site/source/user-manual/managing-services.rst @@ -0,0 +1,156 @@ +.. _managing-services: + +================= +Managing Services +================= + +EmbassyOS provides a rich interface for managing installed Services. + +Service Dashboard +----------------- + +The Service Dashboard provides quick insight into the status and health of your service, as well as exposing a variety of management tools. + +.. figure:: /_static/images/services/service00.png + :width: 60% + +* Status: + * **Needs Config**: The Service needs your attention in making a configuration decision. There will always be default options available to you. + * **Stopping**: Service is in the process of stopping. + * **Stopped**: Service is installed and configured, but not currently running. + * **Starting**: Service is in the process of starting up. + * **Running**: Service is running. +* **Launch UI**: If the service offer a User Interface (UI), and the UI is currently available, clicking this button will launch the UI in a new browser tab. Learn more about :ref:`Web UIs`. +* **Health Checks**: This is a critical feature of EmbassyOS. Health Checks are configured by the service packager in order to quickly convey to the user what is happening with their service, as well as possible actions they may want to take. Learn more about :ref:`Health Checks `. +* **Dependencies**: Some services depend on the presence and proper configuration of other services to function. This section will inform you if all dependencies are satisfied and, if not, what to do about it. Learn more about :ref:`Dependencies `. +* **Start / Stop**: Self-explanatory, use these buttons to start or stop a service. + +Installing a Service +-------------------- + +* To add a new service, find its listing inside the Marketplace and click "Install". + + .. figure:: /_static/images/services/service0.png + :width: 60% + + .. figure:: /_static/images/services/service1.png + :width: 60% + +* Depending on the size of the service and your Internet connection, installation should take between 60 seconds and a few minutes. + + .. figure:: /_static/images/services/service2.png + :width: 60% + +* You may click *View Service* at any time to view install progress. + + .. figure:: /_static/images/services/service3.png + :width: 60% + +Updating a Service +------------------ + +.. note:: EmbassyOS will **NEVER** update a service without your consent. + +To see if an update is available for a service, you can visit the *Updates* section of the Marketplace or by visiting its Marketplace listing. + +If an update is available, simply click "Update" and confirm the action. + +Configuring a Service +--------------------- + +After an installation or update, some services require configuration before they can be started. + +Navigate to the *Services > [Service Name] > Config* + + .. figure:: /_static/images/services/service-needs-config.png + :width: 60% + +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. + + .. figure:: /_static/images/services/service4.png + :width: 60% + +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. + + .. figure:: /_static/images/services/service5.png + :width: 60% + +You can change your configuration at any time from a Service's main page: + + .. figure:: /_static/images/services/config.png + :width: 60% + +Service Instructions +-------------------- + +* Every services comes with its own set of usage instructions. To view the instructions for a particular service, navigate to the *Services > [Service Name] > Instructions*. + +.. figure:: /_static/images/services/instruct.png + :width: 60% + +* Instructions will provide you with service-specific direction, provided by the service package developer, on what to expect, and how to use your new service. + +.. figure:: /_static/images/services/service-instruct.png + :width: 60% + +Service Properties +------------------ + +Properties can contain 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. + +.. note:: Some services do not have any information in the Properties section. + +.. figure:: /_static/images/services/props.png + :width: 60% + +* To view the Properties for a particular service, navigate to *Services > [Service Name] > Properties*. + +* 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. + +Service Interfaces +------------------ + +Interfaces are URLs that an installed service uses to communicate in various ways with other software. Many Services will only have one interface, perhaps with a Tor and LAN address, to denote where it is hosted / accessed. Other services, such as Bitcoin or Lightning Nodes, may have several interfaces for different use cases. + +.. figure:: /_static/images/services/service-ints.png + :width: 60% + +* To view the Interfaces for a particular service, navigate to *Services > [Service Name] > Properties*. From there you can copy a URL to your clipboard for use with external software. + +.. figure:: /_static/images/services/service-ints0.png + :width: 60% + +Service Actions +--------------- + +Actions are defined by the service package developer, and can provide the ability to do resets or other miscellaneous administrative tasks. Actions may or may not require user input. + +.. figure:: /_static/images/services/acts.png + :width: 60% + +Default Actions +............... + +Every service comes with a set up default Actions that can be run. Currently, the only default action is "Uninstall". + +* **Uninstall** - To Uninstall a service, navigate to *Services > [Service Name] > Actions > Uninstall*. + + .. warning:: THIS WILL DELETE ALL DATA FOR THIS SERVICE, PLEASE BE SURE YOU WANT TO DO THIS! + +Custom Actions +.............. + +Service developers can define any number of arbitrary actions for their service. + +Service 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. You can check here if you have an issue with a service, and if you are talking to support, they may ask you to screenshot or copy these logs to help discover the root of the problem. + +.. figure:: /_static/images/services/logs.png + :width: 60% + +* To view the Logs for a particular service, go to *Services > [Service Name] > Logs* diff --git a/site/source/user-manual/managing-services/index.rst b/site/source/user-manual/managing-services/index.rst deleted file mode 100644 index b4b94ac..0000000 --- a/site/source/user-manual/managing-services/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _managing-services: - -================= -Managing Services -================= - -EmbassyOS provides a rich interface for working with services installed from the Marketplace. - -.. toctree:: - :maxdepth: 1 - - service-overview - service-install - service-config - service-instructions - service-properties - service-actions - service-interfaces - service-logs - service-updates diff --git a/site/source/user-manual/managing-services/service-actions.rst b/site/source/user-manual/managing-services/service-actions.rst deleted file mode 100644 index db111d0..0000000 --- a/site/source/user-manual/managing-services/service-actions.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _actions: - -======= -Actions -======= - -Actions are defined by the service package developer, and can provide the ability to do resets or other miscellaneous administrative tasks. Actions may or may not require user input. - -Default Actions ---------------- - -Every service comes with a set up default Actions that can be run. Currently, the only default action is "Uninstall". - -Uninstall -========= - -.. warning:: THIS WILL DELETE ALL DATA FOR THIS SERVICE, PLEASE BE SURE YOU WANT TO DO THIS! - -To remove a service, navigate to the :ref:`Services tab` *> [Service Name] > Actions > Uninstall*. - - .. figure:: /_static/images/services/acts.png - :width: 60% - -Custom Actions --------------- - -Service developers can define any number of arbitrary actions for their service. diff --git a/site/source/user-manual/managing-services/service-config.rst b/site/source/user-manual/managing-services/service-config.rst deleted file mode 100644 index 9a3306f..0000000 --- a/site/source/user-manual/managing-services/service-config.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _service-config: - -============= -Configuration -============= - -After installation or update, some services require configuration before they can be started. - -Navigate to the `Services tab ` *> [Service Name] > Config* - - .. figure:: /_static/images/services/service-needs-config.png - :width: 60% - -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. - - .. figure:: /_static/images/services/service4.png - :width: 60% - -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. - - .. figure:: /_static/images/services/service5.png - :width: 60% - -You can change your configuration at any time from a Service's main page: - - .. figure:: /_static/images/services/config.png - :width: 60% diff --git a/site/source/user-manual/managing-services/service-install.rst b/site/source/user-manual/managing-services/service-install.rst deleted file mode 100644 index f307683..0000000 --- a/site/source/user-manual/managing-services/service-install.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _installing: - -========== -Installing -========== - -.. note:: Some services have :ref:`dependencies` on other services. Adding, updating, or removing a service can sometimes have requirements or consequences for other services. Your Embassy will always inform you of these issues along the way. - -To add a new service, simply find its listing inside the Marketplace: *[Service Name] >* ``Install``. Let's install Synapse as an example: - - .. figure:: /_static/images/services/service0.png - :width: 60% - - .. figure:: /_static/images/services/service1.png - :width: 60% - -Depending on the size of the service and your Internet connection, installation should take between 60 seconds and a few minutes. - - .. figure:: /_static/images/services/service2.png - :width: 60% - -You may click *View Service* at any time to view install progress, or after install to go to the Service page. Many services will need to be configured after install. You can use the default options, or change to your liking. See :ref:`configuration` for details. - - .. figure:: /_static/images/services/service3.png - :width: 60% - -You will see a screen like the following when install is complete. Then you're ready to :ref:`configure ` your service! - - .. figure:: /_static/images/services/service4.png - :width: 60% - -.. note:: You can only use a service once its :ref:`dependencies ` are met, its :ref:`configuration` is complete, it has been started, and is in a *running* :ref:`status `. diff --git a/site/source/user-manual/managing-services/service-instructions.rst b/site/source/user-manual/managing-services/service-instructions.rst deleted file mode 100644 index d5e3ffa..0000000 --- a/site/source/user-manual/managing-services/service-instructions.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _instructions: - -============ -Instructions -============ - -To view the instructions for a particular service, navigate to the :ref:`Services tab ` *> [Service Name] > Instructions*. - -.. figure:: /_static/images/services/instruct.png - :width: 60% - -Instructions will provide you with service-specific direction, provided by the service package developer, on what to expect, and how to use your new service. - -.. figure:: /_static/images/services/service-instruct.png - :width: 60% - -.. note:: For advanced instructions and integration guides, visit the wrapper repository for an `available service `_. diff --git a/site/source/user-manual/managing-services/service-interfaces.rst b/site/source/user-manual/managing-services/service-interfaces.rst deleted file mode 100644 index 116c9ac..0000000 --- a/site/source/user-manual/managing-services/service-interfaces.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _service-interfaces: - -========== -Interfaces -========== - -Interfaces are URLs that a :ref:`Service` uses to communicate in various ways with other software. Many Services will only have one interface, perhaps with a Tor and LAN address, to denote where it is hosted / accessed. Other services, such as Bitcoin or Lightning Nodes, may have several interfaces for different use-cases. - -.. figure:: /_static/images/services/service-ints.png - :width: 60% - -To view the instructions for a particular service, navigate to the :ref:`Services tab ` *> [Service Name] > Properties*. From there you can copy a URL to your clipboard for use with external software. - -.. figure:: /_static/images/services/service-ints0.png - :width: 60% diff --git a/site/source/user-manual/managing-services/service-logs.rst b/site/source/user-manual/managing-services/service-logs.rst deleted file mode 100644 index dd213b9..0000000 --- a/site/source/user-manual/managing-services/service-logs.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _service-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. You can check here if you have an issue with a service, and if you are talking to support, they may ask you to screenshot or copy these logs to help discover the root of the problem. - - .. figure:: /_static/images/services/logs.png - :width: 60% diff --git a/site/source/user-manual/managing-services/service-overview.rst b/site/source/user-manual/managing-services/service-overview.rst deleted file mode 100644 index 3ad2a9c..0000000 --- a/site/source/user-manual/managing-services/service-overview.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _service-overview: - -======== -Overview -======== - -Services are very similar to Applications on a mobile device. The biggest differences are that they are often designed to run constantly, with 24/7 availability for when a user requires them. This is why they are called services: they are always ready to serve users! - -.. figure:: /_static/images/services/service8.png - :width: 60% - -In the image above, we see an example of a Service's homescreen, where you can access all the information and utilities of a particular service. - -Below, we highlight the quick, need-to-know information of a Service that a user will want to see right away. - -.. figure:: /_static/images/services/service00.png - :width: 60% - -.. _service-status: - -We can see the Service (Embassy Pages in this case), its ``Status``, ``Health Checks`` (if it has any), ``Dependencies`` (if it has any), and the ability to ``Start`` or ``Stop`` the Service, as well as ``Launch UI`` if it has a :ref:`Web Interface `. Here's a breakdown of what each of these means: - -- Status: - - ```Needs Config```: The Service needs your attention in making a configuration decision. There will always be default options available to you. - - ```Stopping...```: Service is being stopped - - ```Stopped```: Service is installed and configured, but not currently running. - - ```Starting...```: Service is booting up - - ```Running```: Service is running -- Health Checks: This is a critical feature of EmbassyOS. Health Checks are configured by the service packager in order to quickly convey to the user what is happening with their service, and possible actions they may want to take. Learn more about :ref:`Health Checks `. -- Dependencies: A service may require another service, called a dependency, in order to work. These may be optional, or required. Learn more about :ref:`Dependencies `. -- Start / Stop: Self-explanatory, use these buttons to start or stop a service. -- Launch UI: If available, this will open the User Interface (UI) for the service in a new browser tab. Learn more about :ref:`Web UIs`. diff --git a/site/source/user-manual/managing-services/service-properties.rst b/site/source/user-manual/managing-services/service-properties.rst deleted file mode 100644 index 5f9de17..0000000 --- a/site/source/user-manual/managing-services/service-properties.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _service-properties: - -========== -Properties -========== - -Properties can contain 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. - - .. figure:: /_static/images/services/props.png - :width: 60% - -To view the instructions for a particular service, navigate to the :ref:`Services tab ` *> [Service Name] > Properties*. - -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. - -.. note:: Some services do not have any information in the Properties section diff --git a/site/source/user-manual/managing-services/service-updates.rst b/site/source/user-manual/managing-services/service-updates.rst deleted file mode 100644 index 63da73e..0000000 --- a/site/source/user-manual/managing-services/service-updates.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _service-updates: - -======== -Updating -======== - -To see if an update is available for a service, you can visit the *Updates* section of the Marketplace or by visiting its Marketplace listing. - -If an update is available, simply click "Update" and confirm the action. diff --git a/site/source/user-manual/recover-03.rst b/site/source/user-manual/recover-03.rst deleted file mode 100644 index 77fc0d2..0000000 --- a/site/source/user-manual/recover-03.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. _recover-03: - -====================== -Recover 0.3 Data Drive -====================== - -This guide will cover how to recover existing Embassy 0.3.x service and user data (on an SSD) to a new OS install (sd card). - -Instructions ------------- - -#. Plug up all your hardware - - - New EOS install, flashed on sd card - - Old SSD with 0.3.x data that you are recovering from - - Ethernet cable - - Finally, power cable to boot device - -#. Embassy will power up and then initialize, a process of less than 5 minutes if you purchased an image, or about 10-20 minutes if you built from source. Once complete you will hear a _bep_ to indicate it is initialized and then a _chime_ sound to indicate it is online. - -#. On your computer, open up a browser and go to ``embassy.local``. You will be asked to enter a product key. This can be located on the bottom of your Embassy if you purchased, or in the repository folder if you built from source. - - .. figure:: /_static/images/setup/migrate0.png - :width: 60% - -#. Once entered, select ``Recover`` then select the ``Use Drive`` from the pop-up. If you don't see the drive, you may get a message asking you to unplug, then plug back in the drive, and refresh the page. Do so, then select the drive. - - .. figure:: /_static/images/setup/migrate1.png - :width: 60% - - .. figure:: /_static/images/setup/migrate3.png - :width: 60% - - .. note:: If it does not show up, please power down Embassy, unplug it, plug it back in, and boot Embassy again - -#. If this drive is not empty, you will see a warning first, indicating all data will be overwritten. If you are happy to proceed, click ``Continue``. - - .. figure:: /_static/images/setup/migrate4.png - :width: 60% - -#. You will now need to make a password for your Embassy. It needs to be a strong password. This password protects your Embassy. It can be the same one that you used prior to recovery, or a new one. Either way, make it strong, and make a backup of it. Without this you will **LOSE ALL ACCESS** to your Embassy! - -#. Embassy will now recover all your data from your old Embassy and once finished, you will hear a _bep_ then a _chime_. - - .. figure:: /_static/images/setup/migrate5.png - :width: 60% - -#. Now you will be provided with both a Tor and LAN address with which you can access your Embassy. A file download will contain this important information, which you should keep somewhere safe. It is also a good idea to make bookmarks on the devices that you will use to access your Embassy. These will be the same as your Embassy previous to recovery. - - .. figure:: /_static/images/setup/migrate6.png - :width: 60% - -#. To use LAN safely, the SSL certificate will need to be added to whatever device you are using to access. This can be downloaded by clicking on ``Download root CA`` and installed by following the :ref:`instructions`. - -#. You can now log in to your Embassy via Tor or LAN, and you will be given the option of recovering your data on a service-by-service basis. - -.. note:: For those recovering Bitwarden - it is now called Vaultwarden. diff --git a/site/source/user-manual/sessions.rst b/site/source/user-manual/sessions.rst index c786c42..8ddc3fc 100644 --- a/site/source/user-manual/sessions.rst +++ b/site/source/user-manual/sessions.rst @@ -1,12 +1,14 @@ -.. _active-sessions: +.. _session-management: -=============== -Active Sessions -=============== +================== +Session Management +================== -Every time a login is made with Embassy, such as from a web browser on your laptop or mobile device, a :ref:`Session ` is created. You can see these listed in the ``Embassy`` tab, under ``Active Sessions``. +Every time a login is made with Embassy, such as from a web browser on your laptop or mobile device, a :ref:`Session ` is created. -To end a session, simply click ``Kill`` to the right of your selection. +* To view and manage your active sessions, go to *Embassy > Active Sessions*. + +* To end an active session and log out of that device, click "Kill" to the right of your selection. .. figure:: /_static/images/walkthrough/sessions0.png :width: 60% diff --git a/site/source/user-manual/ssh.rst b/site/source/user-manual/ssh.rst index 957cb39..647ee8e 100644 --- a/site/source/user-manual/ssh.rst +++ b/site/source/user-manual/ssh.rst @@ -4,21 +4,20 @@ Using SSH ========= -.. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause while using SSH access. +Creating an SSH Key +------------------- -.. tip:: An ED25519 key is strongly recommended. If you have issues with any other type of key, please consider using an ED25519. +@TODO -Setting Up SSH Access ---------------------- +Registering an SSH Key +---------------------- -Connecting via CLI (Linux / Mac) -================================ +#. Navigate to the *Embassy > SSH*. +#. Click "Add New Key". +#. Paste in your SSH *public* key (created above) and click "Submit". -#. Navigate to the ``Embassy`` tab, then under ``Settings``, click ``SSH`` -#. Click the ``+ Add New Key`` button -#. Paste in your SSH public key and hit ``Submit`` - - .. tip:: This is typically found under your ``home`` in the ``.ssh`` directory and the file should end in ``.pub`` - copy the entire contents of the file. +Connecting via CLI on Linux/Mac +------------------------------- #. You can now access your Embassy from the command line (Linux and Mac) using: @@ -28,22 +27,22 @@ Connecting via CLI (Linux / Mac) Replacing ```` with your Embassy's LAN (``embassy-xxxxxxx.local``) address -Connecting via SSH on Windows, using PuTTY -========================================== +Connecting via PuTTY on Windows +------------------------------- -One of our community members, `@brewsbitcoin `_ (https://brewsbitcoin.com/), has put together this `Guide `_ for connecting via PuTTY on Windows. +@TODO -Setting Up Remote SSH Access (Tor) ----------------------------------- +Using SSH Over Tor +------------------ -.. note:: The following guide requires that you have already added an `SSH key to your Embassy`. +.. note:: The following guide requires that you have already added an :ref:`SSH key to your Embassy`. -This guide will allow you remote SSH access via Tor. Currently only supported on Linux, but may work on Windows with `Torifier `_. Currently, this setup will not persist after a reboot. +.. caution:: SSH over Tor is only supported on Linux, though it may also work on Windows with `Torifier `_. Setup -===== +..... -#. First, you'll need one dependency, ``torsocks``, which will allow you to use SSH over Tor on the machine that you want access with. Select your Linux flavor to install: +#. First, you'll need one dependency, ``torsocks``, which will allow you to use SSH over Tor on the machine that you want access with. Select your Linux flavor to install: .. tabs:: @@ -61,42 +60,41 @@ Setup #. SSH in: + .. warning:: The changes you make here are on the overlay and won't persist after a restart of your Embassy. + .. code-block:: bash ssh root@embassy-xxxxxxx.local -#. Add the following 2 lines to ``/etc/tor/torrc`` **EITHER** by using your preferred text editor (such as ``nano`` or ``vim``): - - ``HiddenServiceDir /var/lib/tor/ssh`` - ``HiddenServicePort 22 127.0.0.1:22`` - - **OR** by entering the following 2 commands: +#. Using Vim or Nano, add the following 2 lines to ``/etc/tor/torrc`` .. code-block:: bash - echo "HiddenServiceDir /var/lib/tor/ssh" >> /etc/tor/torrc - echo "HiddenServicePort 22 127.0.0.1:22" >> /etc/tor/torrc + HiddenServiceDir /var/lib/tor/ssh + HiddenServicePort 22 127.0.0.1:22 -#. Then reload the Tor configuration with your edits: + .. tip:: You can also add these lines by running the following command: + + .. code-block:: bash + + echo "HiddenServiceDir /var/lib/tor/ssh" >> /etc/tor/torrc && echo "HiddenServicePort 22 127.0.0.1:22" >> /etc/tor/torrc + +#. Reload the Tor configuration with your edits: .. code-block:: bash systemctl reload tor -#. Next, gather the ``.onion`` address you just created: +#. Gather the ".onion" address you just created: .. code-block:: bash cat /var/lib/tor/ssh/hostname - .. note:: All these changes are on the overlay and won't persist after a restart of your Embassy - -#. Add an additional SSH key in your EmbassyUI if you want to access from a machine other than the one you did this setup with. - Access ====== -Now to log in, simply use the following command, using the ``.onion`` hostname you printed above: +To log in, simply use the following command, using the ".onion" hostname you printed above: .. code-block:: diff --git a/site/source/user-manual/updating.rst b/site/source/user-manual/updating.rst index a8095c0..867288f 100644 --- a/site/source/user-manual/updating.rst +++ b/site/source/user-manual/updating.rst @@ -1,31 +1,59 @@ -.. _updates: - -======== -Updating -======== - -Keeping current on Updates ensures a secure and performant system. - -.. _update-eos: +.. _updating-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. +.. note:: EmbassyOS will **NEVER** update itself without your approval. But we highly recommended keeping EmbassyOS up to date for the latest security and performance patches, as well as to take advantage of new features. -.. _auto-check-updates: +How to Update +------------- -Enable Auto Check for Updates ------------------------------ +#. When a new version of EmbassyOS is available, a badge will appear on the "Embassy" tab. +#. Go to *Embassy > Software Update*. -#. 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. + .. warning:: Ensure you have a stable Internet connection before beginning an OS update, and do not unplug your Embassy while EmbassyOS is downloading. -.. 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. +#. Read the release notes and click "Begin Update". +#. While the new version of EmbassyOS is downloading, you may continue to use your device as usual. +#. Once the download is complete, you will be prompted to restart Embassy. +#. After restart, you may be prompted to refresh the browser window. -Manually Checking Updates -------------------------- +Disabling Auto Check for Updates +-------------------------------- -If you choose not to enable automatic update checks, service updates will still appear in the ``Updates`` tab of the Marketplace when ready. +By default, Embassy will automatically check for available updates. To disable this check, do the following: + +#. Navigate to the *Embassy > Preferences*. +#. Click "Auto Check for Updates" and click "Disable". + + .. note:: With auth check for updates disabled, you will need to manually check for updates. This can be done by going to *Embassy > Software Update*. + +This guide will cover how to recover existing Embassy 0.3.x service and user data (on an SSD) to a new OS install (sd card). + +Manual Update by Re-flashing +---------------------------- + +#. Obtain the latest copy of EmbassyOS with your product key included, either by `downloading `_ or `building from source `_. +#. Flash the downloaded image to your microSD card. +#. Insert the microSD card into your Embassy and power it on. + + .. note:: Embassy will power up and then initialize, a process of less than 5 minutes if you purchased an image, or about 10-20 minutes if you built from source. Once complete you will hear a _bep_ to indicate it is initialized and then a _chime_ sound to indicate it is online. + +#. On your computer, open up a browser and go to http://embassy.local. +#. When prompted, enter your Product Key: + + .. figure:: /_static/images/setup/migrate0.png + :width: 60% + +#. Select "Recover". + + .. figure:: /_static/images/setup/migrate1.png + :width: 60% + +#. Assuming you have you fully-intact EmbassyOS data drive plugged in, you will receive a popup declaring that a valid data drive has been detected. Click "Use Drive" from the pop-up. If you don't see the drive, you may get a message asking you to unplug, then plug back in the drive, and refresh the page. + + .. figure:: /_static/images/setup/migrate3.png + :width: 60% + +@TODO get better image ^ diff --git a/site/source/user-manual/migrate-02.rst b/site/source/user-manual/upgrade-02.rst similarity index 91% rename from site/source/user-manual/migrate-02.rst rename to site/source/user-manual/upgrade-02.rst index 8748878..bbfcae8 100644 --- a/site/source/user-manual/migrate-02.rst +++ b/site/source/user-manual/upgrade-02.rst @@ -1,8 +1,8 @@ -.. _migrate-02: +.. _upgrade-02: -================== -Migrate from 0.2.x -================== +==================== +Upgrading from 0.2.x +==================== This guide will cover how to upgrade from EmbassyOS version 0.2.x to version 0.3.0. @@ -20,13 +20,9 @@ Hardware Requirements #. `SD card adapter `_ for getting data from your SD card. -.. _migrate-02-instructions: - Instructions ------------ -.. _migrate-02-backing-up: - Backing up .......... @@ -38,8 +34,6 @@ If you're unsure how to do this - please follow `this `_ -.. _migrate-02-migrate: - -Migrate -....... +Migrate Data +............ #. Begin by going into your Embassy, stopping all running services, and shutting down the device in the Embassy tab. @@ -74,7 +66,7 @@ Power Up #. Embassy will power up and then initialize, a process of less than 5 minutes if you purchased an image, or about 10-20 minutes if you built from source. Once complete you will hear a _bep_ to indicate it is initialized and then a _chime_ sound to indicate it is online. -#. On your computer, open up a browser and go to ``embassy.local`` +#. On your computer, open up a browser and go to http://embassy.local #. You will be asked to enter a product key. This can be located on the bottom of your Embassy if you purchased, or in the repository folder if you built from source. @@ -82,7 +74,7 @@ Power Up :width: 60% -#. Once entered, select ``Recover`` then select the microSD card - this will be labelled ``rootfs``. +#. Once entered, select "Recover" then select the microSD card - this will be labelled ``rootfs``. .. figure:: /_static/images/setup/migrate1.png :width: 60% @@ -97,7 +89,7 @@ Power Up .. note:: If it does not show up, please power down Embassy, unplug it, plug it back in, and boot Embassy again -#. If this drive is not empty, you will see a warning first, indicating all data will be overwritten. If you are happy to proceed, click ``Continue``. +#. If this drive is not empty, you will see a warning first, indicating all data will be overwritten. If you are happy to proceed, click "Continue". .. figure:: /_static/images/setup/migrate4.png :width: 60% @@ -114,7 +106,7 @@ Power Up .. figure:: /_static/images/setup/migrate6.png :width: 60% -#. To use LAN safely, the SSL certificate will need to be added to whatever device you are using to access. This can be downloaded by clicking on ``Download root CA`` and installed by following the :ref:`instructions`. +#. To use LAN safely, the SSL certificate will need to be added to whatever device you are using to access. This can be downloaded by clicking on "Download root CA" and installed by following the :ref:`instructions`. #. You can now log in to your Embassy via Tor or LAN, and you will be given the option of recovering your data on a service-by-service basis. diff --git a/site/source/user-manual/wifi.rst b/site/source/user-manual/wifi.rst index 498831d..8c25c05 100644 --- a/site/source/user-manual/wifi.rst +++ b/site/source/user-manual/wifi.rst @@ -4,9 +4,9 @@ Setting up WiFi =============== -Although we highly recommend a wired (ethernet) connection for best performance, you can connect your Embassy with a wireless connection if you prefer. Follow the directions below to connect to a WiFi network, or save your credentials for later to connect to a network you are not currently in proximity to. +Although a wired (ethernet) connection is recommended for best performance, you can connect your Embassy with a wireless connection if you prefer. Follow the directions below to add one or more WiFi networks to you Embassy. -#. On the ``Embassy`` tab, Under ``Settings``, Click ``WiFi`` +#. Go to *Embassy > WiFi*. .. figure:: /_static/images/config/wifi0.png :width: 60% @@ -18,27 +18,27 @@ Although we highly recommend a wired (ethernet) connection for best performance, :width: 60% :alt: Select Region -#. Select the network you would like from the list of available networks. You will get an idea of signal strength on the right, from red (weak signal) to green (strong signal). If you can move your Embassy closer to the WiFi broadcasting device, you will get a better signal, and as a result, better performance. +#. Select your network from the list of available networks. You will get an idea of signal strength on the right, from red (weak signal) to green (strong signal). If you can move your Embassy closer to the WiFi broadcasting device, you will get a better signal, and as a result, better performance. + + .. tip:: You may also select the network labeled "Other" at the bottom of the list in order to add a hidden network, or a network that is not nearby, for connecting to at a later time. .. figure:: /_static/images/config/wifi2.png :width: 60% :alt: Add WiFi Network - .. tip:: You may also select the network labeled ``Other`` at the bottom of the list in order to add a hidden network, or a network that is not nearby, for connecting to at a later time. - -#. Enter your WiFi password and either select ``Save for Later`` or ``Save and Connect`` to connect immediately. +#. Enter your WiFi password and select "Save for Later" **or** "Save and Connect". .. figure:: /_static/images/config/wifi3.png :width: 60% :alt: Enter Credentials -#. If you saved the network, it will appear in the list when successfully added, but not show connected. If you connect immediately, you will receive a dialogue box and a green checkmark to show connection is live. +#. If you clicked "Save for Later", the network will appear in the list, unconnected. If you selected "Save and Connect", the network will attempt to connect and show a green checkmark upon success. .. figure:: /_static/images/config/wifi4.png :width: 60% :alt: Connect -#. Click on a saved network for connection options. If you are successfully connected, you will receive a dialogue box and a green checkmark to show connection is live. At this point, you can safely disconnect the ethernet cable from your Embassy, if you wish to use WiFi. +#. Once connected to a WiFi network, you may safely disconnect the ethernet cable from your Embassy. .. figure:: /_static/images/config/wifi5.png :width: 60% diff --git a/sphinx-scylladb-theme b/sphinx-scylladb-theme index 9c772de..91c190c 160000 --- a/sphinx-scylladb-theme +++ b/sphinx-scylladb-theme @@ -1 +1 @@ -Subproject commit 9c772de727640dd12a8bdb26ba2cae10819b0288 +Subproject commit 91c190c7991738a632da94e88a88bcfdb093f6e3