Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-31 04:23:41 +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

187
site/source/guides/device-guides/dg-linux/backup-linux.rst Normal file
View File

@@ -0,0 +1,187 @@
.. _backup-linux:
====================
Linux Network Folder
====================
.. contents::
:depth: 2
:local:
Setup Network Folder
--------------------
.. note:: This guide is for Ubuntu only. For Linux Mint, select "Mint", or for different distros such as Arch, Debian, Pop-OS, PureOS, etc, select "Other Linux" below.
.. tabs::
.. group-tab:: Ubuntu
Check out the video below, and follow along with the steps in this guide to setup a Network Folder on your Linux machine, such that you may create encrypted, private backups of all your StartOS data.
.. youtube:: LLIMC5P3NdY
:width: 100%
.. raw:: html
<br/><br/>
#. Install Samba if you have not already:
.. code-block::
sudo apt install samba && sudo systemctl enable smbd
#. Add your user to samba, replacing ``$USER`` with your Linux username.
.. code-block:: bash
sudo smbpasswd -a $USER
First you will be prompted for your linux password, then you will be asked to create a new SMB password for the user with permission to write to your new backup share. Keep it somewhere safe, such as Vaultwarden.
#. Right-click the folder that you want to backup to (or create a new one) and click "Properties"
.. figure:: /_static/images/cifs/cifs-lin0.png
:width: 60%
#. Select the "Local Network Share" tab
.. figure:: /_static/images/cifs/cifs-lin1.png
:width: 60%
#. Click "Share this folder"
.. figure:: /_static/images/cifs/cifs-lin2.png
:width: 60%
- You may rename the "Share", if you prefer - **remember this name**, you will need it later in the StartOS dashboard
- (Optional) Create a description in the "Comment" section
#. In case your installation of Ubuntu is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
.. code-block:: bash
sudo ufw allow Samba
.. group-tab:: Mint
#. Install Samba if you have not already:
.. code-block::
sudo apt install samba && sudo systemctl enable smbd
#. Add your user to samba, replacing ``$USER`` with your Linux username.
.. code-block:: bash
sudo usermod -a -G sambashare $USER
sudo smbpasswd -a $USER
First you will be prompted for your linux password, then you will be asked to create a new SMB password for the user with permission to write to your new backup share. Keep it somewhere safe, such as Vaultwarden.
#. Right-click the folder that you want to backup to (or create a new one, eg. ``start9-backup``) and click "Sharing Options"
.. figure:: /_static/images/cifs/cifs-mint0.png
:width: 60%
#. Enter a Share name consisting of 12 or fewer characters and click "Create Share"
.. figure:: /_static/images/cifs/cifs-mint1.png
:width: 60%
- You may rename the "Share", if you prefer - **remember this name**, you will need it later in the StartOS dashboard. In this example, we call it ``backup-share``
- (Optional) Create a description in the "Comment" section
#. In case your installation of Mint is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
.. code-block:: bash
sudo ufw allow Samba
.. group-tab:: Other Linux
1. Install Samba if it is not already installed.
* ``sudo pacman -S samba`` For Arch
* ``sudo apt install samba`` For Debian-based distros (Pop-OS, PureOS, etc)
* ``sudo yum install samba`` For CentOS/Redhat
* ``sudo dnf install samba`` For Fedora
2. Create a directory to share or choose an existing one and make note of its location (path). For this example, we will call the share ``backup-share`` and its corresponding shared directory will be located at ``/home/$USER/start9-backup``. Replace ``$USER`` with your Linux username below.
.. code-block:: bash
mkdir -p /home/$USER/start9-backup
.. note:: If you are on Fedora 38+, you need to do an extra step to allow the Samba share in SELinux:
.. code-block:: bash
sudo semanage fcontext --add --type "samba_share_t" "/home/$USER/start9-backup(/.*)?"
sudo restorecon -R /home/$USER/start9-backup
3. Configure Samba by adding the following to the end of the ``/etc/samba/smb.conf`` file:
.. code-block::
[backup-share]
path = "/home/$USER/start9-backup"
create mask = 0600
directory mask = 0700
read only = no
guest ok = no
Where:
- ``[backup-share]`` is the *Share Name* inside brakets, and can be called anything you'd like. We used ``backup-share`` in this example.
- ``path`` should be the path to the directory you created earlier
Copy the remainder of the entry exactly as it is
4. Open a terminal and enter the following command, replacing ``$USER`` with your Linux username:
.. code-block:: bash
sudo smbpasswd -a $USER
This creates a password for the Local Network Share. Keep it somewhere safe, such as Vaultwarden.
5. In case your installation of Linux (Pop-OS users take special note!) is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
.. code-block:: bash
sudo ufw allow Samba
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 machine that your shared folder is located on
* Path - This is the "Share Name" (name of the share in your samba config) and **not** the full directory path. In this guide we use ``backup-share``.
* Username - This is your Linux username on the remote machine that you used to create the shared directory
* Password - This is the password you set above using ``smbpasswd``
.. 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 StartOS data to your Linux machine or external drive!!

129
site/source/guides/device-guides/dg-linux/ff-linux.rst Normal file
View File

@@ -0,0 +1,129 @@
.. _ff-linux:
============================
Configuring Firefox on Linux
============================
Mozilla provides some of the most flexible, secure, and freedom-principled applications for using the web. We highly recommend completing all configuration below.
LAN Config
----------
This guide applies to Firefox, Firefox ESR, Librewolf, and Thunderbird. Mozilla apps need to be configured to use the certificate store of your device. To find out why Mozilla does this differently, you can read their `blog post <https://blog.mozilla.org/security/2019/02/14/why-does-mozilla-maintain-our-own-root-certificate-store/>`_ on the topic (TLDR: for security purposes).
#. Open Firefox and enter ``about:config`` in the URL bar. Accept any warnings that may appear about changing advanced configuration preferences.
#. Search for *security.enterprise_roots.enabled* and double click on *false* so that it turns to *true*:
.. figure:: /_static/images/ssl/browser/enterprise_roots_enabled_true.png
:width: 80%
:alt: Firefox security settings
.. tabs::
.. group-tab:: Debian/Ubuntu
For each Mozilla-based application (Firefox, Firefox ESR, LibreWolf, Thunderbird, etc) you plan on using, you will need to complete the following guide. This is in order for them to trust your Start9 server's CA certificate directly from your Linux distribution's certificate trust store.
#. Select the hamgurger menu, then *Settings*, then search for "*security devices*", then select "*Security Devices...*"
.. figure:: /_static/images/ssl/linux/cert-trust-linux-firefox-p11kit-1.png
:width: 60%
:alt: Mozilla application p11kit trust #1
#. When the Device Manager dialog window opens, select "*Load*"
.. figure:: /_static/images/ssl/linux/cert-trust-linux-firefox-p11kit-2.png
:width: 60%
:alt: Mozilla application p11kit trust #2
#. Give the Module Name a title such as "*System CA Trust Module*" and for the Module filename, paste in ``/usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-trust.so`` and hit *OK*:
.. figure:: /_static/images/ssl/linux/cert-trust-linux-firefox-p11kit-3.png
:width: 60%
:alt: Mozilla application p11kit trust #3
#. Verify that the new module shows up on the left hand side and select *OK* at the bottom right:
.. figure:: /_static/images/ssl/linux/cert-trust-linux-firefox-p11kit-4.png
:width: 60%
:alt: Mozilla application p11kit trust #4
.. group-tab:: Arch/Garuda
.. group-tab:: CentOS/Fedora
Now restart Firefox (or other Mozilla application), and log in to your server using ``https``. You should now see this symbol indicating a secure connection:
.. figure:: /_static/images/ssl/browser/firefox-https-good.png
:width: 80%
:alt: Firefox security settings
.. tip:: If you see an exclamation point inside a triangle by the lock, you have made a security exception in the browser. You will need to remove it by clicking the lock and then "Connection not secure":
.. figure:: /_static/images/ssl/browser/cert-trust-exception-remove-1.png
:width: 80%
:alt: Firefox - Remove security exception (Part 1)
Then click "Remove Exception":
.. figure:: /_static/images/ssl/browser/cert-trust-exception-remove-2.png
:width: 80%
:alt: Firefox - Remove security exception (Part 2)
You should now see that the website is trusted as in the final step show above.
Tor Config
----------
.. caution::
This guide assumes you have completed :ref:`setting up Tor<tor-linux>`. 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.allowlist_onions`` and set the value to ``true``:
.. figure:: /_static/images/tor/firefox_allowlist.png
:width: 60%
:alt: Firefox whitelist onions screenshot
#. Next, search for ``network.websocket.allowInsecureFromHTTPS`` and set the value to ``true``:
.. figure:: /_static/images/tor/firefox_insecure_websockets.png
:width: 60%
:alt: Firefox allow insecure websockets over https
#. 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 from a terminal, by using:
.. code-block::
sudo wget -P /etc/tor https://start9.com/assets/proxy.pac
#. Now, back in your Firefox web browser, select ``Settings`` from the right-hand hamburger menu:
.. figure:: /_static/images/tor/os_ff_settings.png
:width: 30%
: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:///etc/tor/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 service :ref:`WebUIs <web-ui>`, and use client integrations such as :ref:`Vaultwarden<vaultwarden-service>` apps and extensions. You can test this by going to Start9's ``.onion`` homepage, `here <http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion/>`_.
If you still encounter issues, `contact support <https://start9.com/contact>`_.

59
site/source/guides/device-guides/dg-linux/index.rst Normal file
View File

@@ -0,0 +1,59 @@
.. _dg-linux:
=====
Linux
=====
To optimize your device for use with your Start9 server, it is recommended to complete all of the following guides. At minimum, you will want to set up your Root CA in the first guide.
.. tip:: 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 are available even with no Internet access!
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Trust Root CA
:link: lan-linux
:icon: scylla-icon scylla-icon--partners
:class: large-4
:anchor: Connect
Trust your Start9 server's Root Certificate Authority in order to create encrypted connections.
.. topic-box::
:title: Backup Configuration
:link: backup-linux
:icon: scylla-icon scylla-icon--cloud
:class: large-4
:anchor: Setup
Configure a Network Folder on your Linux machine (or attached external drive) to receive StartOS backups.
.. topic-box::
:title: Connect to Tor Network
:icon: scylla-icon scylla-icon--networking
:link: tor-linux
:class: large-4
:anchor: Run Tor
Run Tor natively (in the background) on your Linux device. This will enable apps to communicate with your Start9 server via the Tor Network, remotely.
.. topic-box::
:title: Configure Firefox
:link: ff-linux
:icon: scylla-icon scylla-icon--integrations
:class: large-4
:anchor: Config
Configure Firefox for an optimal experience with your server.
.. toctree::
:maxdepth: 4
:hidden:
lan-linux
backup-linux
tor-linux
ff-linux

83
site/source/guides/device-guides/dg-linux/lan-linux.rst Normal file
View File

@@ -0,0 +1,83 @@
.. _lan-linux:
================================
Trusting Your Start9 CA on Linux
================================
Complete this guide to download your Start9 server's Root Certificate Authority (CA), and trust it on your client device (Windows). This allows you to use encrypted ``https`` connections to your ``.local`` (LAN) and ``.onion`` (tor) server addresses, access services on LAN, and enhances performance on tor. The self-signed certificate was created by your server when you perfomed the initial setup, and applies to your server's main UI connection, as well as all service connections.
.. caution:: If you cannot connect following this guide, you may be using an application (such as Firefox) that is installed in a jailed environment, such as an appimage, flatpak, or snap. Please try an alternate install method if so.
Download Root CA
----------------
First, download your Start9 server's Root CA, if you have not already.
- Navigate to *System > LAN*, then click "Download Certificate".
.. figure:: /_static/images/ssl/lan_setup.png
:width: 40%
:alt: LAN setup menu item
Alternatively, you can download to another machine, then transfer the file to your device.
Trust Root CA
-------------
.. tabs::
.. group-tab:: Debian/Ubuntu
These instructions will work for most Debian-based Linux distributions, such as Debian, Linux Mint, PopOS, Ubuntu, etc.
#. Perform the following commands in the Terminal:
.. code-block:: bash
sudo apt update
sudo apt install -y ca-certificates p11-kit
#. Move into the folder where you downloaded your Start9 server's Root CA (usually ``~/Downloads``), and run the following commands to add your Start9 server's CA certificate to the OS trust store:
.. caution:: BE CERTAIN to replace ``adjective-noun`` with your server's unique hostname in the 3rd and 4th commands below!
.. code-block:: bash
cd ~/Downloads
sudo mkdir -p /usr/share/ca-certificates/start9
sudo cp "adjective-noun.local.crt" /usr/share/ca-certificates/start9/
sudo bash -c "echo 'start9/adjective-noun.local.crt' >> /etc/ca-certificates.conf"
sudo update-ca-certificates
In the output it should say ``1 added`` if it was successful. For most applications, you will now be able to securely connect via ``https``. We highly recommend continuing on to our :ref:`Configuring Firefox <ff-linux>` guide.
.. group-tab:: Arch/Garuda
From the folder you have downloaded your Start9 server's Root CA, run the following commands (if you have changed the certificate's filename, be sure to change it here):
.. code-block:: bash
sudo pacman -S ca-certificates
sudo cp "<custom-address>.crt" /etc/ca-certificates/trust-source/anchors/
sudo update-ca-trust
Despite no output from the last command, you can test your app right away.
.. group-tab:: CentOS/Fedora
First, ensure mDNS resolution is turned on so you can reach your server:
Ensure ``MulticastDNS=Yes`` is set in /etc/systemd/resolved.conf and then restart systemd-resolved:
.. code-block:: bash
sudo systemctl restart systemd-resolved
Trust your server's CA certificate:
From the folder you have downloaded your Start9 server's Root CA, run the following commands (if you have changed the certificate's filename, be sure to change it here):
.. code-block:: bash
sudo yum install ca-certificates
sudo cp "<custom-address>.crt" /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
You're now ready to browse your service UIs with encryption, either via the browser, or with native client apps. For Mozilla apps, such as Firefox, you will need to follow the :ref:`Firefox Config <lan-ff>` guide, which we highly recommend.

95
site/source/guides/device-guides/dg-linux/tor-linux.rst Normal file
View File

@@ -0,0 +1,95 @@
.. _tor-linux:
====================
Running Tor on Linux
====================
.. tabs::
.. group-tab:: Debian / Ubuntu
For Debian and Debian-based systems, such as Mint, PopOS etc.
.. note:: The following install is for the LTS (Long Term Support) version of Tor from Debian. If you would like the latest stable release, The Tor Project maintain their own Debian repository. The instructions to connect to this can be found `here <https://support.torproject.org/apt/tor-deb-repo/>`_.
Install the Tor proxy service to your system. To do so, open your terminal and run the following command:
.. code-block:: bash
sudo apt update && sudo apt install tor
.. tip:: You can check that Tor is running with:
.. code-block:: bash
systemctl status tor
In the rare event that Tor is having connectivity issues, you can reset your connection with:
.. code-block:: bash
sudo systemctl restart tor
.. group-tab:: Arch / Garuda / Manjaro
Simply install Tor with:
.. code-block:: bash
sudo pacman -S tor
.. tip:: You can check that Tor is running with:
.. code-block:: bash
systemctl status tor
In the rare event that Tor is having connectivity issues, you can reset your connection with:
.. code-block:: bash
sudo systemctl restart tor
.. group-tab:: CentOS / Fedora / RHEL
#. Configure the Tor Package repository. Add the following to ``/etc/yum.repos.d/tor.repo``:
- CentOS / RHEL:
.. code-block:: bash
[Tor]
name=Tor for Enterprise Linux $releasever - $basearch
baseurl=https://rpm.torproject.org/centos/$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://rpm.torproject.org/centos/public_gpg.key
cost=100
- Fedora:
.. tip:: Latest Fedora versions have Tor package available for installation:
.. code-block:: bash
[Tor]
name=Tor for Fedora $releasever - $basearch
baseurl=https://rpm.torproject.org/fedora/$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://rpm.torproject.org/fedora/public_gpg.key
cost=100
#. Install the Tor package:
.. code-block:: bash
sudo dnf install tor
#. Then enable tor service:
.. code-block:: bash
sudo systemctl enable --now tor