Quick start

GoNIX boots straight from a live image, with no installer to run first. Pick your platform:

First, about SSH. GoNIX accepts public keys only, and a published image authorises no key at all: it trusts nobody until you tell it who you are. Every command below therefore hands it your public key: on a direct kernel boot via the gonix.sshkey= kernel option, on a local ISO via a small cloud-init seed, and on a cloud instance via the provider’s own metadata. (root also has the password gonix at the console, which is the VM’s screen or serial line, never over the network.)

QEMU on x86-64

The ISO boots a fixed kernel command line, so your key goes in through a cloud-init seed, a tiny second CD-ROM. tools/mkseed.sh in the repo builds one, so clone it first, or roll the seed by hand as shown below (a volume labelled cidata holding meta-data and user-data).

$ curl -LO https://pkgs.ulinux.org/images/gonix-amd64.iso
$ git clone https://git.mills.io/prologic/gonix
$ gonix/tools/mkseed.sh ~/.ssh/id_ed25519.pub seed.iso
$ qemu-system-x86_64 -m 1G -cdrom gonix-amd64.iso \
    -drive file=seed.iso,index=1,media=cdrom \
    -device virtio-rng-pci \
    -nic user,hostfwd=tcp::2222-:22
$ ssh -p 2222 root@localhost

The Go userspace reaches a login prompt about 20 ms after the kernel starts it.

Without the seed the VM still boots fine; you just log in at the console (root / gonix) rather than over SSH.

To roll the seed by hand instead of cloning the repo, replace the git clone and mkseed.sh lines above with:

$ mkdir -p seed && cd seed
$ printf 'instance-id: gonix\nlocal-hostname: gonix\n' > meta-data
$ printf '#!/bin/sh\nmkdir -p /root/.ssh\ncat > /root/.ssh/authorized_keys << EOF\n%s\nEOF\n' \
    "$(cat ~/.ssh/id_ed25519.pub)" > user-data
$ cd .. && xorrisofs -J -r -V cidata -o seed.iso seed/

The volume label must be cidata, because that is what cloud-init looks for. On macOS without xorrisofs, use hdiutil makehybrid -iso -joliet -default-volume-name cidata -o seed.iso seed/.

QEMU on arm64 (Apple Silicon)

The fastest arm64 path is the bare kernel + initramfs, booted natively under HVF:

$ curl -LO https://pkgs.ulinux.org/images/gonix-arm64-Image
$ curl -LO https://pkgs.ulinux.org/images/gonix-arm64-rootfs.gz
$ qemu-system-aarch64 -machine virt,accel=hvf -cpu host -m 1G \
    -kernel gonix-arm64-Image -initrd gonix-arm64-rootfs.gz \
    -append "console=ttyAMA0 gonix.sshkey=$(base64 < ~/.ssh/id_ed25519.pub | tr -d '\n')" \
    -device virtio-rng-pci \
    -nic user,hostfwd=tcp::2222-:22 -nographic
$ ssh -p 2222 root@localhost

Two things that line is doing:

  • gonix.sshkey= authorises your public key at boot. It takes base64 because the kernel splits its command line on spaces and a key has spaces in it. Give the option more than once to authorise more than one key.
  • console=ttyAMA0 puts the kernel log and a login on the serial line, which is where -nographic leaves you.

The virtio-rng device seeds the kernel CRNG so the SSH host key can be generated at boot. The VirtualBox tab shows what happens without one.

VirtualBox on Apple Silicon

GoNIX also ships a UEFI-bootable arm64 ISO. In VirtualBox 7.1+ create an ARM 64-bit VM, attach the ISO, and boot. You log in at the VM console window.

https://pkgs.ulinux.org/images/gonix-arm64.iso

A few VirtualBox-on-ARM specifics:

  • Give the VM a USB keyboard and USB mouse, with a USB controller enabled. The ARM platform has no PS/2 controller, so VirtualBox’s default PS/2 input never reaches the guest and the console won’t accept keystrokes. Enable a USB controller (xHCI) under the VM’s USB settings, then: VBoxManage modifyvm <vm> --keyboard usb --mouse usb --usbxhci on. Use a relative USB mouse (--mouse usb), not the absolute USB tablet: VirtualBox’s ARM target doesn’t deliver the tablet’s absolute coordinates, so “Mouse Integration” stays greyed out and the desktop (startgui) cursor won’t move. With a relative mouse the cursor is captured into the window instead; release it with the Host key.
  • Set the network adapter to Intel PRO/1000 (e1000). VirtualBox’s ARM virtio-net is unreliable, and GoNIX’s kernel drives e1000.
  • If a reboot shows “No bootable option or device was found”, reset the VM’s UEFI variable store (VBoxManage modifynvram <vm> inituefivarstore). It’s a quirk of VirtualBox’s preview ARM firmware, not the ISO.
  • Log in at the console window. SSH-over-NAT does not work yet: VirtualBox’s ARM preview exposes no random-number source, so the kernel can’t seed enough entropy to generate an SSH host key (see the note below). The console is fully functional.

For a full SSH-reachable arm64 box, use QEMU + UEFI firmware (edk2/AAVMF), which provides a virtio-rng device:

$ curl -LO https://pkgs.ulinux.org/images/gonix-arm64.iso
$ git clone https://git.mills.io/prologic/gonix
$ gonix/tools/mkseed.sh ~/.ssh/id_ed25519.pub seed.iso
$ qemu-system-aarch64 -machine virt,accel=hvf -cpu host -m 1G \
    -drive if=pflash,format=raw,readonly=on,file=edk2-aarch64-code.fd \
    -cdrom gonix-arm64.iso -device virtio-gpu-pci -device virtio-rng-pci \
    -drive file=seed.iso,if=none,id=cidata,format=raw,readonly=on \
    -device virtio-blk-pci,drive=cidata \
    -nic user,hostfwd=tcp::2222-:22
$ ssh -p 2222 root@localhost

The seed is attached as a virtio disk rather than a second CD-ROM because the arm64 virt machine has no IDE/SATA bus for one.

Note: environments without a hardware RNG. GoNIX relies on the kernel CRNG being seeded at boot, which on a VM means the hypervisor exposing an entropy source (a virtio-rng device, an EFI RNG, or a CPU RNG instruction). QEMU/KVM and cloud providers all do; VirtualBox’s experimental ARM target does not. Without one, the CRNG never initialises, so anything needing secure randomness (the SSH host key, TLS) blocks, though the console still works. Always give arm64 VMs a virtio-rng device where you can.

Any cloud with custom-ISO boot

GoNIX boots the live ISO directly without installing to disk, so the instance’s disk is free for your data. Point your provider at the public ISO URL:

https://pkgs.ulinux.org/images/gonix-amd64.iso

On first boot, GoNIX’s cloud-init pulls your SSH key and hostname from the provider’s metadata service (NoCloud and Vultr are supported today), so you land on a configured server with nothing baked into the image. This is the one case where you don’t have to do anything about keys.

Vultr, declaratively

resource "vultr_iso_private" "gonix" {
  url = "https://pkgs.ulinux.org/images/gonix-amd64.iso"
}

resource "vultr_instance" "gonix" {
  region   = "sgp"
  plan     = "vc2-1c-1gb"
  hostname = "gonix"
  iso_id   = vultr_iso_private.gonix.id
}

terraform apply, and Vultr fetches the ISO and boots it. This site runs this way, and the GoNIX repo has the full cloud-init-driven deploy (site + Let’s Encrypt TLS, reproducible from terraform apply alone).

Once you’re in, try pkg install htop and poke around. The Download page has checksums, per-commit archives, and the from-source build.