TrueNASTrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Installing TrueNAS

After you download the .iso file, you can start installing TrueNAS!

This article describes verifying the .iso file and installing TrueNAS using that file, and selecting the type of installation as either on physical hardware or a virtual machine (VM).

TrueNAS Enterprise

TrueNAS Enterprise customers should receive their systems already installed and ready for UI configuration. If there are any issues with that require you to install or re-install TrueNAS, contact iXsystems Support for assistance.

Enterprise customers with High Availability (HA) systems should not attempt to re-install their systems on their own. The dual controller install process is complicated and the risk of causing serious network issues is high. Contact iXsystems Support for assistance!

Contacting Support

Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.

iXsystems Customer Support
Support Portalhttps://support.ixsystems.com
Emailsupport@ixsystems.com
Telephone and Other Resourceshttps://www.ixsystems.com/support/

ISO Verification

The iXsystems Security Team cryptographically signs TrueNAS .iso files so that users can verify the integrity of their downloaded file. This section demonstrates how to verify an .iso file using the Pretty Good Privacy (PGP) and SHA256 methods.

Performing PGP ISO Verification

You need an OpenPGP encryption application for this method of ISO verification.

Click here for the verification process.
  1. Obtain an OpenPGP encryption application to use. There are many 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 .iso using gnupg2 in a command prompt, but Gpg4win is also a good option for Windows users.

  2. To verify the .iso 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 can be a (.gpg) or a (.sig) file. Open the PGP Public key link 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 .iso and the .iso.gpg or .iso.sig 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
    gpg: key 358EAA9112CF7946: public key "IX SecTeam <security-officer@ixsystems.com>" imported
    gpg: DBG: Using CREATE_BREAKAWAY_FROM_JOB flag
    gpg: Total number processed: 1
    gpg:               imported: 1
    user@ubuntu /tmp>
    

    Use gpg --verify to compare the .iso and the .iso.gpg or .iso.sig 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
    gpg: Good signature from "IX SecTeam <security-officer@ixsystems.com>"
    gpg: WARNING: This key is not certified with a trusted signature!
    gpg:          There is no indication that the signature belongs to the owner.
    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. Open and manually confirm that the key is issued for IX SecTeam <security-officer@ixsystems.com> (iX Security Team) on October 15, 2019 and is signed by an iXsystems account.

Using SHA256 Verification

SHA256 verification uses the checksum to validate/verify the file.

Click here for the verification process.

The command to verify the checksum varies by operating system:

  • BSD: use command sha256 isofile
  • Linux: use command sha256sum isofile
  • Mac: use command shasum -a 256 isofile

Freeware or online checksum utilities are available for Windows users.

The value produced by running the command must match the value shown in the sha256.txt file. Different checksum values indicate a corrupted installer file that you should not use.

Installing TrueNAS

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

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 to complete.

Installing on Physical Hardware

TrueNAS is very flexible and can run on any x86_64 compatible (Intel or AMD) processor. TrueNAS requires at least 8GB of RAM (more is better) and a 20GB Boot Device.

Preparing the Install File

Physical hardware requires burning the TrueNAS installer to a device, typically a CD or removable USB device. This device is temporarily attached to the system to install TrueNAS to the system permanent boot device.

Writing the TrueNAS installer to a USB stick on Linux

To write the TrueNAS installer to a USB stick on Linux, plug the USB stick into the system and open a terminal.

Start by making sure the USB stick connection path is correct. There are many ways to do this in Linux, but a quick option is to enter the command lsblk -po +vendor,model and note the path to the USB stick. This shows in the NAME column of the lsblk output.

Next, use command dd to write the installer to the USB stick.

Be very careful when using dd, as choosing the wrong of= device path can result in irretrievable data loss!

Enter command dd status=progress if=path/to/.iso of=path/to/USB in the CLI.

If this results in a permission denied error, use command sudo dd with the same parameters and enter the administrator password.

Installing From the Device Media

Before you begin:

  • Locate the hotkey defined by the manufacturer of your motherboard to use in this process.
  • Disable SecureBoot if your system supports it so or set it to Other OS, so you can boot to the install media.

With the installer added to a device (CD or USB), you can now install TrueNAS onto the desired system using the TrueNAS installer.

Insert the install media and reboot or boot the system. At the motherboard splash screen, use the hotkey defined by your motherboard manufacturer to boot into the motherboard UEFI/BIOS.

Choose to boot in UEFI mode or legacy CSM/BIOS mode. When installing TrueNAS, make the matching choice for the installation. For Intel chipsets manufactured in 2020 or later, UEFI is likely the only option.

If your system supports SecureBoot, and you have not disabled it or set it to Other OS, do it now, so you can boot the install media.

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. For optimal performance, consider using NVMe S.M.A.R.T. tests to ensure the reliability of your storage devices before installation.

Using the TrueNAS Installer

If you are doing a clean install from the TrueNAS .iso file as part of migrating from a different TrueNAS version, or to recover from a serious issue that requires you to re-install TrueNAS from the .iso, have your network configuration information ready to use after the installation completes. Also have your TrueNAS system configuration file and data backups handy, so you can recover your system settings and import your data into the recovered TrueNAS clean-install system.

After the system boots into the installer, follow these steps.

TrueNAS Installer Instructions

  1. Select Install/Upgrade.

  2. Select the desired install drive.

    Select Yes to proceed with a clean installation of TrueNAS from the .iso. This erases the contents of the selected drive!

  3. Select option 1 Administrative user (truenas_admin) then OK to install TrueNAS and create the truenas_admin user account and password. TrueNAS has implemented an administrator login as a replacement for the root user login as a security hardening measure. The system retains root as a fallback, but it is no longer the default. The truenas_admin account has full control over TrueNAS and is used to log in to the web interface.

    Set a strong password and protect it.

    Next, enter a password for the new truenas_admin user.

  4. Select Yes at the Legacy Boot prompt to allow the system to boot via UEFI, or select No if your system hardware requires legacy BIOS boot. Press Enter to begin the installation.

  5. Select OK when the Installation Succeeded screen shows and press Enter to exit from the installer.

After following the steps to install, reboot the system and remove the install media.

Troubleshooting

If the system does not boot into TrueNAS, there are several things you can check to resolve the situation:

  • Check to see if the system BIOS has an option to change the USB emulation from CD/DVD/floppy to hard drive. If it still does not boot after making the change, 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 repeating 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 you burned the image using a Windows system, wipe the USB stick before trying a second burn using a utility such as Active@ KillDisk. 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!

Installing on a Virtual Machine

Because TrueNAS is built and provided as an .iso file, it works on all virtual machine solutions (Proxmox, VMware, VirtualBox, Citrix Hypervisor, etc). This section describes installing on a VM using VMware Workstation Player 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.

Networking Checks for VMWare

When installing TrueNAS in a VMWare VM, double-check the virtual switch and VMWare port group. A misconfigured virtual switch or VMWare port group can cause network connection errors for TrueNAS systems with additional applications installed inside the TrueNAS VM. Enable MAC spoofing and promiscuous mode on the switch first, and then the port group the VM is using.

If not using static IP addresses, configure your VM to use DHCP to assign IP addresses for seamless network connectivity.

Jail Networking

If you have installed TrueNAS in VMware, you need functional networking to create a jail.

For the jail to have functional networking, you have to change the VMware settings to allow Promiscuous, MAC address changes, and Forged Transmits.

SettingDescription
Promiscuous ModeWhen enabled at the virtual switch level, objects defined within all portgroups can receive all incoming traffic on the vSwitch.
MAC Address ChangesWhen set to Accept, ESXi accepts requests to change the effective MAC address to a different address than the initial MAC address.
Forged TransmitsWhen set to Accept, ESXi does not compare source and effective MAC addresses.

Installing on a Generic Virtual Machine

The procedure for creating a TrueNAS VM is the same for most hypervisors.

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

    • Point a bootable CD/DVD device in the virtual hardware to the TrueNAS installer image (this is usually an .iso).

    • Configure the virtual network card to allow 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.

    • Identify the OS you plan to install on the VM. This is required by some products. The ideal option is Debian 11 64 bit. If not available, try options like Debian 11, Debian 64 bit, 64 bit OS, or other.

    • Install in BIOS mode for VMWare hypervisors.

    • 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.

  3. After the installation completes, shut down the VM instead of rebooting, and disconnect the CD/DVD from the VM before rebooting the VM.

  4. After rebooting into TrueNAS, install VM tools if applicable for your VM, and if they exist for Debian 11, or ensure they loaded on boot.

Installing Using VMWare Player 15.5

This example describes installing TrueNAS using VMWare Player 15.5.

Installation Instructions

Open VMware Player and click Create a New Virtual Machine to enter the New Virtual Machine Wizard.

  1. Install the disk image file.

    Select the Installer disk image file (.iso) option, click Browse…, and upload the TrueNAS .iso downloaded earlier.

  2. Name the virtual machine.

    You can change the virtual machine name and location.

  3. Specify the disk capacity.

    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 configuration.

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

    Click Customize Hardware… > Memory. Drag the slider up to 8GB and click Ok.

  5. Power on the machine after creation if desired. Select Power on this virtual machine after creation.

Adding Virtual Disks

After installing TrueNAS 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.

Adding Virtual Disk Instructions
  1. After creating the virtual machine, select it on the virtual machine list and click Edit virtual machine settings.

  2. Click Add… and select Hard Disk. Select SCSI as the virtual disk type.

  3. Select Create a new virtual disk. Specify the maximum size for this additional virtual disk. This disk stores data in TrueNAS. If desired, allocate the disk space immediately by setting Allocate all disk space now.

  4. Select Store virtual disk as single file.

  5. Enter a 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 for descriptions of the various pool (“vdev”) types and layouts.

Using the TrueNAS Installer

Just as with installing TrueNAS on physical hardware, complete the installation in the VM by booting into the TrueNAS installer.

Using the TrueNAS Installer in a Virtual Machine

Select the virtual machine from the list and click Play virtual machine. The machine starts and boots into the TrueNAS installer.

  1. Select Install/Upgrade.

  2. Select the desired install drive.

    Select Yes to proceed with a clean installation of TrueNAS from the .iso. This erases the contents of the selected drive!

  3. Select option 1 Administrative user (truenas_admin) then OK to install TrueNAS and create the truenas_admin user account and password. TrueNAS has implemented an administrator login as a replacement for the root user login as a security hardening measure. The system retains root as a fallback, but it is no longer the default. The truenas_admin account has full control over TrueNAS and is used to log in to the web interface.

    Set a strong password and protect it.

    Next, enter a password for the new truenas_admin user.

  4. Select Yes at the Legacy Boot prompt to allow the system to boot via UEFI, or select No if your system hardware requires legacy BIOS boot. Press Enter to begin the installation.

  5. Select OK when the Installation Succeeded screen shows and press Enter to exit from the installer.

After the TrueNAS installation completes, reboot the system. The Console Setup menu displays when the system boots successfully.

Congratulations, TrueNAS is now installed!

The next step is to configure TrueNAS network and general settings. Experienced users can use the Console Setup Menu to configure network settings, but if you are unfamiliar with the Console setup menu and how network configuration works, we recommend using the TrueNAS UI to configure settings. TrueNAS uses DHCP to assign an IP address to the primary system interface and displays it at the top of the Console Setup menu screen. Use this IP address to log into the web UI.