Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-04-01 21:13:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Big refactor, many minor fixes (#441)

Browse Source 
* Big refactor, many minor fixes

* Link fixes, icon edits

* Index and ToC fixes

* update icons in theme lib and add to device guides index

* WIP - refactor Initial setup, LAN, FF, others

* First draft ready, many fixes and edits

* Ooops - minor edits and changes on initial setup

* Add change password guide (try 2).

* Remove change password menu item from guides

* Fix display bug, think different

---------

Co-authored-by: Lucy Cifferello <12953208+elvece@users.noreply.github.com>
Co-authored-by: gStart9 <george@start9labs.com>
This commit is contained in:
kn0wmad
2023-07-28 18:02:43 +00:00
committed by GitHub
parent eceae35a2b
commit 09b61c7e33
149 changed files with 1362 additions and 785 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
site/source/user-manual/overview/alt-registries.rst Normal file
View File

@@ -0,0 +1,36 @@
.. _alt-registries:
===========================
Managing Service Registries
===========================
It is critical to Start9's mission that Start9 is **not** a central point of failure. Software distribution is critical infrastructure and therefore the Start9 Marketplace supports adding and accessing of custom registries for maximum resiliency and decentralization.
The most basic method Start9 has made available is the ability to use and distribute packages in their ``.s9pk`` form, which can be simply hosted as a file anywhere you'd like, even on your Start9 server (see below)! Start9 has also built open source tools for the Marketplace UI, to keep the community in maximum control with minimal inconvenience.
See this `blog post <https://blog.start9.com/start9-marketplace-strategy/>`_ for more details.
Changing Registries
-------------------
By default, there are 2 registries available in the Marketplace: Start9 (officially developed/supported) and Community (community developed/supported).
.. 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!!
Go to *Marketplace > Change*.
.. figure:: /_static/images/marketplaces/marketplace-switch0.png
:width: 60%
Adding a Registry
-----------------
Click "Add custom registry" and enter the URL of your desired Marketplace. You may connect immediately, or save for later use.
.. figure:: /_static/images/marketplaces/marketplace-switch1.png
:width: 60%
.. note:: Currently this change will only permit the downloading of *services* from alternative marketplaces. StartOS itself may only be obtained from Start9 (or building from source) at this time.
Hosting a Registry
------------------
You can run your own basic registry using your Start9 server! On each service's GitHub Releases page, such as `Bitcoin <https://github.com/Start9Labs/bitcoind-wrapper/releases/tag/v23.0.0>`_ for example, you will find the ``.s9pk`` Asset. You can download this package, upload to a folder on `File Browser <https://marketplace.start9.com/marketplace/filebrowser>`_ or `Nextcloud <https://marketplace.start9.com/marketplace/nextcloud>`_, and then host it over :ref:`Tor<tor>` using `Start9 Pages <https://marketplace.start9.com/marketplace/embassy-pages>`_!
If you are interested in building and hosting your own full registry that can be accessed in the Start9 Marketplace UI, you can check out the `registry repository <github.com/start9labs/registry>`_.

87
site/source/user-manual/overview/backup-restore/backup-advanced.rst Normal file
View File

@@ -0,0 +1,87 @@
.. _backup-advanced:
=====================
Advanced Backup Tools
=====================
.. warning:: The following are advanced tools and using them is only advised when under the instruction of a Start9 Support Technician. USE AT YOUR OWN RISK - these operations are not supported outside of the context of support.
.. _backup-mount:
Mount a Backup
--------------
#. :ref:`Setup SSH Access<ssh>` and connect to your server via SSH. Elevate yourself to root once in:
.. code-block:: bash
sudo -i
#. Any previously added Network Folder backup location (or physical drive) will be available. Enter the following command:
.. code-block:: bash
embassy-cli backup target list
.. figure:: /_static/images/backups/backup-target-list.png
:width: 60%
#. Select the backup target from the available list. In this example, we could use either ``disk-/dev/sdb1`` or ``cifs-1``:
.. code-block:: bash
embassy-cli backup target mount disk-/dev/sdb1 "YourMasterPasswordGoesHere"
.. figure:: /_static/images/backups/backup-mount.png
:width: 60%
The terminal will print the directory where your decrypted backup is now mounted.
#. `ls` the directory to inspect it, and continue any other operations necessary:
.. figure:: /_static/images/backups/backup-mount-ls.png
:width: 60%
.. _backup-mount-data-drive:
Mount a StartOS Data Drive
--------------------------
If you have an encrypted disk from a prior StartOS installation, you can mount its decrypted contents on a Linux computer.
#. Attach the StartOS data drive to your Linux desktop or laptop computer.
#. Ensure cryptsetup is installed:
.. code-block:: bash
sudo apt update && sudo apt install cryptsetup
#. Enter the following command to reveal your disk's crypto_LUKS filesystems and their labels:
.. code-block:: bash
lsblk --fs
.. figure:: /_static/images/backups/disk-mount-1-lsblk.png
:width: 60%
We are interested in the services data so copy the long label ending with ``package-data``.
#. Take that label, prepend ``/dev/mapper/`` to it, and feed it to ``cryptsetup``:
.. code-block:: bash
sudo cryptsetup open /dev/mapper/EMBASSY_NBMVE7OASAPTIIXNEPFN6PLAPJNT72F2XAVK43L2PGB6O2JRB35A-package--data startos_data_unlocked
You will be prompted for the password to decrypt the filesystem which is ``password``, and a new device mapping called `startos_data_unlocked` will be created.
#. Mount the `startos_data_unlocked` device at a path of your choosing. Here, we will use ``/mnt/startos_data``:
.. code-block:: bash
sudo mkdir /mnt/startos_data
sudo mount /dev/mapper/startos_data_unlocked /mnt/startos_data
#. Inspect the decrypted files in preparation for copying via ``cp``, ``scp``, ``rsync`` or similar utility:
.. figure:: /_static/images/backups/disk-mount-3-inspect.png
:width: 60%

62
site/source/user-manual/overview/backup-restore/backup-create.rst Normal file
View File

@@ -0,0 +1,62 @@
.. _backup:
======
Backup
======
Backing up your server is easy and secure. Backups are encrypted with your master password.
.. contents::
:depth: 2
:local:
.. tip:: Create frequent backups to keep your data safe!
Setup Device
------------
Select your platform for detailed instructions on how to create a Network Folder for creating backups. This can include a drive in, or attached to, a device on your network. Otherwise, you may backup directly to a :ref:`physical drive<backup-physical>`, attached to your server.
* :ref:`Linux Network Folder <backup-linux>`
* :ref:`Mac Network Folder <backup-mac>`
* :ref:`Windows Network Folder <backup-windows>`
* :ref:`Synology Network Folder <backup-synology>`
* :ref:`TrueNAS Network Folder <backup-truenas>`
* :ref:`Physical Drive <backup-physical>`
.. _backup-create:
Create Backup
-------------
#. Go to *System > Create Backup*
.. figure:: /_static/images/config/backup.png
:width: 60%
#. You will see your previously created Network Folder backup location (or Physical Drive) available. Click it, select the services you wish to backup, then click "**BACK UP SELECTED**":
.. figure:: /_static/images/config/backup2.png
:width: 60%
#. You will be prompted for your server's master password:
.. figure:: /_static/images/config/backup2.5.png
:width: 60%
#. The backup will begin. You can continue to use your server while the backup is in progress.
.. figure:: /_static/images/config/backup3.png
:width: 60%
#. When the backup is complete, you will receive a notification where a detailed report is available.
.. figure:: /_static/images/config/backup4.png
:width: 60%
#. If successful, you will also see the date and time of your most recent backup under **BACKUPS** in the **System** tab:
.. figure:: /_static/images/config/backup5.png
:width: 60%

40
site/source/user-manual/overview/backup-restore/backup-physical.rst Normal file
View File

@@ -0,0 +1,40 @@
.. _backup-physical:
========================
Backup to Physical Drive
========================
.. tip:: Create frequent backups to avoid loss of data!
.. youtube:: KJRO9wGOOVw
:width: 100%
The recommended method of backup (including with external drives) is to setup a :ref:`Network Folder<backup>` via your OS. However, you may use an external drive plugged directly into your server.
.. warning:: If you are using a low-powered device (like a RasPi), this drive MUST have external power, or be connected via a powered USB hub in order to prevent any data corruption due to power constraints! Server One and Server Pure users can safely ignore this warning.
#. 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 Start9 server blue USB 3.0 slot. If not, first plug the drive into a powered USB hub, then plug the hub into your Start9 server. Then you may power it up.
#. Go to *System > Create Backup*
.. figure:: /_static/images/config/backup.png
:width: 60%
#. Select your drive.
.. figure:: /_static/images/config/physical-backup1.png
:width: 60%
.. figure:: /_static/images/config/physical-backup2.png
:width: 60%
#. Enter your StartOS master password.
.. figure:: /_static/images/config/backup3.png
:width: 60%
#. When the backup is complete, you will receive a notification. If successful, you will see the date and time of your most recent backup updated under "Backups" in the System tab.
.. figure:: /_static/images/config/backup4.png
:width: 60%

148
site/source/user-manual/overview/backup-restore/backup-restore.rst Normal file
View File

@@ -0,0 +1,148 @@
.. _backup-restore:
=======
Restore
=======
There are 3 different ways that you may choose to recover server data, as well as a 4th option to migrate/transfer data between hardware.
#. "Restore [individual services] from Backup" to your currently running server. This is specifically for service data.
#. "Use Existing Drive" a drive with existing server data on it during setup. Use this when re-flashing your SD card, for example.
#. "Restore [entire server] from Backup" (as in, disaster recovery) all server data in the event that your backup is the **only** thing you have left.
#. "Transfer" data from an existing server. This is a total migration for use when upgrading hardware only.
.. warning:: If you are restoring data from a drive that you are attaching *directly to your server,* (if using a RasPi or other low-powered board) please ensure that it is getting adequate power. This is best accomplished via external power to the drive (such as a powered USB hub). Server One (2022 and newer) and Server Pro users can safely ignore this warning.
Select the appropriate tab below to restore your data:
.. tabs::
.. group-tab:: Restore
#. Go to *System > Restore From Backup*.
.. figure:: /_static/images/config/restore0.png
:width: 60%
#. Select existing backup from either Network Folders or Physical. In this example, we'll select a Network Folder backup.
.. figure:: /_static/images/config/restore1.png
:width: 60%
#. Enter your master password.
.. figure:: /_static/images/config/restore2.png
:width: 60%
#. Previously backed up services will appear in the window. Select the service(s) you'd like to restore and click "Restore Selected".
.. figure:: /_static/images/config/restore3.png
:width: 60%
It is not possible to recover services that are already installed. If you wish to recover a service that is already installed, please uninstall it first to permit recovery.
.. group-tab:: Attach
#. During :ref:`Initial Setup<initial-setup>`, select "Recover."
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.png
:width: 60%
#. Next, select "Use Existing Drive."
.. figure:: /_static/images/setup/screen3-use_existing.png
:width: 60%
#. Select your server's data drive.
.. figure:: /_static/images/setup/screen4-use_existing_drive_selection.png
:width: 60%
#. Enter and confirm a new password.
.. figure:: /_static/images/setup/screen5-set_password.jpg
:width: 60%
#. Your server will initialize again (all previous data will be recovered).
.. figure:: /_static/images/setup/screen6-storage_initialize.jpg
:width: 60%
.. group-tab:: Recover
#. During :ref:`Initial Setup<initial-setup>`, select "Recover."
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.png
:width: 60%
#. Select "Restore From Backup."
.. figure:: /_static/images/restore/recover0.png
:width: 60%
#. If you have a physical backup, plug it in and select the drive. If it does not appear, try another USB 3.0 (blue) port and hit refresh, then select the drive and skip to step 5 (enter drive encryption password). If you are using a Network Folder, click "Open."
.. figure:: /_static/images/restore/recover1.png
:width: 60%
#. Enter the details for your Network Folder and click "Verify." Check the appropriate :ref:`backup setup page<backup>` for reference if you are unsure of the parameters.
.. figure:: /_static/images/restore/recover2.png
:width: 60%
#. Enter the encryption password for the drive (this is your server's master password).
.. figure:: /_static/images/restore/recover3.png
:width: 60%
#. Select the drive (from your new hardware) that you are recovering onto.
.. warning:: This will **PERMANENETLY ERASE** any existing data on that drive. If you re-using an old drive, ensure that you have first removed all your data!!
.. figure:: /_static/images/restore/recover4.png
:width: 60%
.. figure:: /_static/images/restore/recover5.png
:width: 60%
#. Your server will now prepare and then copy the data to the new drive. The time required can vary greatly depending on how much data you are migrating and from where that data is coming. Be prepared for this to take many hours, especially if you have 1-2TB+ of data. Go have a sandwich and contemplate other aspects of your sovereignty.
.. figure:: /_static/images/restore/recover6.png
:width: 60%
.. group-tab:: Transfer
#. During :ref:`Initial Setup<initial-setup>`, select "Recover."
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.png
:width: 60%
#. Select "Transfer"
.. figure:: /_static/images/transfer/transfer0.png
:width: 60%
#. Plug in the drive (make sure it is powered on) of the server you are migrating **from** and select it (in this example, /dev/sda). You may need to try a different USB port and hit "Refresh" if you don't see it immediately. You will see a warning about using the old drive again; read and understand it.
.. figure:: /_static/images/transfer/transfer1.png
:width: 60%
#. Select the drive on your new server (that you are migrating **onto**).
.. figure:: /_static/images/transfer/transfer2.png
:width: 60%
.. warning:: This will **PERMANENETLY ERASE** any existing data on that drive. If you re-using an old drive, ensure that you have first removed all your data!!
#. Set your new master password. *Make it good. Write it down.* Click finish.
.. figure:: /_static/images/transfer/transfer3.png
:width: 60%
.. figure:: /_static/images/transfer/transfer4.png
:width: 60%
#. Your server will now initialize and migrate the old data to the new drive. The time required can vary greatly depending on how much data you are migrating. Be prepared for this to take many hours, especially if you have 1-2TB+ of data. Go have a sandwich and contemplate other aspects of your sovereignty.
.. figure:: /_static/images/transfer/transfer5.png
:width: 60%

55
site/source/user-manual/overview/backup-restore/backup-synology.rst Normal file
View File

@@ -0,0 +1,55 @@
.. _backup-synology:
=======================
Synology Network Folder
=======================
.. contents::
:depth: 2
:local:
.. 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.
Setup Network Folder
--------------------
#. In the Synology UI, go to *Control Panel > Shared Folder* and choose the folder you want to use as the destination for the backup.
.. note:: Do not select an encrypted folder. Encrypted folders on Synology enforce a character limit of 143 characters. At this time, StartOS backups use folder/file names that are longer than 143 characters. The backup process will fail if you try to backup to an encrypted folder.
#. Still in the Synology UI, go to *Control Panel > File Services > SMB* and click the SMB tab if it isn't already selected. Ensure that "Enable SMB service" is checked.
#. Under Advanced Settings on the same tab, set "Min SMB protocol" to SMB2 and "Max SMB protocol" to SMB3
#. Also on the SMB tab, take note of your device name. Just under "Note" in a pale blue box, you will see "PC (Windows Explorer): " and "Mac (Finder):". These both provide network addresses that contain your device's name. This device name is the "Hostname" you will need to provide within the StartOS "New Network Folder" dialog in step 3 of the "Connect StartOS" section below.
#. Still in File Services, click on the rsync tab. Click the checkbox to enable the rsync service.
#. Back in the Synonogy UI, click "File Station" and locate the the desired destination folder. Right click the folder, then *Properties > General*. Next to "Location" will be a folder location. The portion of the location *without the volume label* is the value you will use for the "Path" within the StartOS New Network Folder dialog. For example, if the Location is `/volume1/Backups`, the value you care about is `Backups`.
Connect StartOS
---------------
#. Go to *System > Create Backup*.
.. figure:: /_static/images/config/backup.png
:width: 60%
#. Click "Open".
.. figure:: /_static/images/config/backup0.png
:width: 60%
#. Fill in the following fields:
* Hostname - This is the hostname of the destination machine
* Path - This is the name of the destination folder (e.g. `Backups` from the example above)
* 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/backup1.png
:width: 60%
#. Click "Save".
That's it! You can now :ref:`Create<backup-create>` encrypted, private backups of all your Start9 server's data to your Synology NAS!

101
site/source/user-manual/overview/backup-restore/backup-truenas.rst Normal file
View File

@@ -0,0 +1,101 @@
.. _backup-truenas:
======================
TrueNAS Network Folder
======================
.. contents::
:depth: 2
:local:
.. 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.
Setup Network Folder
--------------------
.. note:: This guide assumes you have already created a ZFS disk pool in *Storage > Pool* as a place to store your backups. If you need help with this step, see the `TrueNAS documentation <https://www.truenas.com/docs/scale/scaletutorials/storage/pools/createpoolscale/#creating-a-pool>`_.
#. In the TrueNAS UI, to add a user who will write the backups from the Start9 server to the NAS, go to **Accounts > Users > ADD**:
.. figure:: /_static/images/backups/truenas-1-users.png
:width: 60%
#. Fill in a human-readable **Full Name**, **Username**, and **Password** for the new user:
.. figure:: /_static/images/backups/truenas-2-newuser.png
:width: 60%
Near the bottom, select **Shell: nologin**, and enable **Samba Authentication**.
Click **SUBMIT**
#. Enable the SMB service via **Services > SMB**:
.. figure:: /_static/images/backups/truenas-3-services-enable_smb.png
:width: 60%
Also ensure the **Start Automatically** box is checked.
#. Open a shell and create your backups directory:
.. figure:: /_static/images/backups/truenas-4-shell-mkdir.png
:width: 60%
In this example, we will create a directory called *start9backupshare* on the root of our storage pool:
.. code-block:: bash
mkdir /mnt/zpooldisk1/start9backupshare
This is the example path we will use in this guide. You may choose a different name or path.
#. Under **Sharing > Windows Shares (SMB)**, drill down into the path until you find the directory to be shared:
.. figure:: /_static/images/backups/truenas-5-sharing-smb-create_share.png
:width: 60%
We give the share the **Name** *nasshare*
Click **SUBMIT** to create the share.
#. A **Configure ACL** dialog will emerge. Click **CONFIGURE NOW**:
.. figure:: /_static/images/backups/truenas-6-sharing-smb-config_acl.png
:width: 60%
#. You will be brought to an **Edit ACL** screen.
Under **User** check "Apply User" and select or type the username we created in Step 2:
.. figure:: /_static/images/backups/truenas-7-acl.png
:width: 60%
Off to the right-hand side, *Permissions Type* should be set to "Basic" and *Permissions* should be set to "Full Control".
Click **SAVE**
Connect StartOS
---------------
#. Go to *System > Create Backup*.
.. figure:: /_static/images/config/backup.png
:width: 60%
#. Click "Open".
.. figure:: /_static/images/config/backup0.png
:width: 60%
#. Fill in the following fields:
* Hostname - Enter your truenas hostname: `truenas.local`
* Path - This is the "Name" of the share that we set in step 5: *nasshare*
* Username - This is the Username of the user we created in Step 2: *s9backup*
* Password - This is the Password of that user, also set in Step 2
.. figure:: /_static/images/backups/truenas-9-start9server-create_backup.png
:width: 60%
#. Click "Save".
That's it! You can now :ref:`Create<backup-create>` encrypted, private backups of all your Start9 server's data to your TrueNAS!

54
site/source/user-manual/overview/backup-restore/index.rst Normal file
View File

@@ -0,0 +1,54 @@
.. _backups:
=======
Backups
=======
In addition to the safe-keeping of a good master password, maintaining good backups is the major responsibility required to keep the benefits and freedom that come with self-hosting.
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Create Backup
:link: backup-create
:icon: scylla-icon scylla-icon--cloud
:class: large-5
:anchor: Backup
Create an encrypted backup of your server data.
.. topic-box::
:title: Restore From Backup
:link: backup-restore
:icon: scylla-icon scylla-icon--live-test
:class: large-5
:anchor: Restore
Restore your server data from a previous backup.
.. topic-box::
:title: Advanced Backup Tools
:link: backup-advanced
:icon: scylla-icon scylla-icon--live-test
:class: large-5
:anchor: View
Tools for backups - use only at the direction of support, or at your own risk.
.. raw:: html
</div></div>
.. toctree::
:maxdepth: 1
:hidden:
backup-create
backup-restore
backup-physical
backup-synology
backup-truenas
backup-advanced

33
site/source/user-manual/overview/change-password.rst Normal file
View File

@@ -0,0 +1,33 @@
.. _change-password:
===============
Password Change
===============
This guide is for changing your password from the web-UI. If you forgot your password and want to reset it, see the :ref:`reset password guide<reset-password>`.
#. Login to the web-UI and navigate to System > Change Master Password
.. figure:: /_static/images/config/password_change_ui-1.png
:width: 60%
#. A warning will be displayed. Select `CONTINUE`.
.. figure:: /_static/images/config/password_change_ui-2.png
:width: 60%
#. Fill out the Change Master Password form by entering
a. Your current password
b. Your desired new password
c. Retype your new password
d. Click `Save`
.. figure:: /_static/images/config/password_change_ui-3.png
:width: 60%
#. You will see a notice pop up near the bottom of the screen informing you that you've successfully changed your password:
.. figure:: /_static/images/config/password_change_ui-4.png
:width: 60%

11
site/source/user-manual/overview/connecting/connecting-ff.rst Normal file
View File

@@ -0,0 +1,11 @@
.. _connecting-ff:
=====================
Firefox Configuration
=====================
Select your OS below to configure Firefox for encrypted sessions and Tor compatability. See our :ref:`Device Guides<device-guides>` section for all your client's setup guides.
:ref:`Linux<ff-linux>`
:ref:`Mac<ff-mac>`
:ref:`Windows<ff-windows>`
:ref:`Android<ff-android>`

60
site/source/user-manual/overview/connecting/connecting-lan.rst Normal file
View File

@@ -0,0 +1,60 @@
.. _connecting-lan:
===============
LAN Connections
===============
Whenever you are connected to the same Local Area Network (LAN) as your Start9 server, it is best to access your Start9 server's LAN Address (.local URL). LAN connections are fast and secure and do not even require Internet access!
Select your OS below to connect via LAN. See our :ref:`Device Guides<device-guides>` section for all your client's setup guides.
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Linux
:link: ../../../../guides/device-guides/dg-linux/lan-linux
:icon: scylla-icon scylla-icon--linux
:class: large-4
:anchor: Connect
Integrate Linux devices
.. topic-box::
:title: Mac
:link: ../../../../guides/device-guides/dg-mac/lan-mac
:icon: scylla-icon scylla-icon--apple
:class: large-4
:anchor: Connect
Integrate Mac devices
.. topic-box::
:title: Windows
:link: ../../../../guides/device-guides/dg-windows/lan-windows
:icon: scylla-icon scylla-icon--windows
:class: large-4
:anchor: Connect
Integrate Windows devices
.. topic-box::
:title: Android
:link: ../../../../guides/device-guides/dg-android/lan-android
:icon: scylla-icon scylla-icon--android
:class: large-4
:anchor: Connect
Integrate Android devices
.. topic-box::
:title: iOS
:link: ../../../../guides/device-guides/dg-ios/lan-ios
:icon: scylla-icon scylla-icon--ios
:class: large-4
:anchor: Connect
Integrate iOS devices

32
site/source/user-manual/overview/connecting/connecting-tor.rst Normal file
View File

@@ -0,0 +1,32 @@
.. _connecting-tor:
===============
Tor Connections
===============
You can connect to your Start9 server from anywhere in the world, privately and anonymously, by using its unique Tor Address (``.onion`` URL).
.. note:: Tor connections can sometimes be unreliable and have higher latency than normal internet connections.
Select your OS below to connect via Tor. See our :ref:`Device Guides<device-guides>` section for all your client's setup guides.
:ref:`Linux<tor-linux>`
:ref:`Mac<tor-mac>`
:ref:`Windows<tor-windows>`
:ref:`Android<tor-android>`
:ref:`iOS<tor-ios>`
Using TorBrowser
-------------------
.. caution:: Tor Browser will allow you to use your Start9 server's ``.onion`` URL without any manual configuration, however *all* connections are proxied via Tor, so you will not be able to access your Start9 server's ``.local`` LAN address with it. `Using Firefox <#using-firefox>`_ is recommended over TorBrowser.
* Linux, Mac, Windows, Android
* `Tor Browser <https://torproject.org/download/>`_
* iOS
* iOS lacks a well-functioning Tor Browser. Use :ref:`Firefox<tor-ios>`.

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

@@ -0,0 +1,41 @@
.. _connecting:
===================
Network Connections
===================
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Connecting Over LAN
:link: connecting-lan
:icon: scylla-icon scylla-icon--home
:class: large-5
:anchor: Setup
Local Area Network connections are fast and secure and do not even require Internet access.
.. topic-box::
:title: Connecting Over Tor
:link: connecting-tor
:icon: scylla-icon scylla-icon--networking
:class: large-5
:anchor: Setup
Leverage Tor to connect to your Start9 server privately and anonymously from anywhere in the world.
.. raw:: html
</div></div>
.. toctree::
:maxdepth: 2
:hidden:
connecting-lan
connecting-tor
connecting-ff

24
site/source/user-manual/overview/customize.rst Normal file
View File

@@ -0,0 +1,24 @@
.. _customize:
=========
Customize
=========
.. contents::
:depth: 2
:local:
Custom Browser Tab Title
------------------------
#. Go to *System > Browser Tab Title*.
.. figure:: /_static/images/config/basic-config1.png
:width: 60%
:alt: Preferences
#. Enter the desired name and click ``Save``
.. figure:: /_static/images/config/basic-config2.png
:width: 60%
:alt: Custom browser tab

121
site/source/user-manual/overview/dashboard-overview.rst Normal file
View File

@@ -0,0 +1,121 @@
.. _dashboard-overview:
=========
Dashboard
=========
.. contents::
:depth: 2
:local:
Connection Status
-----------------
In the bottom left of your screen you can monitor whether or not you are connected to your server.
When connected it will look like this:
.. figure:: /_static/images/walkthrough/connection_status_alive.png
:width: 60%
When connecting it will look like this:
.. figure:: /_static/images/walkthrough/connection_status_connecting.png
:width: 60%
If you have no connection, it will look like this:
.. figure:: /_static/images/walkthrough/connection_status_nointernet.png
:width: 60%
Services Tab
------------
Use this tab to view and access your installed services.
.. figure:: /_static/images/walkthrough/servicestab.png
:width: 60%
Marketplace Tab
---------------
Use this tab to access your preferred Marketplace, where you can discover and install new services, or update existing services.
Check out a live version of Start9's Official Marketplace `here <https://marketplace.start9.com>`_.
.. figure:: /_static/images/walkthrough/markettab.png
:width: 60%
Updates Tab
-----------
Use this tab to update services. A green icon will appear next to this tab when a new update is available.
.. figure:: /_static/images/walkthrough/updatestab.png
:width: 60%
Notifications Tab
-----------------
Notifications issued by StartOS 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%
System Tab
-----------
Use this tab to customize and manage StartOS.
.. figure:: /_static/images/walkthrough/systemtab.png
:width: 60%
Read below for a summary of each section within the System Tab.
Backups
=======
The Backups section allows you to create and restore :ref:`StartOS backups <backups>`.
Manage
======
The Manage section gives you access to :ref:`updating-eos`, Software Updates, Device Preferences, :ref:`connecting-lan`, :ref:`ssh`, :ref:`wifi`, and Service Sideloading.
Insights
========
The Insights section gives you basic information on your your server, monitoring of system resources / temperature, and logs for debugging.
Support
=======
The Support section provides links to frequently asked questions as well as Start9 and community contact information.
Power
=====
* **Log Out**
* This will log you out and return you to the log in screen.
* **Restart**
* Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
* A gentle *bep* will sound when the server is powered back on.
* A *chime* will sound when the server is ready to use. Please be patient as a Restart will take some time.
* **Shutdown**
.. caution:: After a shutdown, the *only* way to turn your server back on is to unplug it and plug it back in. As such, we do not recommend shutting down your server 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 your server from power and the ethernet cable, if connected.
* **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 server.

22
site/source/user-manual/overview/index.rst Normal file
View File

@@ -0,0 +1,22 @@
.. _overview:
================
StartOS Overview
================
Welcome to StartOS! Get familiar with your server by discovering all the available features.
.. toctree::
:includehidden:
:maxdepth: 1
dashboard-overview
change-password
managing-services
backup-restore/index
customize
updating
connecting/index
sessions
ssh
wifi
alt-registries

164
site/source/user-manual/overview/managing-services.rst Normal file
View File

@@ -0,0 +1,164 @@
.. _managing-services:
=================
Managing Services
=================
.. contents::
:depth: 2
:local:
StartOS 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<web-ui>`.
* **Health Checks**: This is a critical feature of StartOS. 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 <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 <service-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 Installed* at any time to view install progress.
.. figure:: /_static/images/services/service3.png
:width: 60%
Updating a Service
------------------
.. note:: StartOS will **NEVER** update a service without your consent.
To see if an update is available for a service, you can visit the *Updates* tab or visit the service's Marketplace listing.
.. figure:: /_static/images/services/updatestab2.png
:width: 60%
.. figure:: /_static/images/services/update-marketplace-listing.png
:width: 60%
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! StartOS'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 service 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 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 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, go to *Services > [Service Name] > Interfaces*
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*

23
site/source/user-manual/overview/sessions.rst Normal file
View File

@@ -0,0 +1,23 @@
.. _session-management:
==================
Session Management
==================
Every time a login is made with StartOS, such as from a web browser on your laptop or mobile device, a :ref:`Session <sessions>` is created.
* To view and manage your active sessions, go to *System > Active Sessions*.
.. figure:: /_static/images/walkthrough/sessions0.png
:width: 60%
* To end an active session and log out of that device, click "LOGOUT" to the right of where that session is listed.
.. figure:: /_static/images/walkthrough/sessions1.png
:width: 60%
* To end all sessions except for the session you are currently using - click "TERMINATE ALL"
.. figure:: /_static/images/walkthrough/sessions3.png
:width: 60%

198
site/source/user-manual/overview/ssh.rst Normal file
View File

@@ -0,0 +1,198 @@
.. _ssh:
=========
Using SSH
=========
Like most Linux distributions, you can go "under-the-hood" via SSH (Secure Shell Protocol) if you choose. It's a good idea to have set up, but generally, all server access is recommended via the UI. If you are auditing, doing dev work, hacking (with an understanding of the consequences), or are directed to by a Start9 support tech, then you may need SSH access.
For security reasons, password access is not available in most situations, so you will need to add an SSH key to your server via the method below.
.. contents::
:depth: 2
:local:
Creating an SSH Key
-------------------
#. Open a terminal and enter the following command:
.. code-block:: bash
ssh-keygen -t ed25519
You will be asked to ``Enter a file in which to save the key`` - we recommend you press ``Enter`` to use the default location
#. Create a strong passphrase and save it somewhere safe, or press ``Enter`` for no passphrase
.. note:: The next 3 steps only apply to Linux and macOS. If you are on Windows, please skip down to :ref:`Registering an SSH Key<registering-an-ssh-key>`.
#. It will inform you that your public key has been saved. Take note of this path:
.. code-block:: bash
Your public key has been saved in /home/user/.ssh/id_ed25519.pub
#. Next, start your system's ``ssh-agent``:
.. code-block:: bash
eval "$(ssh-agent -s)"
#. Now add your key to it:
.. code-block:: bash
ssh-add ~/.ssh/id_ed25519
Note that if you changed the file name/location in step 1, you will need to use that file/path in this step
.. _registering-an-ssh-key:
Registering an SSH Key
----------------------
#. In the StartOS dashboard, navigate to *System > SSH*.
#. Click "Add New Key".
#. Back in the terminal of your workstation, display and copy your SSH *public* key (created above):
On Mac simply copy your key to clipboard by typing the following into a terminal:
.. code-block:: bash
pbcopy < ~/.ssh/id_ed25519.pub
On Linux:
.. code-block:: bash
cat ~/.ssh/id_ed25519.pub
On Windows:
.. code-block:: bash
type .ssh\id_ed25519.pub
Copy the whole resulting line that looks similar to:
.. code-block:: bash
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINH3tqX71XsPlzYhhoo9CqAP2Yx7gsGTh43bQXr1zqoq user@ema.il
#. Paste that line into the `Add New Key` text field
.. figure:: /_static/images/walkthrough/ssh_key_add.jpg
#. Click **Submit**
You are now ready to SSH into your server!
.. _connecting-via-ssh:
Connecting via CLI
------------------
#. You can now access your Start9 server from the command line (Linux and Mac) using:
.. code-block:: bash
ssh start9@SERVER-HOSTNAME
Replacing ``<SERVER-HOSTNAME>`` with your server's LAN (``<custom-address>.local``) address
.. note:: If you get a scary looking warning that says something like "WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!" - fear not! This is most likely happening because you have recently reflashed or did an update from pre-v0.3.3, which would cause a change in the key for your device's hostname (e.g. `xxxxxxxx.local`) or IP address (e.g. `192.168.1.x`). The solution is to delete the existing entry from your `known_hosts` file, which is typically located at `~/.ssh/known_hosts`. This will be specified in the warning, along with a helpful line number (in case your file is lengthy).
Connecting via PuTTY on Windows
-------------------------------
Following the commands above for Windows will get you in. However, if you prefer a GUI tool, `BrewsBitcoin <https://brewsbitcoin.com>`_ has created `a guide for connecting via SSH using PuTTY on Windows. <https://medium.com/@brewsbitcoin/ssh-to-start9-embassy-from-windows-4a4e17891b5a>`_
Using SSH Over Tor
------------------
.. note:: The following guide requires that you have already added an :ref:`SSH key to your server<ssh>`.
.. caution:: SSH over Tor is only supported on Linux and macOS, although it can also work on Windows with in PuTTY `like this <https://tor.stackexchange.com/a/143>`_. Note that those instructions use port 9150 but we've configured Tor in Windows on the traditional port: ``9050``.
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:
.. tabs::
.. group-tab:: Debian / Ubuntu
.. code-block:: bash
sudo apt install torsocks
.. group-tab:: Arch / Garuda / Manjaro
.. code-block:: bash
sudo pacman -S torsocks
#. SSH in:
.. warning:: The changes you make here are on the overlay and won't persist after a restart of your server.
.. code-block:: bash
ssh start9@<custom-address>.local
#. Elevate yourself to root in chroot edit mode (which will make your changes persist across reboots):
.. code-block:: bash
sudo /usr/lib/embassy/scripts/chroot-and-upgrade
#. Using Vim or Nano, add the following 2 lines to ``/etc/tor/torrc``
.. code-block:: bash
HiddenServiceDir /var/lib/tor/ssh
HiddenServicePort 22 127.0.0.1:22
.. 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
#. Restart your Start9 server by exiting chroot edit mode:
.. code-block:: bash
exit
#. SSH in to your Start9 server again and gather the ".onion" address that was generated:
.. code-block:: bash
cat /var/lib/tor/ssh/hostname
.. note:: Your newly generated .onion address is unique for SSH access only and should not be confused with the main .onion address for the server.
Configure local SSH client
..........................
#. You'll need to add the following configuration to your SSH config file, which will allow you to use SSH over Tor on any Unix-based system:
.. code-block:: bash
echo -e "Host *.onion\n ProxyCommand nc -xlocalhost:9050 %h %p\n" >> ~/.ssh/config
This command adds a wildcard setting for .onion domains to your SSH config file. Any .onion domains you connect to using SSH will use the specified proxy command.
Note: You only need to run this command only once to set up the SSH Over Tor configuration.
Access
======
To log in, simply use the following command, using the ".onion" hostname you printed above:
.. code-block::
ssh start9@xxxxxxxxxxxxxxxxx.onion

38
site/source/user-manual/overview/updating.rst Normal file
View File

@@ -0,0 +1,38 @@
.. _updating-eos:
================
Updating StartOS
================
.. contents::
:depth: 2
:local:
.. note:: StartOS will **NEVER** update itself without your approval. But we highly recommended keeping StartOS up to date for the latest security and performance patches, as well as to take advantage of new features.
How to Update
-------------
#. When a new version of StartOS is available, a badge will appear on the "System" tab.
#. Go to *System > Software Update*.
.. warning:: Ensure you have a stable Internet connection before beginning an OS update, and do not unplug your server while StartOS is downloading.
#. Read the release notes and click "Begin Update".
#. While the new version of StartOS is downloading, you may continue to use your device as usual.
#. Once the download is complete, you will be prompted to restart your server.
#. After restart, but before the web interface becomes available again, there may be an upgrade period of up to thirty minutes while data is transitioned.
**Do not unplug or otherwise power off your server during this period.**
Next, you may be prompted to refresh the browser window.
.. _manual-update:
Manual Update
-------------
In some cases, it may be necessary to manually update by :ref:`re-flashing StartOS<flashing>`. Reasons might include:
- Updating from a beta or other experimental install
- :ref:`Reset your password<reset-password>`
- Something went wrong during an update (very rare)

45
site/source/user-manual/overview/wifi.rst Normal file
View File

@@ -0,0 +1,45 @@
.. _wifi:
===============
Setting up WiFi
===============
Although a wired (ethernet) connection is recommended for best performance, you can connect your server with a wireless connection if you prefer. Follow the directions below to add one or more WiFi networks.
#. Go to *System > WiFi*.
.. figure:: /_static/images/config/wifi0.png
:width: 60%
:alt: Select Region
#. Select the appropriate region at the top
.. figure:: /_static/images/config/wifi1.png
:width: 60%
:alt: Select Region
#. 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 server 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
#. 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 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
#. Once connected to a WiFi network, you may safely disconnect the ethernet cable from your server.
.. figure:: /_static/images/config/wifi5.png
:width: 60%
:alt: Connect