Skip to content

Commit

Permalink
Merge pull request #2336 from truenas/PD-713-SCALE-23.10.1-docs
Browse files Browse the repository at this point in the history 
Pd 713 SCALE 23.10.1 docs
  • Loading branch information
@ericbsd
ericbsd authored Dec 19, 2023
2 parents f278901 + fe10029 commit f9f6684
Show file tree
Hide file tree
Showing 39 changed files with 1,984 additions and 841 deletions.
17 changes: 6 additions & 11 deletions content/GettingStarted/23.10Upgrades.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,24 +22,19 @@ When available, update the system to 22.12.4 (Bluefin), resolve any migrations f
## Upgrading from the Web Interface

Log in to the SCALE web interface and go to **System Settings > Update**.
The screen shows which update train is active for the install.
The **Update Screen** displays the current active update train. For more information on other available trains, see [Release Schedules](https://www.truenas.com/docs/truenasupgrades/).

{{< truetable >}}
| Train Type | Name | Notes |
|------------|------|-------|
| Stable Release | TrueNAS-SCALE-Bluefin | |
| Prerelease | TrueNAS-SCALE-Cobia-BETA | Intended for early testing and feature previews. Do not use a prerelease train for production use. |
| Nightly | TrueNAS-SCALE-Cobia-Nightlies | Adventurous users with disposable hardware only. Requires nightly [.iso file](https://download.truenas.com/truenas-scale-cobia-nightly/) upgrade to switch to this train. |
{{< /truetable >}}
When a new maintenance version is available from the current train, TrueNAS SCALE stages available updates.
Click **Apply Pending Update** to install it.

When a new version is available, open the **Current Train** dropdown and select the desired release option.
TrueNAS begins checking for update files from the new train and stages any updates available from that location.
{{< include file="/_includes/UpgradeClearCache.md" >}}

Alternately, uploading a <file>.update</file> file and manually updating switches the system between train types.
Alternately, upload an <file>.update</file> file and perform a manual update.
{{< expand "Manual Update Process (Click to expand)" "v" >}}
{{< include file="/content/_includes/ManualUpdates.md" >}}
{{< /expand >}}

Uploading an <file>.update</file> file from another train and manually updating switches the system between train types.
Changing trains is a one-way operation!
Do not change to a prerelease or nightly release unless the system is intended to permanently remain on early versions and is not storing any critical data.

Expand Down
102 changes: 56 additions & 46 deletions content/GettingStarted/Install/InstallEnterpriseHASCALE.md
View file

Large diffs are not rendered by default.

67 changes: 39 additions & 28 deletions content/GettingStarted/Install/InstallingSCALE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,25 +26,27 @@ Enterprise customers with High Availability (HA) systems should not attempt to r
{{< /enterprise >}}

## ISO Verification

The iXsystems Security Team cryptographically signs TrueNAS <kbd>.iso</kbd> files so that users can verify the integrity of their downloaded file.
This section demonstrates how to verify an <kbd>.iso</kbd> file using the [Pretty Good Privacy (PGP)](https://tools.ietf.org/html/rfc4880) and [SHA256](https://tools.ietf.org/html/rfc6234) methods.

### Performing PGP ISO Verification

You need an OpenPGP encryption application for this method of ISO verification.
{{< expand "Click here for the verification process." "v" >}}
1. Obtain an OpenPGP encryption application to used.
There are many different free applications available, but the OpenPGP group provides a list of available software for different operating systems at https://www.openpgp.org/software/.

1. Obtain an OpenPGP encryption application to use.
There are many different free applications available, but the OpenPGP group provides a list of available software for different operating systems at https://www.openpgp.org/software/.
The examples in this section show verifying the TrueNAS <kbd>.iso</kbd> using [gnupg2](https://gnupg.org/software/index.html) in a command prompt, but [Gpg4win](https://www.gpg4win.org/) is also a good option for Windows users.

2. To verify the <kbd>.iso</kbd> source, go to https://www.truenas.com/download-tn-scale/, expand the **Security** option,
and click **PGP Signature** to download the Gnu Privacy Guard signature file. This file may be a (<kbd>.gpg</kbd>) or a (<kbd>.sig<kbd>) file.
2. To verify the <kbd>.iso</kbd> source, go to https://www.truenas.com/download-tn-scale/, expand the **Security** option,
and click **PGP Signature** to download the Gnu Privacy Guard signature file. This file may be a (<kbd>.gpg</kbd>) or a (<kbd>.sig<kbd>) file.
Open the [PGP Public key link](https://keyserver.ubuntu.com/pks/lookup?search=0xC8D62DEF767C1DB0DFF4E6EC358EAA9112CF7946&fingerprint=on&op=index) and note the address in your browser and **Search results for** string.

3. Use one of the OpenPGP encryption tools mentioned above to import the public key and verify the PGP signature.

Go to the <kbd>.iso</kbd> and the <kbd>.iso.gpg</kbd> or <kbd>.iso.sig</kbd> download location and import the public key using the keyserver address and search results string:

```
user@ubuntu /tmp> gpg --keyserver keys.gnupg.net --recv-keys 0xc8d62def767c1db0dff4e6ec358eaa9112cf7946
gpg: DBG: Using CREATE_BREAKAWAY_FROM_JOB flag
Expand All @@ -54,9 +56,9 @@ You need an OpenPGP encryption application for this method of ISO verification.
gpg: imported: 1
user@ubuntu /tmp>
```

Use `gpg --verify` to compare the <kbd>.iso</kbd> and the <kbd>.iso.gpg</kbd> or <kbd>.iso.sig</kbd> files:

```
user@ubuntu /tmp> gpg --verify TrueNAS-SCALE-21.04-ALPHA.1.iso
gpg: Signature made Thu May 27 10:49:02 2021 EDT using RSA key ID 12CF7946
Expand All @@ -66,14 +68,15 @@ You need an OpenPGP encryption application for this method of ISO verification.
Primary key fingerprint: C8D6 2DEF 767C 1DB0 DFF4 E6EC 358E AA91 12CF 7946
user@ubuntu /tmp>
```

This response means the signature is correct but still untrusted.

4. Go back to the browser page that has the **PGP Public key**.
This response means the signature is correct but still untrusted.

4. Go back to the browser page that has the **PGP Public key**.
Open and manually confirm that the key is issued for `IX SecTeam <[email protected]>` (iX Security Team) on October 15, 2019 and is signed by an iXsystems account.
{{< /expand >}}

### Using SHA256 Verification

SHA256 verification uses the checksum to validate/verify the file.
{{< expand "Click here for the verification process." "v" >}}
The command to verify the checksum varies by operating system:
Expand All @@ -89,13 +92,14 @@ Different checksum values indicate a corrupted installer file that you should no
{{< /expand >}}

## Installing SCALE

You can install SCALE on either physical hardware or a virtual machine.

{{< hint type=important >}}
Prior to starting the update process, confirm that the system storage has enough space to handle the update. The update stops if there is insufficient space for it to finish.
{{< /hint >}}

### Installing on Physical Hardware
### Installing on Physical Hardware

TrueNAS SCALE is very flexible and can run on any x86_64 compatible (Intel or AMD) processor.
SCALE requires at least 8GB of RAM (more is better) and a 20GB Boot Device.
Expand Down Expand Up @@ -143,9 +147,10 @@ Select the install device as the boot drive, exit, and reboot the system.
If the USB stick is not shown as a boot option, try a different USB slot.
Slots available for boot differs by hardware.

#### Using the TrueNAS Installer Console Setup
#### Using the TrueNAS Installer Console Setup

{{< hint type=important >}}
If you are doing a clean install from the SCALE <kbd>.iso</kbd> file as part of migrating from a different version of TrueNAS CORE or SCALE, or to recover from a serious issue that requires you to re-install SCALE from the <kbd>.iso</kbd>, have your network configuration information ready to use after the installation completes.
If you are doing a clean install from the SCALE <kbd>.iso</kbd> file as part of migrating from a different version of TrueNAS CORE or SCALE, or to recover from a serious issue that requires you to re-install SCALE from the <kbd>.iso</kbd>, have your network configuration information ready to use after the installation completes.
Also have your SCALE system configuration file and data backups handy so you can recover your system settings and import your data into the recovered SCALE clean-install system.
{{< /hint >}}
After the system boots into the installer, follow these steps.
Expand All @@ -156,26 +161,27 @@ After following the steps to install, reboot the system and remove the install m
{{< expand "Troubleshooting" "v">}}
If the system does not boot into TrueNAS SCALE, there are several things you can check to resolve the situation:

* Check the system BIOS and see if there is an option to change the **USB emulation** from **CD/DVD/floppy** to **hard drive**.
* Check the system BIOS and see if there is an option to change the **USB emulation** from **CD/DVD/floppy** to **hard drive**.
If it still does not boot, check to see if the card/drive is UDMA compliant.
* Check to see if the system BIOS supports **UEFI with BIOS emulation**, if not, see if it has an option to boot using **legacy BIOS mode**.

* If the system starts to boot but hangs with this repeated error message: `run_interrupt_driven_hooks: still waiting after 60 seconds for xpt_config`,
* If the system starts to boot but hangs with this repeated error message: `run_interrupt_driven_hooks: still waiting after 60 seconds for xpt_config`,
go into the system BIOS and look for an onboard device configuration for a `1394 Controller`. If present, disable that device and try booting again.
* If the burned image fails to boot and the image was burned using a Windows system, wipe the USB stick before trying a second burn using a utility such as [Active@ KillDisk](https://www.killdisk.com/eraser.html).
Otherwise, the second burn attempt fails as Windows does not understand the partition that was written from the image file.
* If the burned image fails to boot and the image was burned using a Windows system, wipe the USB stick before trying a second burn using a utility such as [Active@ KillDisk](https://www.killdisk.com/eraser.html).
Otherwise, the second burn attempt fails as Windows does not understand the partition written from the image file.
Be very careful to specify the correct USB stick when using a wipe utility!
{{< /expand >}}
{{< /expand >}}

### Installing on a Virtual Machine
### Installing on a Virtual Machine

Because TrueNAS SCALE is built and provided as an <kbd>.iso</kbd> file, it works on all virtual machine solutions (VMware, VirtualBox, Citrix Hypervisor, etc).
This section describes installing on a VM using [VMware Workstation Player](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html) on Windows.

#### Minimum Virtual Machine Settings

Regardless of virtualization application, use these minimum settings:

* RAM: at least 8192MB (8GB)
* DISKS: two virtual disks with at least 16GB, one for the operating system and boot environments and at least one additional virtual disk to use as data storage.
* NETWORK: Use NAT, bridged, or host-only depending on your host network configuration.
Expand All @@ -192,19 +198,20 @@ Enable **MAC spoofing** and **promiscuous mode** on the switch first, and then t

For most hypervisors, the procedure for creating a TrueNAS VM is the same.
{{< expand "Generic VM Install Instructions" "v" >}}

1. Create a new virtual machine as usual, taking note of the following:

* The virtual hardware has a bootable CD/DVD device pointed to the TrueNAS SCALE installer image (this is usually an <kbd>.iso</kbd>).

* The virtual network card configuration allows your network to reach it.
* The virtual network card configuration allows your network to reach it.
**bridged** mode is optimal as this treats the network card as one plugged into a simple switch on the existing network.

* Some products require you identify the OS you plan to install on the VM. The ideal option is **Debian 11 64 bit**.
* Some products require you identify the OS you plan to install on the VM. The ideal option is **Debian 11 64 bit**.
If this is not available, try options like **Debian 11**, **Debian 64 bit**, **64 bit OS**, or **Other**.

* For VMWare hypervisors, install in BIOS mode.

* Ensure the VM has sufficient memory and disk space. For TrueNAS set to at least **8 GB** RAM and **20 GB** disk space.
* Ensure the VM has sufficient memory and disk space. For TrueNAS set to at least **8 GB** RAM and **20 GB** disk space.
Not all hypervisors allocate enough memory by default.

2. Boot the VM and install TrueNAS as usual.
Expand All @@ -215,6 +222,7 @@ For most hypervisors, the procedure for creating a TrueNAS VM is the same.
{{< /expand >}}

#### Example VMWare Player 15.5 Installation

This example describes installing TrueNAS SCALE using VMWare Player 15.5.
{{< expand " Click here for more information." "v" >}}
Open VMware Player and click **Create a New Virtual Machine** to enter the New Virtual Machine Wizard.
Expand All @@ -231,12 +239,12 @@ Open VMware Player and click **Create a New Virtual Machine** to enter the New V

Specify the maximum disk size for the initial disk.
The default *20GB* is enough for TrueNAS.

Next, select **Store virtual disk as a single file**.

4. Review the virtual machine.

Review the virtual machine configuration before proceeding.
Review the virtual machine configuration before proceeding.
By default, VMware Player does not set enough RAM for the virtual machine.

Click **Customize Hardware...** > **Memory**.
Expand All @@ -246,9 +254,11 @@ Open VMware Player and click **Create a New Virtual Machine** to enter the New V
{{< /expand >}}

#### Adding Virtual Disks
After installing SCALE on a virtual machine (VM), add virtual disks to the VM. You need a minimum of two disks, 16 GB each.

After installing SCALE on a virtual machine (VM), add virtual disks to the VM. You need a minimum of two disks, 16 GB each.
One disk is for the boot environment the other for data storage.
{{< expand "Click Here for More Information" "v" >}}

1. After creating the virtual machine, select it from the virtual machine list and click **Edit virtual machine settings**.

2. Click **Add...** and select **Hard Disk**. Select **SCSI** as the virtual disk type.
Expand All @@ -260,11 +270,12 @@ One disk is for the boot environment the other for data storage.

5. Name and chose a location for the new virtual disk.

Repeat this process until enough disks are available for TrueNAS to create ideal storage pools. This depends on your specific TrueNAS use case.
See [Pool Creation]({{< relref "CreatePoolWizard.md" >}}) for descriptions of the various pool ("vdev") types and layouts.
Repeat this process until enough disks are available for TrueNAS to create ideal storage pools. This depends on your specific TrueNAS use case.
See [Pool Creation]({{< relref "CreatePoolWizard.md" >}}) for descriptions of the various pool ("vdev") types and layouts.
{{< /expand >}}

#### Using the TrueNAS Installer
#### Using the TrueNAS Installer

Just as with installing SCALE on physical hardware, you complete the install in the VM by booting into the TrueNAS installer.
{{< expand "Using the TrueNAS Installer in a Virtual Machine" "v" >}}
Select the virtual machine from the list and click **Play virtual machine**.
Expand Down
Loading

0 comments on commit f9f6684

Please sign in to comment.