Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-04-02 05:23:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Feat/re arrange (#475)

Browse Source 
* move things around a lot

* move up a layer

* some edits

* rename some paths
This commit is contained in:
Matt Hill
2023-08-15 13:31:05 -06:00
committed by GitHub
parent 3f8d6b8c02
commit adcff208ac
76 changed files with 1223 additions and 1278 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
site/source/user-manual/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
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 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/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/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/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/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/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