XCP-ng¶
In this article
- XCP-ng. Key Features
- Getting Started with XCP-ng After Deployment
- Authorization
- Working with XO Lite
- Creating a Virtual Machine
- Installing XCP-ng Guest Tools
- Virtual Machine Management
- Working with Storage, ISO and Networks
- Common Issues and Solutions
- Basic CLI Commands
- Ordering a Server with XCP-ng via API
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 API — Invapi.
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
rootand the password from the email, then click theLoginbutton.
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:
- 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:

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
rootpassword; - 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.
Navigation in xsconsole¶
- 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:
-
Connect to the server via SSH
-
If the xsconsole opens after connection, exit to the regular command line by selecting the Local Command Shell menu item or pressing
Ctrl+C. -
Find the UUID of the ISO storage
Copy the UUID of the storage named "XCP-ng Tools". -
Navigate to the ISO storage directory
-
Download the ISO image
Download from the internet:
Or upload from local computer (execute on your PC)
-
Rescan the storage
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 VMbutton 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
Createbutton.
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:
Or get a list of all running VMs:
Eject the installation ISO (if connected):
Insert guest-tools ISO:
Verify that the ISO has been replaced:
Step 3: VM Reboot
- If you haven't rebooted after installation yet: In the VM console, press "Reboot System" or execute the
rebootcommand; - 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:
Mount guest-tools ISO:
If /dev/sr0 doesn't work, try alternative options:
or
Check contents:
Navigate to directory:
Run installation:
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:
Check service status:
Unmount ISO:
Reboot the system to apply changes:
For Linux (Debian-based: Ubuntu, Debian)¶
Log in to the system as root or use sudo.
Create mount point:
Mount guest-tools ISO:
Navigate to directory:
Run installation:
Verify installation:
Check service status:
Unmount ISO:
Reboot system:
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:
Install xe-guest-utilities:
Enable service:
Start service:
Check status:
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:
Check version:
On XCP-ng host check network information display:
Check PV drivers status:
Get general VM information:
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
Detailed information about specific SR View disk space usageWorking with ISO Storage:
Find ISO SR
Get path to ISO SR Navigate to ISO directory (usually /opt/xensource/packages/iso) View available ISOs Download ISO from internet Upload ISO from local computerAttention
You must rescan SR after adding ISO
Managing Local Storage¶
View virtual disks (VDI):
Check free space:
View snapshot list:
Delete snapshot:
Network Management¶
View all networks:
Detailed network information:
View physical interfaces (PIF):
Specific PIF details:
Check host IP address:
Create internal network:
Create VLAN network:
View VM network interfaces:
Create new network interface for VM:
Basic CLI Commands¶
Virtual Machine Management¶
List all VMs:
Only running VMs:
Detailed VM information:
Start VM:
Shutdown VM:
Reboot VM:
Suspend VM:
Force shutdown VM:
Create snapshot:
List snapshots:
Restore from snapshot:
Delete snapshot:
Export VM:
Import VM:
Monitoring and Diagnostics¶
Host information:
Process monitoring:
Advanced process monitoring:
Check memory usage:
Host free memory:
CPU usage by virtual machines:
View main XCP-ng log:
System logs:
View system messages:
Xen logs:
Create bug report (contains all diagnostic information):
Report Location
Result will be saved to /var/opt/xen/bug-report/
Managing ISO Images and CD Drives¶
List available ISO images:
Detailed information about ISO in SR:
Attach ISO to VM:
Eject ISO from VM:
Check connected CD/ISO to VM:
Navigate to ISO directory on host:
Download ISO from internet:
Rescan SR after loading ISO:
Checking Guest Tools Status¶
Check PV drivers version:
Check if PV drivers are up-to-date:
Get guest OS information:
Check PV drivers detection:
Get VM network information:
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:
Check kernel messages:
Check filesystem:
Check disk usage:
Check block devices:
If the issue is in fstab (e.g., missing swap or disk), edit the file:
Comment out the problematic line by adding # at the beginning. Example:
If you need to check the filesystem, first unmount the partition:
Check and repair filesystem:
Reboot system:
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:
Possible order values: - cdn - HDD ©, CD (d), Network (n) - dcn - CD (d), HDD ©, Network (n) - c - HDD only
For OS installation, set CD first:
After OS installation, set boot from HDD only:
Eject installation ISO if still connected:
Reboot VM:
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:
Output will be something like:(hd0) (hd0,msdos2) (hd0,msdos1) Find partition with /boot (usually msdos1 or gpt1):
Check boot contents:
You should see vmlinuz, initramfs files and grub2 folder.
For BIOS systems execute:
For UEFI systems execute:
After system boots, restore GRUB.
For RHEL-based (AlmaLinux, Rocky, CentOS):
For UEFI systems:
For Debian-based (Ubuntu, Debian):
Reinstall GRUB if needed (for BIOS):
Solution 3: Switching Between UEFI and BIOS
If issues persist, on XCP-ng host check current mode:
Switch to BIOS (may require OS reinstallation):
Or explicitly set 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:
-
Install Guest Tools (see section above) - this will solve 90% of network issues
-
Check network interface status in guest OS
For Linux check interface state:
Check IP addresses:
For systems with NetworkManager:
Check connections:
For systems with systemd-networkd:
Check routing:
-
Enable and configure interface
For RHEL-based with NetworkManager enable interface:
Bring up connection:
Or restart NetworkManager:
For Debian-based check configuration (Ubuntu 18.04+):
For Debian/old Ubuntu:
Enable interface:
Request IP via DHCP:
-
Check XCP-ng settings
On XCP-ng host check VM virtual network interfaces:
Check available networks:
If VIF is missing or incorrect, get network UUID:
Create new VIF:
-
Check firewall
For Linux (firewalld) check status:
Temporarily disable for testing:
For Linux (iptables) check rules:
Temporarily clear rules for testing:
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:
-
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.
-
Temporarily increase VM resources
On XCP-ng host (before starting or during installation) increase RAM:
Increase vCPU:
-
Check disk performance
On XCP-ng host check I/O:
Check disk load:
Check SR status:
Get SR details:
-
Use faster storage:
- If multiple SRs are available, use
SSD-based storage; - Consider migrating to another SR.
- If multiple SRs are available, use
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):
If CD drive is occupied by another ISO, eject it:
Now insert the needed ISO:
If CD drive is completely absent, first find needed ISO UUID:
Create VBD manually:
Solution 2: No matching VMs found
Problem: using Control Domain UUID instead of VM.
Check VM list correctly (excluding Control Domain):
Make sure you're using correct UUID by checking:
Should be: is-control-domain ( RO): false
Solution 3: ISO doesn't appear in list
Check that ISO is loaded:
If ISO is not in list, find SR for ISO:
Navigate to ISO directory:
Check file presence:
If file is missing, download from internet:
Or from local computer (execute on your PC):
Rescan SR:
Check again:
Issue: VM Doesn't Shutdown Properly¶
Symptoms:
xe vm-shutdowndoesn'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:
-
Install/check Guest Tools (main cause)
-
Check Guest Tools status
On XCP-ng host check PV drivers version:
Check drivers currency:
-
Use correct shutdown commands
Soft shutdown (requires Guest Tools):
Forced shutdown (equivalent to pressing power button):
Hard shutdown (equivalent to pulling power cord, use only as last resort):
General Diagnostic Tips
When issues occur, always check logs.
In guest OS (Linux) check recent events:
Check kernel messages:
View system log (RHEL-based):
View system log (Debian-based):
On XCP-ng host view main log:
Check Xen hypervisor messages:
Check system events:
Creating diagnostic report on XCP-ng host:
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.