Skip to content

XCP-ng

In this article

Information

XCP-ng (Xen Cloud Platform - New Generation) is a free open-source hypervisor based on the Xen Project. XCP-ng was created as an open alternative to Citrix XenServer after Citrix limited the functionality of the free version. The project provides a fully-featured enterprise-level virtualization platform without any artificial limitations, supporting live migration, high availability, storage management, and integration with orchestration systems. XCP-ng is distributed under GPLv2 and compatible free licenses.

XCP-ng. Key Features

  • Virtualization: XCP-ng supports running multiple virtual machines on a single physical server with full isolation and efficient resource distribution. Supported guest OSes include Linux, Windows, and others.
  • Live Migration: ability to move running virtual machines between hosts without downtime, ensuring service continuity during hardware maintenance.
  • High Availability (HA): automatic restart of virtual machines on other pool hosts in case of server failure.
  • Storage Management: support for various types of Storage Repositories, including local disks, NFS, iSCSI, Ceph, and others.
  • Snapshots and Backup: creation of instant snapshots of virtual machine states for quick recovery and backup.
  • Resource Pools: combining multiple XCP-ng hosts into a single pool for centralized management and load distribution.
  • Network Capabilities: support for VLAN, network interface bonding, SR-IOV, and software-defined networks.
  • Web Management Interfaces: XCP-ng includes the built-in XO Lite web interface for basic management, while the full-featured Xen Orchestra (XO) provides advanced automation, monitoring, and backup capabilities.

XCP-ng Management Options

Several management interfaces are available for working with XCP-ng:

XO Lite (built-in, free):

  • Available immediately after XCP-ng installation at https://<server_IP_address>;
  • Basic web interface for creating and managing virtual machines;
  • Resource monitoring and basic operations;
  • Suitable for home labs and small projects;
  • Requires no additional configuration.

Xen Orchestra from Sources (free, requires installation):

  • Full-featured open-source management system;
  • Automatic backups, replication, advanced monitoring;
  • Centralized management of multiple hosts;
  • Requires creating a separate virtual machine and manual installation (Ubuntu/Debian);
  • Maintenance and updates are performed manually;
  • Support through community forums.

Xen Orchestra Appliance (XOA) (paid subscription, requires deployment):

  • Ready-made virtual machine with pre-installed Xen Orchestra;
  • Deployed via the "Deploy XOA" button in XO Lite interface;
  • Official technical support from Vates (24/7);
  • Automatic updates and SLA guarantees;
  • Small business plans: €2,000/year (ESSENTIAL, up to 3 hosts) or €4,000/year (ESSENTIAL+, full access) – details;
  • Recommended for production environments with support requirements.

The choice of option depends on infrastructure scale and technical support requirements. The built-in XO Lite is sufficient to get started, while more advanced features are available through installing the full-featured Xen Orchestra.

Minimum Server Requirements:

  • RAM: 8 GB;
  • HDD: 60 GB;
  • Virtualization: nested virtualization support.

Getting Started with XCP-ng After Deployment

After you pay for your order, you'll receive an email notification at the address you provided during registration, indicating that your server is ready. This email will include the VPS IP address and login credentials. Our company's clients manage their equipment through the server management panel and APIInvapi.

You can find the authorization details in either the Info >> Tags section of the server management panel or in the email you received:

  • Login: root;
  • Password: Sent to your email address after the server is ready for use following software deployment.

Authorization

Two methods are available for accessing the XCP-ng server: through the XO Lite web interface and via SSH.

Connecting via XO Lite

XO Lite is a built-in web interface for managing XCP-ng, accessible directly from the host.

  • Open a browser and navigate to https://<server_IP_address>:

  • Enter login root and the password from the email, then click the Login button.

Information

The browser may show a warning about an untrusted certificate - this is normal for a self-signed certificate. Add an exception to continue.

Connecting via SSH

  • Open a terminal and connect to the server with the command:
ssh root@<server_IP_address>
  • Enter the password when prompted. After successful connection, you will be in the XCP-ng command line.

Connecting via VNC Console

You can also use the VNC console in the Invapi control panel to access the host console:

The console provides a configuration menu that allows you to configure network parameters, authentication, virtual machine management, and other system parameters.

Working with xsconsole

When connecting via SSH or VNC console, you can use xsconsole - the built-in text management console for XCP-ng configuration and host administration.

To launch xsconsole, enter the command:

xsconsole

After launch, the system management menu will open:

Main xsconsole Sections

Status Display

  • Host status monitoring (CPU, memory, network, storage);
  • View running virtual machines;
  • General system information.

Network and Management Interface

  • Network interface configuration;
  • IP address configuration (static/DHCP);
  • Gateway and DNS server configuration.

Authentication

  • Changing root password;
  • SSH access management;
  • Account configuration.

Virtual Machines

  • View list of virtual machines;
  • Basic VM management (start, stop);
  • Guest system status control.

Disks and Storage Repositories

  • View connected disks;
  • Storage Repository management;
  • SR creation and deletion.

Resource Pool Configuration

  • Creating a pool from multiple hosts;
  • Joining an existing pool;
  • Server cluster management.

Hardware and BIOS Information

  • Processor and memory information;
  • Network card data;
  • BIOS and firmware versions.

Keyboard and Timezone

  • Keyboard layout configuration;
  • System timezone setting.

Remote Service Configuration

  • Remote access configuration;
  • SSH configuration;
  • SSL certificate management.

Backup, Restore and Update

  • Host configuration backup;
  • Settings restoration;
  • System update checking and installation.

Technical Support

  • Generate technical support report (bug report);
  • System log collection;
  • Diagnostic information.

Local Command Shell

  • Exit to standard bash command line;
  • For executing arbitrary commands and scripts.

Reboot or Shutdown

  • Host reboot;
  • Proper system shutdown.
  • Enter - select menu item/confirm action;
  • ↑/↓ - move through menu items;
  • Tab - switch between form elements;
  • Esc or q - return to previous menu/exit.

Tip

xsconsole is especially useful for initial server setup, emergency access recovery, or network configuration when the XO Lite web interface is unavailable. To exit xsconsole to the regular command line, select Local Command Shell.

Working with XO Lite

After authorization in XO Lite, the main management panel (Dashboard) opens:

The XO Lite interface contains the following sections:

  • DASHBOARD: general overview of host status, virtual machine status, storage usage, and notifications;
  • ALARMS: view system warnings and alerts;
  • STATS: performance and resource usage statistics;
  • SYSTEM: host system settings;
  • NETWORK: network interface and virtual network management;
  • STORAGE: data storage management (Storage Repositories);
  • TASKS: log of running and completed tasks;
  • HOSTS: information about hosts in the pool;
  • VMS: virtual machine management.

Network Management

The NETWORK tab displays available networks and their parameters:

Here you can view Pool-wide networks (available to all hosts in the pool) and Host internal networks, as well as create new network connections.

Creating a Virtual Machine

Preparation: Loading an ISO Image

Before creating a virtual machine, you need to load an ISO image of the operating system into the Storage Repository.

Loading ISO via SSH

XO Lite does not support uploading ISO images through the web interface. To upload an ISO, you must use the command line:

  1. Connect to the server via SSH

        ssh root@<server_IP_address>
    
  2. If the xsconsole opens after connection, exit to the regular command line by selecting the Local Command Shell menu item or pressing Ctrl+C.

  3. Find the UUID of the ISO storage

        xe sr-list content-type=iso
    
    Copy the UUID of the storage named "XCP-ng Tools".

  4. Navigate to the ISO storage directory

        cd /opt/xensource/packages/iso
    
  5. Download the ISO image

    Download from the internet:

        wget https://repo.almalinux.org/almalinux/9/isos/x86_64/AlmaLinux-9-latest-x86_64-boot.iso
    

    Or upload from local computer (execute on your PC)

        scp /path/to/file.iso root@<server_IP>:/opt/xensource/packages/iso/
    
  6. Rescan the storage

        xe sr-scan uuid=<UUID_SR>
    
    Where <UUID_SR> is the UUID obtained in step 3.

    After this, the ISO image will appear in the list of available images when creating a virtual machine.

Creating a VM via XO Lite

  • Click the New VM button in the upper right corner of the interface.

  • In the window that opens, fill in the virtual machine parameters:

    • Template: select the operating system template (e.g., AlmaLinux 9);
    • Install settings: choose installation method:
      • ISO/DVD: installation from ISO image (recommended) - select the loaded ISO from the list;
      • PXE: network installation (requires configured PXE server).
    • System: specify VM name, description, firmware type (BIOS/UEFI);
    • Memory: set the number of vCPUs and RAM amount.
  • Configure network connections and storage:

    • Network: select network interface for VM connection;
    • Storage: select storage and specify disk size;
    • Settings: enable automatic VM startup at boot (optional).
  • Review the final configuration in the Summary section and click the Create button.

After creation, the virtual machine will automatically start and boot from the ISO image will begin. The XO Lite interface will open the Dashboard page of the created VM:

The Dashboard page displays:

  • Quick info: basic VM information (status, UUID, host, resources);
  • CPU usage: processor usage graph;
  • RAM usage: memory usage graph;
  • Network throughput: network activity graph;
  • VDI throughput: disk activity graph;
  • Change state: VM state management menu (start, pause, reboot, shutdown).

To access the virtual machine console and begin operating system installation, go to the CONSOLE tab.

Tip

For network installation (Boot ISO), ensure that the virtual machine has internet access through the configured network, as installation packages will be downloaded from the repository.

ISO Image Selection

When selecting an ISO image, consider the image type:

For Linux (using AlmaLinux as example):

  • DVD/Full ISO (~4-10 GB) - full image, contains all packages, doesn't require internet
    • AlmaLinux-9-latest-x86_64-dvd.iso;
    • Ubuntu-22.04-server.iso.
  • Boot/Minimal ISO (~1 GB) - minimal image, requires active internet connection to download packages
    • AlmaLinux-9-latest-x86_64-boot.iso;
    • Ubuntu-22.04-live-server.iso.

Recommendation: For reliable installation, use full ISO images (DVD/Full), especially if the VM has unstable or no internet connection.

Firmware Selection Recommendations

  • UEFI - recommended for modern OSes:
    • Linux: AlmaLinux 9+, Ubuntu 20.04+, Debian 11+;
    • Windows: Windows Server 2016+, Windows 10/11.
  • BIOS - for compatibility:
    • Older OS versions;
    • When encountering UEFI boot issues;
    • Specific scenarios (legacy applications).

Software Selection Choice

When installing Linux distributions, various environment options are available:

  • Minimal Install - basic system without GUI (~400-600 packages, 5-10 minute installation)
    • Recommended for servers and production;
    • Minimal resource consumption.
  • Server with GUI - full system with graphical interface (~1000-1500 packages, 15-30 minute installation)
    • Convenient for learning and testing;
    • Requires more resources (RAM, CPU, disk).

For production servers, Minimal Install is recommended.

Installing XCP-ng Guest Tools

After installing the operating system, it is critically important to install XCP-ng Guest Tools for correct virtual machine operation.

Why Guest Tools Are Needed

Guest Tools provide:

  • Correct VM shutdown and reboot (soft shutdown);
  • Display of IP address and VM status in XCP-ng interface;
  • Improved network and disk performance;
  • Time synchronization between host and guest OS;
  • Snapshot support with quiesce (consistent snapshots);

Important

Without installed Guest Tools, the virtual machine may work unstably, especially regarding network connections and state management.

Guest Tools Installation Sequence

Step 1: Complete OS Installation

After operating system installation, when a completion message or reboot prompt appears:

Important

Do not reboot the virtual machine immediately. First, you need to replace the installation ISO with guest-tools.iso.

Exception: If you have already rebooted the VM, that's fine - the ISO can be connected after the first boot of the installed system.

Step 2: Replace ISO with Guest Tools (on XCP-ng host)

Connect to the XCP-ng host via SSH and execute commands.

Find your VM's UUID:

xe vm-list name-label="VM_NAME"

Or get a list of all running VMs:

xe vm-list power-state=running

Eject the installation ISO (if connected):

xe vm-cd-eject uuid=<UUID_VM>

Insert guest-tools ISO:

xe vm-cd-insert uuid=<UUID_VM> cd-name="guest-tools.iso"

Verify that the ISO has been replaced:

xe vbd-list vm-uuid=<UUID_VM> type=CD

Step 3: VM Reboot

  • If you haven't rebooted after installation yet: In the VM console, press "Reboot System" or execute the reboot command;
  • If already in a running system: Reboot is not required, proceed to Step 4.

Step 4: Install Guest Tools in Guest OS

The installation procedure depends on the operating system:

For Linux (RHEL-based: AlmaLinux, Rocky, CentOS, RHEL)

Log in to the system as root and execute commands.

Create mount point:

mkdir -p /mnt/cdrom

Mount guest-tools ISO:

mount /dev/sr0 /mnt/cdrom

If /dev/sr0 doesn't work, try alternative options:

mount /dev/cdrom /mnt/cdrom

or

mount /dev/xvdd /mnt/cdrom

Check contents:

ls -la /mnt/cdrom/Linux/

Navigate to directory:

cd /mnt/cdrom/Linux

Run installation:

bash install.sh

Note

Installation may hang at 100% for 30-60 seconds - this is normal. If it hangs for more than 2 minutes - press Ctrl+C and check the result.

Verify installation:

rpm -qa | grep xe-guest

Check service status:

systemctl status xe-linux-distribution

Unmount ISO:

cd ~
umount /mnt/cdrom

Reboot the system to apply changes:

reboot

For Linux (Debian-based: Ubuntu, Debian)

Log in to the system as root or use sudo.

Create mount point:

sudo mkdir -p /mnt/cdrom

Mount guest-tools ISO:

sudo mount /dev/sr0 /mnt/cdrom

Navigate to directory:

cd /mnt/cdrom/Linux

Run installation:

sudo bash install.sh

Verify installation:

dpkg -l | grep xe-guest

Check service status:

sudo systemctl status xe-linux-distribution

Unmount ISO:

cd ~
sudo umount /mnt/cdrom

Reboot system:

sudo reboot

Alternative Method for Linux: Installation via Repository

If ISO mounting doesn't work or you want to install Guest Tools via package manager.

For RHEL-based (AlmaLinux, Rocky, CentOS) install EPEL repository:

sudo dnf install -y epel-release

Install xe-guest-utilities:

sudo dnf install -y xe-guest-utilities

Enable service:

sudo systemctl enable xe-linux-distribution

Start service:

sudo systemctl start xe-linux-distribution

Check status:

sudo systemctl status xe-linux-distribution

Note

Installation via repository requires active internet connection in the VM.

Step 5: Verify Guest Tools Operation

After reboot and Guest Tools installation, verify their operation.

In guest OS (Linux) check service status:

systemctl status xe-linux-distribution

Check version:

xe-daemon --version

On XCP-ng host check network information display:

xe vm-param-get uuid=<UUID_VM> param-name=networks

Check PV drivers status:

xe vm-param-get uuid=<UUID_VM> param-name=PV-drivers-version

Get general VM information:

xe vm-param-list uuid=<UUID_VM> | grep -E "PV-drivers|networks"

Virtual Machine Management

The VMS tab displays a list of all virtual machines with management capabilities:

Available actions:

  • Change state: start, stop, reboot VM;
  • Migrate: migrate VM to another host;
  • Copy: create a copy of the virtual machine;
  • Edit config: edit VM configuration;
  • Snapshot: create a state snapshot;
  • Export: export VM to a file;
  • Delete: delete virtual machine.

Working with Storage, ISO and Networks

Managing Storage Repositories (SR)

View all storage:

List all SRs

xe sr-list
Detailed information about specific SR

xe sr-param-list uuid=<UUID_SR>
View disk space usage

xe sr-list params=name-label,physical-size,physical-utilisation,uuid

Working with ISO Storage:

Find ISO SR

xe sr-list content-type=iso
Get path to ISO SR

xe pbd-list sr-uuid=<UUID_SR>
Navigate to ISO directory (usually /opt/xensource/packages/iso)

cd /opt/xensource/packages/iso
View available ISOs

ls -lh
Download ISO from internet

wget https://example.com/os.iso
Upload ISO from local computer

scp /path/to/file.iso root@<server_IP>:/opt/xensource/packages/iso/

Attention

You must rescan SR after adding ISO

xe sr-scan uuid=<UUID_SR>
Verify that ISO appeared

xe vdi-list sr-uuid=<UUID_SR>

Managing Local Storage

View virtual disks (VDI):

xe vdi-list sr-uuid=

Check free space:

df -h

View snapshot list:

xe snapshot-list | grep snapshot

Delete snapshot:

xe snapshot-uninstall snapshot-uuid=

Network Management

View all networks:

xe network-list

Detailed network information:

xe network-param-list uuid=

View physical interfaces (PIF):

xe pif-list

Specific PIF details:

xe pif-param-list uuid=

Check host IP address:

ip addr show

Create internal network:

xe network-create name-label="Internal Network" name-description="Private VM network"

Create VLAN network:

xe network-create name-label="VLAN100" name-description="VLAN 100" vlan=100 pif-uuid=

View VM network interfaces:

xe vif-list vm-uuid=

Create new network interface for VM:

xe vif-create vm-uuid= network-uuid= device=0

Basic CLI Commands

Virtual Machine Management

List all VMs:

xe vm-list

Only running VMs:

xe vm-list power-state=running

Detailed VM information:

xe vm-param-list uuid=<UUID_VM>

Start VM:

xe vm-start uuid=<UUID_VM>

Shutdown VM:

xe vm-shutdown uuid=<UUID_VM>

Reboot VM:

xe vm-reboot uuid=<UUID_VM>

Suspend VM:

xe vm-suspend uuid=<UUID_VM>

Force shutdown VM:

xe vm-shutdown uuid=<UUID_VM> force=true

Create snapshot:

xe vm-snapshot uuid=<UUID_VM> new-name-label="backup-$(date +%Y%m%d)"

List snapshots:

xe snapshot-list

Restore from snapshot:

xe snapshot-revert snapshot-uuid=<UUID_snapshot>

Delete snapshot:

xe snapshot-uninstall snapshot-uuid=<UUID_snapshot>

Export VM:

xe vm-export uuid=<UUID_VM> filename=/path/to/backup.xva

Import VM:

xe vm-import filename=/path/to/backup.xva

Monitoring and Diagnostics

Host information:

xe host-list params=all

Process monitoring:

top

Advanced process monitoring:

htop

Check memory usage:

free -h

Host free memory:

xe host-param-get uuid=<UUID_host> param-name=memory-free

CPU usage by virtual machines:

xe vm-list params=name-label,power-state,VCPUs-utilisation

View main XCP-ng log:

tail -f /var/log/xensource.log

System logs:

journalctl -xe

View system messages:

tail -f /var/log/messages

Xen logs:

xl dmesg

Create bug report (contains all diagnostic information):

xen-bugtool -y

Report Location

Result will be saved to /var/opt/xen/bug-report/

Managing ISO Images and CD Drives

List available ISO images:

xe cd-list

Detailed information about ISO in SR:

xe vdi-list sr-uuid= content-type=iso

Attach ISO to VM:

xe vm-cd-insert uuid= cd-name=".iso"

Eject ISO from VM:

xe vm-cd-eject uuid=

Check connected CD/ISO to VM:

xe vbd-list vm-uuid= type=CD

Navigate to ISO directory on host:

cd /opt/xensource/packages/iso

Download ISO from internet:

wget https://example.com/os.iso

Rescan SR after loading ISO:

xe sr-scan uuid=

Checking Guest Tools Status

Check PV drivers version:

xe vm-param-get uuid= param-name=PV-drivers-version

Check if PV drivers are up-to-date:

xe vm-param-get uuid= param-name=PV-drivers-up-to-date

Get guest OS information:

xe vm-param-get uuid= param-name=os-version

Check PV drivers detection:

xe vm-param-get uuid= param-name=PV-drivers-detected

Get VM network information:

xe vm-param-get uuid= param-name=networks

Common Issues and Solutions

Issue: VM Boots into Emergency/Recovery Mode

Symptoms:

Message appears "You are in emergency mode" or "Welcome to emergency mode";

Typical Causes:

  • Boot configuration errors (fstab for Linux);
  • Filesystem corruption;
  • Virtualization issues;
  • Incorrect VM shutdown.

Solution for Linux:

Log in to the system with root password (or press Ctrl+D to continue).

Check system logs:

journalctl -xb | grep -i error

Check kernel messages:

dmesg | grep -i error

Check filesystem:

cat /etc/fstab

Check disk usage:

df -h

Check block devices:

lsblk

If the issue is in fstab (e.g., missing swap or disk), edit the file:

nano /etc/fstab

Comment out the problematic line by adding # at the beginning. Example:

# /dev/mapper/almalinux-swap none swap defaults 0 0

If you need to check the filesystem, first unmount the partition:

umount /dev/xvda2

Check and repair filesystem:

fsck -y /dev/xvda2

Reboot system:

systemctl reboot

Issue: GRUB Doesn't Load or Hangs

Symptoms:

  • VM hangs on TianoCore (UEFI) screen;
  • "Welcome to GRUB" appears and nothing happens;
  • Black screen with cursor after BIOS/UEFI.

Typical Causes:

  • Incorrect boot order;
  • ISO still connected as first boot device;
  • GRUB bootloader corruption;
  • UEFI/BIOS incompatibility.

Solution 1: Check and Change Boot Order

On XCP-ng host check current boot order:

xe vm-param-get uuid=<UUID_VM> param-name=HVM-boot-params

Possible order values: - cdn - HDD ©, CD (d), Network (n) - dcn - CD (d), HDD ©, Network (n) - c - HDD only

For OS installation, set CD first:

xe vm-param-set uuid=<UUID_VM> HVM-boot-params:order=dcn

After OS installation, set boot from HDD only:

xe vm-param-set uuid=<UUID_VM> HVM-boot-params:order=c

Eject installation ISO if still connected:

xe vm-cd-eject uuid=<UUID_VM>

Reboot VM:

xe vm-reboot uuid=<UUID_VM> --force

Solution 2: Boot Through GRUB Rescue (for Linux)

If you end up in GRUB command line (grub> prompt appears), execute the following commands.

Find available partitions:

ls
Output will be something like: (hd0) (hd0,msdos2) (hd0,msdos1)

Find partition with /boot (usually msdos1 or gpt1):

ls (hd0,msdos1)/

Check boot contents:

ls (hd0,msdos1)/boot/

You should see vmlinuz, initramfs files and grub2 folder.

For BIOS systems execute:

set root=(hd0,msdos1)
set prefix=(hd0,msdos1)/grub2
insmod normal
normal

For UEFI systems execute:

set root=(hd0,gpt1)
set prefix=(hd0,gpt1)/boot/grub2
insmod normal
normal

After system boots, restore GRUB.

For RHEL-based (AlmaLinux, Rocky, CentOS):

sudo grub2-mkconfig -o /boot/grub2/grub.cfg

For UEFI systems:

sudo grub2-mkconfig -o /boot/efi/EFI/almalinux/grub.cfg

For Debian-based (Ubuntu, Debian):

sudo update-grub

Reinstall GRUB if needed (for BIOS):

sudo grub2-install /dev/xvda

Solution 3: Switching Between UEFI and BIOS

If issues persist, on XCP-ng host check current mode:

xe vm-param-get uuid=<UUID_VM> param-name=HVM-boot-params

Switch to BIOS (may require OS reinstallation):

xe vm-param-remove uuid=<UUID_VM> param-name=HVM-boot-params param-key=firmware

Or explicitly set BIOS:

xe vm-param-set uuid=<UUID_VM> HVM-boot-params:firmware=bios

Issue: Network Doesn't Work After Installation

Symptoms:

  • VM doesn't get IP address;
  • Network interface shows "disconnected" or "no carrier";
  • Ping doesn't work;
  • IP address not displayed in XCP-ng interface;

Typical Causes:

  • Guest Tools not installed (main cause);
  • Incorrect network configuration in VM;
  • Virtual network adapter issues;
  • Firewall blocking connection.

Solution:

  1. Install Guest Tools (see section above) - this will solve 90% of network issues

  2. Check network interface status in guest OS

    For Linux check interface state:

    ip link show
    

    Check IP addresses:

    ip addr show
    

    For systems with NetworkManager:

    nmcli device status
    

    Check connections:

    nmcli connection show
    

    For systems with systemd-networkd:

    networkctl status
    

    Check routing:

    ip route show
    

  3. Enable and configure interface

    For RHEL-based with NetworkManager enable interface:

    sudo nmcli device set eth0 managed yes
    

    Bring up connection:

    sudo nmcli connection up eth0
    

    Or restart NetworkManager:

    sudo systemctl restart NetworkManager
    

    For Debian-based check configuration (Ubuntu 18.04+):

    cat /etc/netplan/00-installer-config.yaml
    

    For Debian/old Ubuntu:

    cat /etc/network/interfaces
    

    Enable interface:

    sudo ip link set eth0 up
    

    Request IP via DHCP:

    sudo dhclient eth0
    

  4. Check XCP-ng settings

    On XCP-ng host check VM virtual network interfaces:

    xe vif-list vm-uuid=<UUID_VM>
    

    Check available networks:

    xe network-list
    

    If VIF is missing or incorrect, get network UUID:

    xe network-list name-label="Pool-wide network associated with eth0"
    

    Create new VIF:

    xe vif-create vm-uuid=<UUID_VM> network-uuid=<UUID_NETWORK> device=0
    

  5. Check firewall

    For Linux (firewalld) check status:

    sudo systemctl status firewalld
    

    Temporarily disable for testing:

    sudo systemctl stop firewalld
    

    For Linux (iptables) check rules:

    sudo iptables -L -n
    

    Temporarily clear rules for testing:

    sudo iptables -F
    

Issue: Very Slow OS Installation

Symptoms:

  • Installation takes several hours instead of 15-30 minutes;
  • Package copying is very slow;
  • VM hangs at "Installing packages" or "Configuring" stage.

Typical Causes:

  • Slow host disk subsystem (HDD instead of SSD);
  • Overloaded Storage Repository;
  • Insufficient VM resources (CPU, RAM);
  • Host performance issues.

Solutions:

  1. Use Minimal Install for Linux:

    • Minimal contains ~400-600 packages instead of 1000-1500 (Server with GUI);
    • Installation takes 5-10 minutes instead of hours;
    • For production servers, GUI is usually not needed;
    • You can install needed packages after installation.
  2. Temporarily increase VM resources

    On XCP-ng host (before starting or during installation) increase RAM:

    xe vm-param-set uuid=<UUID_VM> memory-static-max=8GiB memory-dynamic-max=8GiB
    

    Increase vCPU:

    xe vm-param-set uuid=<UUID_VM> VCPUs-max=4 VCPUs-at-startup=4
    

  3. Check disk performance

    On XCP-ng host check I/O:

    iostat -x 1
    

    Check disk load:

    iotop
    

    Check SR status:

    xe sr-list
    

    Get SR details:

    xe sr-param-list uuid=<UUID_SR>
    

  4. Use faster storage:

    • If multiple SRs are available, use SSD-based storage;
    • Consider migrating to another SR.

Issue: Cannot Connect ISO

Symptoms:

  • Error "The VM has no empty CD drive (VBD)";
  • Error "No matching VMs found";
  • ISO doesn't appear in available list.

Solution 1: VM has no empty CD drive

Check existing VBDs (Virtual Block Devices):

xe vbd-list vm-uuid=<UUID_VM>

If CD drive is occupied by another ISO, eject it:

xe vm-cd-eject uuid=<UUID_VM>

Now insert the needed ISO:

xe vm-cd-insert uuid=<UUID_VM> cd-name="guest-tools.iso"

If CD drive is completely absent, first find needed ISO UUID:

xe cd-list name-label="guest-tools.iso"

Create VBD manually:

xe vbd-create vm-uuid=<UUID_VM> vdi-uuid=<UUID_ISO> device=3 bootable=false mode=RO type=CD

Solution 2: No matching VMs found

Problem: using Control Domain UUID instead of VM.

Check VM list correctly (excluding Control Domain):

xe vm-list is-control-domain=false

Make sure you're using correct UUID by checking:

xe vm-param-list uuid=<UUID_VM> | grep "is-control-domain"

Should be: is-control-domain ( RO): false

Solution 3: ISO doesn't appear in list

Check that ISO is loaded:

xe cd-list

If ISO is not in list, find SR for ISO:

xe sr-list content-type=iso

Navigate to ISO directory:

cd /opt/xensource/packages/iso

Check file presence:

ls -lh

If file is missing, download from internet:

wget https://example.com/your-iso.iso

Or from local computer (execute on your PC):

scp /local/path/file.iso root@<IP-host>:/opt/xensource/packages/iso/

Rescan SR:

xe sr-scan uuid=<UUID_SR>

Check again:

xe cd-list

Issue: VM Doesn't Shutdown Properly

Symptoms:

  • xe vm-shutdown doesn't work or hangs
  • VM can only be shut down via --force
  • Timeout errors in logs

Causes:

  • Guest Tools not installed or not working
  • OS not responding to ACPI events
  • Stuck processes in guest OS

Solution:

  1. Install/check Guest Tools (main cause)

  2. Check Guest Tools status

    On XCP-ng host check PV drivers version:

    xe vm-param-get uuid=<UUID_VM> param-name=PV-drivers-version
    

    Check drivers currency:

    xe vm-param-get uuid=<UUID_VM> param-name=PV-drivers-up-to-date
    

  3. Use correct shutdown commands

    Soft shutdown (requires Guest Tools):

    xe vm-shutdown uuid=<UUID_VM>
    

    Forced shutdown (equivalent to pressing power button):

    xe vm-shutdown uuid=<UUID_VM> --force
    

Hard shutdown (equivalent to pulling power cord, use only as last resort):

xe vm-destroy uuid=<UUID_VM>

General Diagnostic Tips

When issues occur, always check logs.

In guest OS (Linux) check recent events:

journalctl -xe

Check kernel messages:

dmesg | tail -50

View system log (RHEL-based):

tail -f /var/log/messages

View system log (Debian-based):

tail -f /var/log/syslog

On XCP-ng host view main log:

tail -f /var/log/xensource.log

Check Xen hypervisor messages:

xl dmesg

Check system events:

journalctl -xe

Creating diagnostic report on XCP-ng host:

xen-bugtool -y

Result will be saved to /var/opt/xen/bug-report/

Note

Detailed information on XCP-ng configuration and administration is available in the official documentation.

Ordering a Server with XCP-ng via API

To install a server with RouterOS using the API, follow these instructions.


Some of the content on this page was created or translated using AI.

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×