Skip to main content

Unraid

Unraid runs the image as a KVM virtual machine. You copy the qcow2 disk to the domains share, create a Linux machine that uses it as its disk, attach a seed ISO with your SSH key, and start it.

Before you start​

  • Unraid 7, with VMs enabled under Settings > VM Manager and the domains and isos shares in place.
  • A server with an Intel or AMD processor and hardware virtualization switched on in its firmware. The image is amd64 only.
  • Room on the server: 2 vCPU and 4 GB of memory free for the machine, and 40 GB or more of disk, as Hardware describes.
  • A network bridge to your LAN, usually br0, so the machine gets an address on your network.
  • Your SSH public key: the one line in the .pub file, such as ~/.ssh/id_ed25519.pub. It goes on the seed ISO.
  • The file: the qcow2, antelao-ohm-<version>-amd64.qcow2.

Download​

Download the qcow2 from the table on the overview page, then check it before you use it. Run this in the folder you downloaded it to:

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, and how to check on Windows or a Mac.

You can also download it on the Unraid server itself, from its terminal (the >_ icon in the web interface), straight into the folder the next step uses.

Import​

Unraid has no import as such: a machine's disk is a file on the domains share, and you point a new machine at it.

  1. Make a folder for the machine on the domains share and copy the qcow2 into it, over the network share (\\tower\domains on Windows, smb://tower/domains on a Mac) or on the server:

    mkdir -p /mnt/user/domains/antelao-ohm
    cp antelao-ohm-<version>-amd64.qcow2 /mnt/user/domains/antelao-ohm/

  2. To give the machine more than 40 GB, grow the disk now, while the server is not running on it. The first boot uses the space:

    qemu-img resize /mnt/user/domains/antelao-ohm/antelao-ohm-<version>-amd64.qcow2 100G

  3. Open the VMs tab and click Add VM, then choose the Linux template.

  4. Switch the form to Advanced View (the toggle at the top right) and fill it in:

    • Name: for example antelao-ohm.
    • CPU cores: 2 or more. Initial Memory: 4096 MB or more.
    • Machine: Q35, the default for Linux.
    • BIOS: OVMF or SeaBIOS. The disk boots both. It can only be chosen when the machine is created.
    • Primary vDisk Location: Manual, then the qcow2 you copied, for example /mnt/user/domains/antelao-ohm/antelao-ohm-<version>-amd64.qcow2.
    • Primary vDisk Type: qcow2. Primary vDisk Bus: VirtIO.
    • Network Source: the bridge to your LAN, usually br0. virbr0 is a private network behind the Unraid server, where nothing else on your network can reach the machine.
    • Graphics Card: Virtual, with VNC, so you can watch its screen.

  5. Leave the form open for the next section.

Give it your SSH key​

Unraid has no field for an SSH key, so you hand the key over on a seed ISO.

  1. Build seed.iso with the seed ISO builder on the overview page.
  2. Copy it to the isos share, next to your other installation discs.
  3. In the form, choose seed.iso as the OS Install ISO. The seed is a data disc, not a boot disc: the machine finds no system on it and boots from its disk, and the first boot finds the seed in the CD drive.
  4. Clear Start VM after creation if you want to check the settings first, then click Create.

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

Start it and wait for the first boot​

  1. On the VMs tab, click the machine's icon and choose Start, if it is not running yet.
  2. Choose VNC Remote from the same menu to watch its screen.

The screen shows the usual Linux boot messages, then a login prompt. Among the messages, cloud-init prints a table of the network devices, its lines starting with ci-info, with the address the machine received. Your router's list of DHCP leases shows the same address.

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

Reach the console​

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

ssh debian@192.168.1.50

Once the first boot is done, the login message shows the console's address. Read the administrator's first password:

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

With a password on the seed instead of a key, sign in as debian on the machine's screen through VNC Remote. SSH keeps refusing passwords.

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

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​

  • The machine stops at a firmware shell or "no bootable device". It tried the seed ISO and gave up. Stop it, edit it and check that the disk comes first in the boot order, or recreate it with the other BIOS choice.
  • A screen that stays black with OVMF. Recreate the machine with Machine set to Q35, as Unraid's own documentation advises.
  • No address appears. Check Network Source: the machine must be on the bridge to your LAN, not on virbr0. Settings > Network Settings shows whether bridging is on.
  • Keep the disk where it is. The machine runs on the file you named. Moving or renaming it breaks the machine; back it up with the machine stopped, or use Unraid's own snapshots.
  • Nothing reaches the server from outside your network. Your router has to forward ports 80 and 443 to the machine's address before Let's Encrypt can issue certificates for your instances. Never forward the console's port 5322.
  • The first boot failed. The login message says FAILED with the reason. See What the first boot does for how to run it again.
  • The seed ISO afterwards. Leave it attached: a machine whose seed disappears looks new to cloud-init at its next start, as Keep the seed attached explains. It holds a hash of your password, if you gave one, so keep the isos share where only administrators can reach it.
Last updated on