GenericCloud (QCOW2) Deployment

GenericCloud Deployment

RLC provides GenericCloud QCOW2 images for on-premises VM deployment. These images are provisioned using cloud-init.

Available GenericCloud Images

All images are available for x86_64 and aarch64 architectures. Download from the CIQ Portal.

No Password Is Set on This Image

The rocky user has full sudo access without a password. Root SSH login is disabled by cloud-init (disable_root: true), and SSH password authentication is disabled (ssh_pwauth: false). The supported way in is to provide an SSH public key through cloud-init at first boot, then connect with ssh rocky@<vm-ip-address>.

Quick Deployment (Recommended)

For virt-install 4.0 or later (Rocky Linux 9 and other EL9 hosts), copy the image into place and deploy with one virt-install command. Your SSH key is injected directly, with no separate cloud-init user-data or meta-data files:

sudo cp /path/to/RLC-Pro-9-GenericCloud.qcow2 /var/lib/libvirt/images/rlc-pro-vm.qcow2

sudo virt-install \
    --name rlc-pro-vm \
    --memory 4096 \
    --vcpus 2 \
    --import \
    --disk /var/lib/libvirt/images/rlc-pro-vm.qcow2 \
    --cloud-init clouduser-ssh-key=/path/to/id_ed25519.pub \
    --os-variant rocky9 \
    --graphics none \
    --console pty,target_type=serial

Key options:

• --import: Boots the existing disk image directly instead of running an OS installer. This flag is required. Without it, virt-install waits for an installation that never starts and hangs at Starting install....
• --cloud-init clouduser-ssh-key=: Injects the public key into the default cloud-init user (rocky). Do not confuse this with root-ssh-key= (or its legacy alias ssh-key=), which targets the root account; root logins are disabled on this image, so keys injected for root do not provide access.
• --graphics none --console pty,target_type=serial: Runs headless and attaches your terminal to the VM serial console. See Console Access.

When the VM is up, find its address and connect as rocky:

virsh domifaddr rlc-pro-vm
ssh rocky@<vm-ip-address>

Deploying with cloud-init Files

For older virt-install versions, or when you need fuller provisioning (packages, runcmd, multiple users), supply cloud-init user data files. Create the following files:

user-data:

#cloud-config
users:
  - name: rocky
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... user@example

meta-data:

instance-id: rlc-vm-01
local-hostname: rlc-vm-01

Deploy the VM

sudo virt-install \
    --name rlc-pro-vm \
    --memory 4096 \
    --vcpus 2 \
    --import \
    --disk /path/to/RLC-Pro-9-GenericCloud.qcow2 \
    --cloud-init user-data="$(pwd)/user-data,meta-data=$(pwd)/meta-data" \
    --os-variant rocky9 \
    --graphics none \
    --console pty,target_type=serial

For the full range of cloud-init directives, see the cloud-init documentation.

NoCloud ISO Alternative

On platforms where virt-install's --cloud-init option is unavailable (or on hypervisors other than libvirt), package the same user-data and meta-data files into a NoCloud seed ISO and attach it as a CD-ROM:

mkisofs -output seed.iso -volid cidata -joliet -rock user-data meta-data

sudo virt-install \
    --name rlc-pro-vm \
    --memory 4096 \
    --vcpus 2 \
    --import \
    --disk /path/to/RLC-Pro-9-GenericCloud.qcow2 \
    --disk seed.iso,device=cdrom \
    --os-variant rocky9 \
    --graphics none \
    --console pty,target_type=serial

The volume label must be exactly cidata for cloud-init to find the seed data.

Deploying with kvm-install-vm

For repeated lab deployments, kvm-install-vm is a community CLI wrapper around virt-install that stands up and tears down cloud-init based VMs with a single command. It generates the cloud-init data for you, injects your SSH public key automatically (it looks for ~/.ssh/id_rsa.pub, id_dsa.pub, or id_ed25519.pub, or accepts -k to specify one), and removes the VM together with its storage on teardown.

# Create a VM from the downloaded RLC image
kvm-install-vm create -c 2 -m 4096 -i /path/to/RLC-Pro-9-GenericCloud.qcow2 rlc-pro-vm

# Tear it down, including the associated storage
kvm-install-vm remove rlc-pro-vm

The tool prints the SSH connection details when the VM is ready. By default the login user matches your local username; override it with -u.

Console Access for Headless Deployments

On a host with no graphical display, add --graphics none --console pty,target_type=serial to the virt-install command (as shown above) to attach your terminal to the VM serial console. To reconnect later:

virsh console rlc-pro-vm

Press Ctrl+] to leave the console. Remember that the console presents a login prompt you cannot use until a password exists on the VM: SSH as the rocky user is the intended access path. If the console connects but shows nothing at all, see No output on the serial console.

Setting a Password (Development Only)

Generated Root Password

virt-install can generate a one-time root password at deploy time:

sudo virt-install \
    --name rlc-pro-vm \
    --memory 4096 \
    --vcpus 2 \
    --import \
    --disk /var/lib/libvirt/images/rlc-pro-vm.qcow2 \
    --cloud-init root-password-generate=on \
    --os-variant rocky9 \
    --graphics none \
    --console pty,target_type=serial

virt-install prints the generated password to your terminal and pauses for about 10 seconds so you can record it. Log in as root on the console; you are forced to change the password at first login. Note this logs you in as root, which the image otherwise keeps disabled, so treat it strictly as a quick dev-only escape hatch. You can combine it with clouduser-ssh-key= in the same --cloud-init option.

Password via cloud-init User Data

To give the rocky user a password, several image defaults must be overridden together in user-data:

#cloud-config
users:
  - name: rocky
    lock_passwd: false
    plain_text_passwd: <temporary-password>
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... user@example
ssh_pwauth: true

All three overrides matter: lock_passwd: false unlocks the account, a password directive sets the password, and ssh_pwauth: true permits password authentication over SSH (omit it to allow console login only). Leaving any one out silently preserves the key-only default.

NVIDIA Image with GPU Passthrough

For the NVIDIA (CUDA) image, attach a GPU using PCI passthrough:

sudo virt-install \
    --name rlc-pro-gpu-vm \
    --memory 16384 \
    --vcpus 8 \
    --import \
    --disk /path/to/RLC-Pro-9-Cuda-GenericCloud.qcow2 \
    --cloud-init clouduser-ssh-key=/path/to/id_ed25519.pub \
    --host-device <pci-address> \
    --os-variant rocky9

Use lspci | grep -i nvidia on the host to identify the GPU PCI address (e.g., pci_0000_41_00_0).

Resizing the Disk

Resize the QCOW2 image before first boot if your workload requires more space:

qemu-img resize /path/to/RLC-Pro-9-GenericCloud.qcow2 100G

The guest filesystem will be expanded automatically on first boot by cloud-init's growpart and resizefs modules.

Post-Deployment Setup

After the VM boots, SSH in as the rocky user and set up repository access:

# Log in to CIQ Depot
sudo depot login -u [USER STRING] -t [USER TOKEN]

# Enable RLC Pro (or RLC+)
sudo depot enable rlc-pro-9

# Update the system
sudo dnf update -y

Verify the Deployment

# System identity
cat /etc/os-release

# CIQ kernel
uname -r

# Active repositories
sudo dnf repolist

Expected output for RLC Pro 9.7:

PRETTY_NAME="Rocky Linux from CIQ Pro 9.7 (Blue Onyx)"

5.14.0-611.34.1+2.1.el9_7_ciq.x86_64

Troubleshooting

virt-install hangs at "Starting install..."

The command is missing --import. Without it, virt-install waits for an OS installation that never begins and gives no diagnostic. Destroy the stuck domain and rerun with --import:

virsh destroy rlc-pro-vm
virsh undefine rlc-pro-vm

Cannot log in at the console

Expected behavior: the image ships with no password (see No Password Is Set on This Image). SSH in as rocky using the key you injected, or redeploy with one of the methods above.

cloud-init configuration is not applied to a copied image

cloud-init runs its per-instance configuration (including runcmd) only once per instance ID, and that state lives on the disk image in /var/lib/cloud. If you boot a qcow2, then cp it to create a "fresh" VM, the copy inherits the original's state and silently skips first-boot provisioning. Either:

• Always copy from the pristine downloaded image, never from one that has booted, or
• Clean the source VM before copying:

sudo cloud-init clean

• Or supply a new instance-id in meta-data, which makes cloud-init treat the VM as a new instance.

VM powers off instead of rebooting after first deployment

virt-install treats the first boot as an installation phase, so a reboot issued inside the guest during that first boot (for example after a dnf update) shuts the domain off instead of restarting it. This is normal: start it again with virsh start <vm-name>. Subsequent reboots behave normally.

SSH key was injected but no account accepts it

The virt-install suboption ssh-key= is a legacy alias of root-ssh-key=; both inject the key for the root account, and root logins are disabled on this image, so the key provides SSH access to nobody. To inject a key for the rocky user, use clouduser-ssh-key= as shown in Quick Deployment.

No output on the serial console

The GenericCloud image's kernel command line does not include console=ttyS0, so boot messages and the login prompt go only to the graphical console. For a one-off VM, connect with virt-viewer or virt-manager instead, or SSH in directly as rocky. For scripted or fully headless environments, fix the image itself: log in once and direct the kernel to the serial console, then reboot:

sudo grubby --update-kernel=ALL --args="console=ttyS0,115200n8"

If you maintain a master image for repeated deployments, apply this once in the master (together with cloud-init clean, see above) so every VM copied from it boots with a working serial console.

Support

For deployment issues, contact CIQ Support or refer to the FAQs.