Skip to main content

Proxmox VE

Proxmox VE runs the qcow2 image as an ordinary virtual machine. Proxmox downloads the image itself and checks its checksum, the Create VM wizard imports it as the machine's disk, and Proxmox's own Cloud-Init drive hands the machine your SSH key. No seed ISO is needed.

Everything below can be done in the web interface or, further down, with qm on the Proxmox host.

Before you start​

  • Proxmox VE 9.
  • Room for the machine: 2 vCPU, 4 GB of memory or more, and 40 GB or more of disk, as Hardware describes. Proxmox proposes 2 GB of memory and 1 core, so both are raised below.
  • A storage with the Import content type, for the image file. The local storage of a standard install has it. If Import is missing under your storage, add it under Datacenter > Storage > your storage > Edit > Content.
  • A bridge the machine can reach the internet from, and you can reach it on: usually vmbr0, bridged to your network with its DHCP.
  • 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​

Proxmox downloads the image straight onto its storage and checks it there, so nothing passes through your own computer. Copy the qcow2's link and its checksum from the table on the overview page first.

  1. In the resource tree, open your node, then the storage that holds imports, such as local.
  2. Choose Import > Download from URL.
  3. URL: the qcow2's link, https://images.antelao.io/ohm/stable/<version>/antelao-ohm-<version>-amd64.qcow2. Click Query URL; Proxmox fills in the file name and the size.
  4. Tick Advanced. Hash algorithm: SHA-256. Checksum: the qcow2's checksum from the table, which is also its line in SHA256SUMS.
  5. Click Download.

The task log ends with checksum verified and TASK OK, and the file shows under Import.

The checksum proves the file matches SHA256SUMS. To check the signature on SHA256SUMS itself, run this in a folder on the Proxmox host or any Linux machine:

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.

Import​

Click Create VM at the top right and go through the wizard:

  1. General: a VM ID and a name, for example odoo-1.

  2. OS: Do not use any media. Guest OS Linux, with the proposed version.

  3. System: Machine q35 and BIOS OVMF (UEFI), with Add EFI Disk ticked and an EFI Storage. Leave Pre-Enroll keys ticked: the image boots with Secure Boot on. Tick Qemu Agent; the image carries the agent, and Proxmox then shows the machine's address. SeaBIOS works as well, if you prefer it.

  4. Disks: delete the proposed disk scsi0 with its bin icon, then click Import. Import Storage: the storage you downloaded to. Select Image: antelao-ohm-<version>-amd64.qcow2. Target Storage: where the machine's disk should live, such as local-lvm. Tick Discard if your storage supports it. The disk takes the image's size, 40 GB; Hardware says when to give it more.

  5. CPU: Cores 2. The proposed CPU type works.

  6. Memory: 4096 MiB or more. Proxmox proposes 2048, which is too little.

  7. Network: your bridge, such as vmbr0, with the VirtIO model.

  8. Confirm: leave Start after created clear. The Cloud-Init drive comes first. Click Finish.

Give it your SSH key​

Proxmox hands the key to the machine on a Cloud-Init drive. The drive holds what the Cloud-Init page says, so fill that page in before the first start.

  1. Select the new machine, open Hardware and choose Add > CloudInit Drive.
  2. Bus/Device: IDE, with the number Proxmox proposes. Do not use any media left an empty CD drive on ide2, so the Cloud-Init drive takes ide0, which is fine. Storage: any storage for disk images. Click Add.
  3. Open the machine's Cloud-Init page and edit these lines:
    • User: debian.
    • SSH public key: paste your public key.
    • IP Config (net0): IPv4 DHCP, or a static address. This line is empty by default, and a machine without it gets no address at all.
    • DNS domain and DNS servers: leave them on use host settings, unless the Proxmox host itself resolves through a local stub such as 127.0.0.53 (systemd-resolved). A machine cannot use that address, so its first boot cannot reach the package repository or the registry. Enter your network's DNS server instead.
    • Upgrade packages can stay Yes.
  4. Click Regenerate Image.

Proxmox gives the key to debian, the image's own user. Leave Password empty: SSH refuses passwords on this image, so a password only works on the machine's own screen.

Changing the Cloud-Init page after the first start makes the machine look new to cloud-init, which then gives it, for example, new SSH host keys. Once the server's install has completed, it does not run again; until then, the changed data starts it again, which is what the DNS fix under Platform notes and troubleshooting relies on.

With qm, on the Proxmox host​

The same machine from a root shell on the Proxmox host. Put your public key in a file on the host first, here my-key.pub, and set the version:

cd /var/lib/vz/import
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

qm create 101 --name odoo-1 --memory 4096 --cores 2 --cpu host --machine q35 --bios ovmf \
  --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=0 --scsihw virtio-scsi-single \
  --net0 virtio,bridge=vmbr0 --ostype l26 --agent enabled=1
qm importdisk 101 /var/lib/vz/import/antelao-ohm-<version>-amd64.qcow2 local-lvm
qm set 101 --scsi0 local-lvm:vm-101-disk-1,discard=on,ssd=1 --boot order=scsi0 \
  --ide2 local-lvm:cloudinit --ciuser debian --sshkeys my-key.pub --ipconfig0 ip=dhcp
qm start 101

qm importdisk attaches the imported disk as unused0 and prints its name; use that name in --scsi0. pre-enrolled-keys=0 creates the EFI disk without Secure Boot keys, so this machine starts with Secure Boot off; the wizard's ticked Pre-Enroll keys box is pre-enrolled-keys=1 and starts it with Secure Boot on. The image boots either way.

For SeaBIOS, leave out --machine, --bios and --efidisk0; a single qm create can then import the disk itself:

qm create 102 --name odoo-2 --memory 4096 --cores 2 --cpu host --scsihw virtio-scsi-single \
  --scsi0 local-lvm:0,import-from=/var/lib/vz/import/antelao-ohm-<version>-amd64.qcow2 \
  --boot order=scsi0 --net0 virtio,bridge=vmbr0 --ostype l26 --agent enabled=1 \
  --ide2 local-lvm:cloudinit --ciuser debian --sshkeys my-key.pub --ipconfig0 ip=dhcp
qm start 102

When the host resolves through 127.0.0.53, add --nameserver with your network's DNS server, as the DNS line above explains. qm cloudinit dump 101 user and qm cloudinit dump 101 network show what Proxmox hands the machine.

No Cloud-Init drive? 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​

Click Start, then Console. The login prompt appears within seconds. The machine's Summary shows its address once the guest agent runs, under IPs.

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

The console fills with kernel messages while the containers start, and they print over the login prompt. Nothing is wrong: press Enter for a fresh login: line.

Reach the console​

Sign in over SSH as debian with your key, using the address from the Summary:

ssh debian@192.0.2.165

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

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 address. IP Config (net0) was left empty. Set it to DHCP, click Regenerate Image and restart the machine.

  • The first boot failed with Could not resolve 'deb.debian.org' or Name or service not known (ghcr.io:443). The machine took the host's DNS setting, a local stub it cannot use. Either set DNS servers on the Cloud-Init page and restart: the changed Cloud-Init data makes the first boot, which has not completed, run again by itself. Or, signed in on the machine, give it a DNS server and run the first boot again:

    sudo resolvectl dns eth0 <your DNS server>
    sudo /usr/local/lib/ohm/ohm-firstboot

  • SSH refuses the key. Sign in as debian, and check the SSH public key line on the Cloud-Init page. Only the public key belongs there, on one line.

  • The import storage is missing from the Disks page. The storage needs the Import content type; see Before you start.

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

  • The first boot failed for another reason. The login message says FAILED with the reason. See What the first boot does for how to run it again.

Last updated on