Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-30 20:14:50 +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

163
site/source/guides/device-guides/dg-mac/backup-mac.rst Normal file
View File

@@ -0,0 +1,163 @@
.. _backup-mac:
==================
Mac Network Folder
==================
.. contents::
:depth: 2
:local:
Setup a Network Folder
----------------------
Please select what version of MacOS you are using from the two tabs below:
.. tabs::
.. group-tab:: Ventura
#. Identify or create a folder you would like to use to store your Start9 server's backups.
.. tip:: You can select an external drive or folder within an external drive connected to your Mac if you'd like.
#. Go to **System Settings**:
.. figure:: /_static/images/tor/systemSettings.png
:width: 40%
:alt: System settings
#. Click on **General** then **Sharing**:
.. figure:: /_static/images/cifs/ventura-general-sharing.png
:width: 40%
:alt: general-sharing
#. Click the toggle to enable file sharing and then click info icon:
.. figure:: /_static/images/cifs/ventura-enable-file-sharing.png
:width: 40%
:alt: enable-cifs
#. Click on the **"+"** icon and select the folder you would like to make backups to:
.. figure:: /_static/images/cifs/ventura-click-plus.png
:width: 40%
:alt: click-plus
#. Once added, click **Options**:
.. figure:: /_static/images/cifs/ventura-folder-added.png
:width: 40%
:alt: ventura-folder-added
#. Enable SMB sharing for the user you want to use and then click **Done**:
.. figure:: /_static/images/cifs/ventura-smb.png
:width: 40%
:alt: ventura-smb
#. Click **Done** to close this window. You can now move on to connecting your server.
.. tip:: You can find hostname at the bottom of sharing window. You will need this in the next step.
.. tip:: You can find hostname at the bottom of sharing window.
.. group-tab:: Pre-Ventura
#. Identify or create a folder you would like to use to store your Start9 server's backups.
.. tip:: You can select an external drive or folder within an external drive connected to your Mac if you'd like.
#. Go to **System Preferences** and click **Sharing**:
.. figure:: /_static/images/cifs/cifs-mac0.png
:width: 40%
:alt: sharing
#. Click **File Sharing**:
.. figure:: /_static/images/cifs/cifs-mac1.png
:width: 40%
:alt: file-sharing
#. Click the **"+"** icon under **Shared Folders** and add the folder you would like to back up to:
.. figure:: /_static/images/cifs/cifs-mac2.png
:width: 40%
:alt: click-plus
#. After selecting your folder, click **Options**:
.. figure:: /_static/images/cifs/cifs-mac3.png
:width: 40%
:alt: options
#. Enable **Share files and folders using SMB** and turn it on for the user you would like to use to authenticate and then click **Done**:
.. figure:: /_static/images/cifs/cifs-mac4.png
:width: 40%
:alt: SMB
#. Make a note of your computer's **Hostname** which can be found here:
.. figure:: /_static/images/cifs/cifs-mac-hostname.png
:width: 40%
:alt: hostname
#. You will also need the name of the "Shared Folder" you chose or created, as well as your Mac's username and password.
Connect Your Server
-------------------
#. Go to the **System** tab and click **Create Backup**:
.. figure:: /_static/images/config/backup.png
:width: 60%
:alt: system-create-backup
#. Click **Open New**:
.. figure:: /_static/images/config/backup0.png
:width: 60%
:alt: open-new
#. You will now see the following:
.. figure:: /_static/images/cifs/cifs-blank.png
:width: 50%
:alt: cifs-blank
Enter the credentials as follows:
* **Hostname** - This is the name of your computer.
.. tip:: Sometimes it can be unclear what your Mac's hostname is. Check the tip in Step 8 of the section above to find it. On some versions of Mac, you may need to open up Terminal and type `hostname` as below:
.. figure:: /_static/images/cifs/hostname-terminal-mac.png
:width: 35%
:alt: hostname-terminal-mac
* **Path** - This is the *name of the shared folder* you are using and **not** the full directory path.
.. tip:: If you copied the share name from the Mac computer and it contained a space, macOS will have replaced the space with the string "%20". Please re-replace `%20` with a space in this `Path` field.
* **Username** - This is the user on the remote machine that you used to create the shared directory.
* **Password** - This is the password to the above user.
.. figure:: /_static/images/cifs/cifs-mac5.png
:width: 60%
.. note:: If you are on MacOS Catalina (version 10.15.7), and the backup fails, please `see this Apple support thread <https://discussions.apple.com/thread/253970425>`_. If the provided solution still doesn't work, SMB file sharing probably will not work for this old Mac. Consider backing up to a USB thumb drive instead.
.. note:: If you recently updated to MacOS Ventura (version 13.2), and you cannot get the share to connect:
#. Turn off file sharing switch in **General > Sharing**
#. Restart macOS
#. Turn on file sharing switch in **General > Sharing**
#. Click **Connect**.
That's it! You can now :ref:`create encrypted, private backups<backup-create>` of all your Start9 server's data to your Mac.

81
site/source/guides/device-guides/dg-mac/ff-mac.rst Normal file
View File

@@ -0,0 +1,81 @@
.. _ff-mac:
==========================
Configuring Firefox on Mac
==========================
Here we will add your Start9 server's Root CA (Certificate Authority) to your system's certificate trust store to ensure that applications can verify connections to your services.
LAN Config
----------
#. 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
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-mac>`. 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
#. Now go to the right-hand hamburger menu and select ``Settings``:
.. 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
#. Check the option labeled ``Use System Proxy Settings``
#. Check the box labeled ``Proxy DNS when using SOCKS v5``:
.. figure:: /_static/images/tor/firefox_proxy.png
:width: 60%
:alt: Firefox proxy settings screenshot
#. Click ``OK`` and then restart Firefox for the changes to take effect.
#. You're all set! You should now be able to navigate to ``.onion`` URLs in Firefox. You can test this by going to Start9's ``.onion`` homepage, `here <http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion/>`_.
If you still encounter issues, `contact support <https://start9.com/contact>`_.

69
site/source/guides/device-guides/dg-mac/index.rst Normal file
View File

@@ -0,0 +1,69 @@
.. _dg-mac:
===
Mac
===
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-mac
: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-mac
:icon: scylla-icon scylla-icon--cloud
:class: large-4
:anchor: Setup
Configure a Network Folder on your Mac (or attached external drive) to receive StartOS backups.
.. topic-box::
:title: Connect to Tor Network
:icon: scylla-icon scylla-icon--networking
:link: tor-mac
:class: large-4
:anchor: Run Tor
Run Tor natively (in the background) on your Mac. This will enable apps to communicate with your Start9 server via the Tor Network, remotely.
.. topic-box::
:title: Configure Firefox
:link: ff-mac
:icon: scylla-icon scylla-icon--integrations
:class: large-4
:anchor: Config
Configure Firefox for an optimal experience with your server.
.. topic-box::
:title: Screensharing
:link: screenshare-mac
:icon: scylla-icon scylla-icon--workshop
:class: large-4
:anchor: Share Screen
Guide to allow screensharing with a Start9 Support Tech.
.. toctree::
:maxdepth: 4
:hidden:
lan-mac
backup-mac
tor-mac
ff-mac
screenshare-mac

59
site/source/guides/device-guides/dg-mac/lan-mac.rst Normal file
View File

@@ -0,0 +1,59 @@
.. _lan-mac:
================================
Trusting Your Start9 CA on macOS
================================
Complete this guide to download your Start9 server's Root Certificate Authority (CA), and trust it on your client device (Mac). 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.
#. In your Start9 server's UI, navigate to **System** -> **LAN**
.. figure:: /_static/images/ssl/macos/trust-cert-macos-1-system-lan.png
:width: 60%
:alt: Navigate to System > LAN
#. Click **Download Certificate** and your browser will either automatically save the certificate to your Downloads folder or ask you where to save it:
.. figure:: /_static/images/ssl/macos/trust-cert-macos-2-download_cert.png
:width: 60%
:alt: Download Certificate
#. Among the browser's downloads, right click your certificate file and select *Show in Folder*:
.. figure:: /_static/images/ssl/macos/trust-cert-macos-3-show_in_folder.png
:width: 60%
:alt: Show certificate file in Downloads folder
#. Finder will open. Locate your unique `adjective-noun Local CA.crt` file in your *Downloads* folder and double click it to open it in the Keychain Access program. You will be prompted for your macOS username and password, or thumbprint. Then select *Modify Keychain*:
.. figure:: /_static/images/ssl/macos/trust-cert-macos-4-modify_keychain.png
:width: 60%
#. Your server's CA certificate will be displayed among the imported certificates in Keychain Access. Right-click on the imported CA cert and select *Get Info*:
.. figure:: /_static/images/ssl/macos/trust-cert-macos-5-cert-get_info.png
:width: 60%
:alt: Keychain Access - Get Info of CA Certificate
#. The details of your CA certificate will be displayed in a new dialog window. Expand the **Trust** heading, then select "**Always Trust**" on **Secure Sockets Layer (SSL)** and **X.509 Basic Policy**.
.. figure:: /_static/images/ssl/macos/trust-cert-macos-6-ssl_tls-always_trust.png
:width: 60%
:alt: Trust CA Certificate
Click the red (x) button at the top left of the Local Root CA dialog window.
#. You will then be prompted again for your username and password, or thumbprint. Enter those and click **Update Settings**:
.. figure:: /_static/images/ssl/macos/trust-cert-macos-7-password-update_settings.png
:width: 60%
:alt: Authenticate to change the settings
#. You will see your server's CA certificate as trusted now, signified by a blue (+) sign and the CA cert information will now say "This certificate is marked as trusted for all users" in Keychain Access:
.. figure:: /_static/images/ssl/macos/trust-cert-macos-8-cert_trusted.png
:width: 60%
:alt: Keychain submenu
.. tip:: If the keychain console did not show the certificate as trusted, press "Command + spacebar" and type “Keychain Access”, and hit enter to re-open it.
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.

65
site/source/guides/device-guides/dg-mac/screenshare-mac.rst Normal file
View File

@@ -0,0 +1,65 @@
.. _screenshare-mac:
=============
Screensharing
=============
.. warning:: BE CERTAIN you are communicating with an official Start9 team member. Do not be fooled by impostors. If you are unsure, please `contact us <https://start9.com/contact>`_.
You may run into an issue and want to have a support call where we ask you to share your screen with us. While we understand if you'd rather not do this, it can make troubleshooting issues a lot easier. We will direct you on how you can share your screen. If it doesn't work, please see the following instructions:
.. tabs::
.. group-tab:: Pre-Ventura:
#. Head to System Preferences:
.. figure:: /_static/images/mac-stuff/system-prefs.png
:width: 20%
#. Click Security & Privacy:
.. figure:: /_static/images/mac-stuff/priv-security.png
:width: 20%
#. Click the lock to make changes and select "Privacy":
.. figure:: /_static/images/mac-stuff/click-lock.png
:width: 20%
#. Click "Screen Recording" and click the + icon:
.. figure:: /_static/images/mac-stuff/screen-rec-plus.png
:width: 20%
#. Find your browser within the applications folder and click "Open":
.. figure:: /_static/images/mac-stuff/add-browser-screen-rec.png
:width: 20%
#. Restart your browser and you should now be able to share your screen by clicking on this button within the Jitsi call:
.. figure:: /_static/images/mac-stuff/jitsi-screenshare.png
:width: 20%
.. group-tab:: Ventura:
#. Head to System Settings and scroll down to "Privacy & Security":
.. figure:: /_static/images/mac-stuff/system-settings-priv-sec.png
:width: 20%
#. Scroll down and click "Screen Recording":
.. figure:: /_static/images/mac-stuff/screen-rec-vent.png
:width: 20%
#. You can then click the + icon and add your browser - you may need to restart your browser after this:
.. figure:: /_static/images/mac-stuff/screen-rec-plus-vent.png
:width: 20%
#. You should now be able to share your screen by clicking on this button within the Jitsi call:
.. figure:: /_static/images/mac-stuff/jitsi-screenshare.png
:width: 20%

179
site/source/guides/device-guides/dg-mac/tor-mac.rst Normal file
View File

@@ -0,0 +1,179 @@
.. _tor-mac:
==================
Running Tor on Mac
==================
Install Homebrew
----------------
#. If you do not have Homebrew installed, follow the installation instructions `here <https://brew.sh/>`_. TLDR: Open the Terminal and paste the following line:
.. code-block:: bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
#. You will be prompted for your system password before installation; proceed with entering your password. You may be asked more than once.
.. figure:: /_static/images/tor/install_homebrew.png
:width: 80%
:alt: Homebrew installation
#. You will be notified which directories Homebrew is going to create, hit :code:`RETURN`:
.. figure:: /_static/images/tor/install_homebrew1.png
:width: 80%
:alt: Homebrew installation
Homebrew creates the directories and downloads any other files it needs e.g. “Command Line Tool for Xcode” and “Homebrew”.
Wait a few minutes while it downloads and installs what it needs.
.. note:: Once installation is complete you will need to add "brew" to your path. There will be instructions on how to do this with the specific commands you need to enter if you scroll up a little in your terminal. Look for "Add homebrew to your path". Enter the commands and then type **brew --version** to ensure that brew is working. If you see something like **"Homebrew 3.6.18"** then it is installed. If you see **"zsh: command not found: brew"** then it either hasn't installed correctly, has not been added to your path yet or you simply need to open a new terminal. (If you do try restarting terminal, make a note of the commands suggested in case you need them again).
.. warning:: Surprisingly, Homebrew uses Google Analytics to collect anonymous usage data. You can deselect the option to share usage data by `opting out <https://docs.brew.sh/Analytics#opting-out>`_.
Install Tor
-----------
.. caution:: If you have the Tor Browser open, close it and quit the application.
.. note:: If you are on a very old version of macOS, such as High Sierra (10.13) or below, first execute this command in a Terminal window:
.. code-block::
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile
Then close the Terminal.
#. Open a new Terminal and install Tor using the following command:
.. code-block:: bash
brew install tor
#. Then run Tor with:
.. code-block:: bash
brew services start tor
This will start Tor and ensure that it is always running, even after a restart. See the `Tor Project docs <https://2019.www.torproject.org/docs/tor-doc-osx.html.en>`_ for more details.
Enable Tor System-wide
----------------------
.. tabs::
.. group-tab:: Ventura
#. Enable proxy autoconfig file (This will download the Start9 standard proxy config file. You can use your own if you prefer):
.. code-block:: bash
sudo curl https://start9.com/assets/proxy.pac --output /Library/WebServer/Documents/proxy.pac
#. Now enable apache service:
.. code-block:: bash
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
#. Go to System Settings:
.. figure:: /_static/images/tor/systemSettings.png
:width: 40%
:alt: System Preferences
#. Click on *Network* and then select the interface on which you wish to enable Tor system-wide (both Ethernet and WiFi advised - do one then the other):
.. figure:: /_static/images/tor/ventura-settings.png
:width: 80%
:alt: Select Network
#. Click *Details*:
.. figure:: /_static/images/tor/ventura-network-advanced.png
:width: 80%
:alt: Click Advanced
#. Click "Proxies," then select "Automatic Proxy Configuration," add this URL: ``http://localhost/proxy.pac``, then click "OK":
.. figure:: /_static/images/tor/ventura-proxies-corrected.png
:width: 80%
:alt: Select Proxys
Done! You have now enabled system-wide Tor potential.
We advise going back to step 4 and repeating this for Wifi/Ethernet depending on which interface you haven't done yet.
If you ever need to view the status of the tor service, enter the following into a Terminal:
.. code-block:: bash
cat /usr/local/var/log/tor.log || sudo cat /opt/homebrew/var/log/tor.log
If you'd like to setup Firefox to use Tor you can follow :ref:`this guide<ff-mac>`.
.. group-tab:: Pre-Ventura
#. Enable proxy autoconfig file (This will download the Start9 standard proxy config file. You can use your own if you prefer):
.. code-block:: bash
sudo curl https://start9.com/assets/proxy.pac --output /Library/WebServer/Documents/proxy.pac
#. Now enable apache service:
.. code-block:: bash
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
#. Go to System Preferences:
.. figure:: /_static/images/tor/systemprefs.png
:width: 40%
:alt: System Preferences
#. Click on Network:
.. figure:: /_static/images/tor/network.png
:width: 80%
:alt: Select Network
#. In this example, we'll select WiFi on the left panel. If you're using Ethernet, click that instead. Next click "Advanced" (We suggest returning to this step in order to do both Ethernet AND WiFi):
.. figure:: /_static/images/tor/wifi_click_advanced.png
:width: 80%
:alt: Click Advanced
#. Select "Proxies":
.. figure:: /_static/images/tor/proxys.png
:width: 80%
:alt: Select Proxys
#. Select "Automatic Proxy Configuration", add this URL: **http://localhost/proxy.pac** then click "OK"
.. figure:: /_static/images/tor/entertorproxyURL-pre-ventura.png
:width: 80%
:alt: Select Automatic proxy config and enter URL
#. Finally, click "Apply"
.. figure:: /_static/images/tor/applyproxy.png
:width: 80%
:alt: Apply proxy
Done! You have now enabled system-wide Tor potential.
We suggest heading back to step 5 and enabling Tor system-wide on Ethernet/WiFi now - whichever you did not do already.
If you ever need to view the status of the tor service, enter the following into a Terminal:
.. code-block:: bash
cat /usr/local/var/log/tor.log || sudo cat /opt/homebrew/var/log/tor.log
If you'd like to setup Firefox to use Tor you can follow :ref:`this guide<ff-mac>`.