Skip to main content

TrueNAS SCALE

TrueNAS SCALE runs the qcow2 image as a virtual machine under Virtual Machines. The Create Virtual Machine wizard converts the image onto a zvol, and a seed ISO attached as the machine's installation media hands it your SSH key.

Before you start​

  • TrueNAS SCALE 25.10 ("Goldeye") or later, on a machine whose processor supports virtualization. In 25.10, Virtual Machines and Containers are separate entries in the menu; everything below is under Virtual Machines.
  • A pool with room for a 40 GB zvol, and a dataset on it for the image and the seed, for example tank/images.
  • Room for the machine: 2 vCPU and 4 GB of memory or more, as Hardware describes.
  • A network interface of the TrueNAS machine on a network the machine can reach the internet from, with DHCP.
  • A VNC client, to see the machine's screen. TrueNAS 25.10 has no screen of its own for it in the browser.
  • Your SSH public key: the one line in the .pub file, such as ~/.ssh/id_ed25519.pub.
  • The file: the qcow2, antelao-ohm-<version>-amd64.qcow2.

Download​

Download the image onto the dataset from a shell on TrueNAS, System > Shell, or over SSH:

cd /mnt/tank/images
curl -fsSLO https://images.antelao.io/ohm/stable/<version>/antelao-ohm-<version>-amd64.qcow2
curl -fsSLO https://images.antelao.io/ohm/stable/<version>/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS

sha256sum must print OK after the image's name. To check the signature on SHA256SUMS as well, run the full check on a machine with cosign:

curl -fsSLO https://packages.antelao.io/raw/cosign.pub
sha256sum cosign.pub
curl -fsSLO https://images.antelao.io/ohm/stable/0.23.0/SHA256SUMS
curl -fsSLO https://images.antelao.io/ohm/stable/0.23.0/SHA256SUMS.sig
cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig \
  --insecure-ignore-tlog=true SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS

Verify the download says what must come out right.

Give it your SSH key​

  1. Build seed.iso with the seed ISO builder on the overview page.
  2. Copy it to the same dataset, for example with scp to /mnt/tank/images/seed.iso.

The wizard attaches it as the machine's installation media in the next section.

No seed? The machine's own screen shows the console address and a one-time sign-in code after the first boot.

Import​

Open Virtual Machines and click Add. The Create Virtual Machine wizard has seven steps:

  1. Operating System: Guest Operating System Linux, a Name such as odoo1, and Boot Method UEFI. Leave Enable Secure Boot clear. Keep Enable Display (VNC) ticked and set a Password: the display requires one, and it is what your VNC client asks for.

  2. CPU And Memory: Virtual CPUs 2, Cores 1, Threads 1, CPU Mode Host Passthrough, and Memory Size 4 GiB or more.

  3. Disks: keep Create new disk image and tick Import Image. Image Source: the qcow2 on your dataset. Select Disk Type: VirtIO. Zvol Location: your pool. Size: 40 GiB or more. TrueNAS proposes 10 GiB, which is smaller than the image.

  4. Network Interface: Adapter Type VirtIO, and under Attach NIC the TrueNAS interface on your network.

  5. Installation Media: choose seed.iso on your dataset. TrueNAS attaches it as a CD-ROM; the machine still boots from its disk.

  6. GPU: nothing to change.

  7. Confirm Options: check that Import Image names the qcow2 and Installation Media the seed, then click Save.

TrueNAS now converts the image onto a zvol, which takes a few minutes, and only then creates the machine. Keep the browser tab open until it says Virtual machine created. The machine is created by the page itself: closing the tab during Converting disk image leaves a zvol and no machine, although the conversion job reports success.

Start it and wait for the first boot​

  1. In Virtual Machines, expand the machine's row and click Start.
  2. Click Display. TrueNAS shows the address to give your VNC client, port 5900 on the TrueNAS machine. Connect to it with the password from step 1 of the wizard. Serial Shell in the same row shows the machine's serial console instead.

The screen shows boot messages, then a login prompt with the machine's name. The machine takes an address from your network's DHCP; your router's list of DHCP leases shows it.

The login prompt appearing does not mean the work is done. The first boot installs the server in the background, which takes several minutes, longer on a slow connection or slow disks. Sign in over SSH meanwhile and the login message says how far it is.

Kernel messages may print over the login prompt while the containers start. Nothing is wrong: press Enter for a fresh login: line.

Reach the console​

Sign in over SSH as debian with your key, using the machine's address:

ssh debian@192.0.2.166

The login message is shown when you sign in over SSH, not on the machine's screen. Once the first boot is done, it shows the console's address. Read the administrator's first password:

sudo cat /root/antelao-ohm-handoff.json

Then open the console through an SSH tunnel from your own computer, which opens no port on the machine:

ssh -N -L 5322:127.0.0.1:5322 debian@192.0.2.166

Browse to https://localhost:5322/ and accept the self-signed certificate once. From here, carry on with the installation page:

  1. Check the server
  2. Reach the console
  3. Sign in and finish the setup
  4. Create your first instance

Platform notes and troubleshooting​

  • No machine after Save, but a new zvol. The browser tab was closed, or lost its connection, while the image was converting. Delete the leftover zvol under Datasets, named after the machine, and run the wizard again with the tab kept open.
  • The disk is too small. Size in the wizard's Disks step must be at least the image's 40 GiB.
  • Display shows no screen in the browser. That is how 25.10 works: use a VNC client with the address Display shows and the password from the wizard, or Serial Shell.
  • SSH refuses the key. Sign in as debian, and check that the seed ISO was the machine's installation media. The seed is read at the first boot only, so create the machine again.
  • The first boot is slow or fails with timeouts. The first boot pulls and starts the server's containers, and a machine short of CPU takes much longer. Give it the CPUs and memory above. The login message says FAILED with the reason; see What the first boot does for how to run it again.
  • Nothing reaches the server from outside your network. Ports 80 and 443 must reach the machine before Let's Encrypt can issue certificates for your instances. Keep the console's port 5322 closed.
Last updated on