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

Update/035 (#529)

Browse Source 
* update initial setup images and some copy

* rename backups

* cleanup and fix build errors

* reconfigure for 035 deployment

* Alignment

* Initial Root CA trust

* Wording touchups and Pro>Pure

* Remove extraneous message

* Simplify anchor text

* restructure backups

* update setup wizard screenshots

* Update firmware link and filename

* update branches list

* copy updates

* update copy to make anchor tags cleaner

* Remove FAQ, link to website FAQ

* add missing troubleshooting links

---------

Co-authored-by: gStart9 <george@start9labs.com>
Co-authored-by: Matt Hill <mattnine@protonmail.com>
Co-authored-by: agent <kn0wmad@protonmail.com>
This commit is contained in:
Lucy
2023-11-03 15:16:52 -04:00
committed by GitHub
parent e202b1a160
commit ddebb08873
89 changed files with 459 additions and 1116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,87 +0,0 @@
.. _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
start-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
start-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 -y 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/backup-restore/backup-create.rst
View File

@@ -1,62 +0,0 @@
.. _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/backup-restore/backup-physical.rst
View File

@@ -1,40 +0,0 @@
.. _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%

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

@@ -1,55 +0,0 @@
.. _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/backup-restore/backup-truenas.rst
View File

@@ -1,101 +0,0 @@
.. _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!

69
site/source/user-manual/backups/backup-create.rst Normal file
View File

@@ -0,0 +1,69 @@
.. _backup-create:
=============
Backup Create
=============
Choose your backup target
-------------------------
You can back up your data to a physical drive plugged into the server, or over-the-air to a network folder shared from another device on the same LAN.
Physical Drive
..............
#. Ensure your backup drive is properly formatted. The recommended format at this time is ``exFAT``. **Do not** use ``fat32``.
#. Plug your physical drive 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.
Network Folder
..............
Choose your destination platform below for instructions on creating and sharing a network folder.
* :ref:`Linux <backup-linux>`
* :ref:`Mac <backup-mac>`
* :ref:`Windows <backup-windows>`
* :ref:`Synology <backup-synology>`
* :ref:`TrueNAS <backup-truenas>`
Create the Backup
-----------------
#. Go to *System > Create Backup*
.. figure:: /_static/images/config/backup.png
:width: 60%
#. Select the network folder or physical drive you want to target, then select the services you want to back up.
.. 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%

24
site/source/user-manual/backup-restore/backup-restore.rst → site/source/user-manual/backups/backup-restore.rst
View File

@@ -1,8 +1,8 @@
.. _backup-restore:
=======
Restore
=======
==============
Backup 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.
@@ -11,7 +11,7 @@ There are 3 different ways that you may choose to recover server data, as well a
#. "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.
.. 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 Pure users can safely ignore this warning.
Select the appropriate tab below to restore your data:
@@ -45,22 +45,22 @@ Select the appropriate tab below to restore your data:
#. During :ref:`Initial Setup<initial-setup>`, select "Recover."
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.png
.. figure:: /_static/images/setup/screen0-recover.jpg
:width: 60%
#. Next, select "Use Existing Drive."
.. figure:: /_static/images/setup/screen3-use_existing.png
.. figure:: /_static/images/setup/screen3-use_existing.jpg
:width: 60%
#. Select your server's data drive.
.. figure:: /_static/images/setup/screen4-use_existing_drive_selection.png
.. figure:: /_static/images/setup/screen4-use_existing_drive_selection.jpg
:width: 60%
#. Enter and confirm a new password.
.. figure:: /_static/images/setup/screen5-set_password.jpg
.. figure:: /_static/images/setup/screen5-set_password_complete.jpg
:width: 60%
#. Your server will initialize again (all previous data will be recovered).
@@ -72,7 +72,7 @@ Select the appropriate tab below to restore your data:
#. During :ref:`Initial Setup<initial-setup>`, select "Recover."
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.png
.. figure:: /_static/images/setup/screen0-recover.jpg
:width: 60%
#. Select "Restore From Backup."
@@ -85,7 +85,7 @@ Select the appropriate tab below to restore your data:
.. 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.
#. Enter the details for your Network Folder and click "Verify".
.. figure:: /_static/images/restore/recover2.png
:width: 60%
@@ -97,7 +97,7 @@ Select the appropriate tab below to restore your data:
#. 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!!
.. warning:: This will **PERMANENTLY 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%
@@ -114,7 +114,7 @@ Select the appropriate tab below to restore your data:
#. During :ref:`Initial Setup<initial-setup>`, select "Recover."
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.png
.. figure:: /_static/images/setup/screen0-recover.jpg
:width: 60%
#. Select "Transfer"

18
site/source/user-manual/backup-restore/index.rst → site/source/user-manual/backups/index.rst
View File

@@ -3,6 +3,7 @@
=======
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
@@ -12,7 +13,7 @@ In addition to the safe-keeping of a good master password, maintaining good back
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Create Backup
:title: Backup Create
:link: backup-create
:icon: scylla-icon scylla-icon--cloud
:class: large-5
@@ -21,7 +22,7 @@ In addition to the safe-keeping of a good master password, maintaining good back
Create an encrypted backup of your server data.
.. topic-box::
:title: Restore From Backup
:title: Backup Restore
:link: backup-restore
:icon: scylla-icon scylla-icon--live-test
:class: large-5
@@ -29,15 +30,6 @@ In addition to the safe-keeping of a good master password, maintaining good back
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>
@@ -48,7 +40,3 @@ In addition to the safe-keeping of a good master password, maintaining good back
backup-create
backup-restore
backup-physical
backup-synology
backup-truenas
backup-advanced

2
site/source/user-manual/index.rst
View File

@@ -11,7 +11,7 @@ User Manual
dashboard-overview
change-password
managing-services
backup-restore/index
backups/index
customize
updating
sessions