> For the complete documentation index, see [llms.txt](https://docs.storware.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.storware.eu/protecting-virtual-machines/virtual-machines/citrix-hypervisor-xenserver.md). # Citrix Hypervisor and XCP-ng ## Ovierview Storware Backup & Recovery protects virtual machines running on Citrix Hypervisor (XenServer) and XCP-ng using two backup strategies: **VM image (full) + separate disks (incremental)** and **Separate disks (full/incremental) + Changed Block Tracking (incremental)**. Use a hypervisor version supported by your Storware Backup & Recovery release. Availability of the CBT feature on a hypervisor does not, by itself, indicate that its version is supported by Storware. ### Supported versions **Recommended strategy: Separate disks (full/incremental) + Changed Block Tracking (incremental)**
VM image (full) + separate disks (incremental)Separate disks (full/incremental) + Changed Block Tracking (incremental).
Supported versions of Citrix Hypervisor8.48.4
Supported version of XCP-ng8.38.3
The last snapshot is kept on the hypervisor for incremental backupsYesYes
Access to hypervisor OS requiredNoYes
Proxy VM requiredNoNo
Full backupSupportedSupported
Incremental backupSupported (non-synthetic backup destination only)Supported
Synthetic backupsNot supportedSupported
Secondary backup destinationSupported (only for a full backup)Supported
File-level restoreNot supportedSupported
VM disk exclusionNot supportedSupported
Quiesced snapshotsSupportedSupported
Snapshots managementSupportedSupported
Pre/post command executionSupportedSupported
Access to VM disk backup over iSCSINot supportedSupported
VM name-based policy assignmentSupportedSupported
VM tag-based policy assignmentSupportedSupported
Power-on VM after restoreSupportedSupported
### Backup Strategies #### VM image (full) + separate disks (incremental) This is the default strategy. Full backups contain the VM configuration and disk data in a single XVA bundle. Incremental backups contain separate VHD delta files for the VM disks. Both types of backup transfer data directly over HTTPS using the hypervisor API; NBD is not required. Although the backup type is called *incremental* in Storware Backup & Recovery, each XVA incremental backup contains changes relative to the **last full backup**. These backups are therefore cumulative, or differential, rather than a chain of changes relative to the previous incremental backup. **Backup Process** 1. For a full backup, Storware Backup & Recovery creates a VM snapshot using the hypervisor API. 2. The snapshot is exported as an XVA bundle containing VM metadata and disk data. XVA compression is controlled by the Node settings and is enabled by default. 3. If at least one schedule assigned to the VM uses incremental backups, the full-backup snapshot is retained as the baseline. 4. For subsequent incremental backups, the disks are exported as VHD deltas relative to that baseline. The strategy does not create a new VM snapshot for each incremental export. **Restore Process** Storware Backup & Recovery imports the full XVA and applies the VHD delta data required for the selected restore point. If the import creates a template object, it is converted into a VM. The restored VM receives the requested name, and its network interfaces can be mapped to target networks. The result is a **virtual machine**, not a template. #### **Separate disks (full/incremental) + Changed Block Tracking (incremental)** This strategy stores VM metadata separately from disk data and supports excluding individual disks. Full backups export each included disk as RAW over HTTPS. Incremental backups use the hypervisor's changed-block information and read only the changed blocks through TLS-protected NBD connections. Each incremental backup depends on the **previous backup**, forming a chain from the full backup to the selected restore point. For full backups only, this strategy does not require CBT tracking or NBD data transfer on the hypervisor. **Backup Process** 1. Storware Backup & Recovery creates a VM snapshot using the hypervisor API. 2. When initializing incremental protection, it checks CBT availability and initializes tracking for each included disk. If CBT is already enabled, it is disabled and enabled again. 3. For a full backup, VM metadata is exported as OVF and each included disk is exported separately as RAW over HTTPS. 4. For an incremental backup, the previous and current snapshots are used to identify changed blocks. Storware Backup & Recovery saves the changed-block map and reads the corresponding data over TLS NBD. 5. When incremental backups are configured, the latest snapshot is retained as the reference for the next backup. {% hint style="info" %} **Important:** Initializing incremental protection resets CBT on the included disks. This can affect tracking used by other backup tools protecting the same disks. Coordinate their use before enabling CBT protection. {% endhint %} Excluded disks are represented by metadata placeholders; their contents are not backed up. **Restore Process** Storware Backup & Recovery merges the full backup and the required incremental data locally on the Node to reconstruct each disk at the selected restore point. It then creates virtual disks in the selected storage repositories, imports their RAW data over HTTPS, and imports the VM metadata with the corresponding disk mappings. Individual disks can also be excluded during restore. ### Backup Consistency Where a backup operation creates a VM snapshot, the default snapshot is crash-consistent. Quiesced snapshots can be requested when the corresponding option is enabled and the required guest tools are installed and operational. For specific supported quiescing errors, Storware Backup & Recovery falls back to a regular snapshot. Other errors may cause the backup to fail; fallback is not guaranteed for every quiescing failure. Application consistency can also be coordinated using pre- and post-snapshot commands. The commands must be appropriate for the application and complete successfully. These snapshot options apply to operations that create snapshots. XVA incremental exports do not create a new VM snapshot for each backup. ### CBT Configuration CBT incremental backups require: * CBT availability on the hypervisor, including any applicable licensing requirements. * An NBD-enabled network accessible from the Node. * An NBD client and the Linux NBD kernel module on the Node. * Available `/dev/nbd*` devices for NBD connections. Licensing and feature availability differ between XenServer and XCP-ng. Use the requirements applicable to the supported platform and release in your environment. #### Enable NBD on the Hypervisor Administrative access to the hypervisor is required for this configuration. Routine backup and restore operations use the API and, for CBT incrementals, NBD; the Node does not require an SSH session to transfer backup data. 1. On the hypervisor, list the networks: ```bash xe network-list ``` 2. Identify the UUID of the network to use for NBD traffic. Ensure that the Node can reach the host addresses on this network. 3. Enable NBD on the selected network, replacing `` with its UUID: ```bash xe network-param-add uuid= param-name=purpose param-key=nbd ``` 4. Verify that the required hosts expose reachable NBD endpoints on the selected network. #### Verify NBD on the Node Use the Node installation and configuration procedure for your supported operating system. NBD client provisioning is handled by the Node packages and configuration process: * On RHEL-family systems covered by the Node configuration script, the script checks for `nbd-client` and builds it from the supplied sources if necessary. It also attempts to load the NBD kernel module and configures it to load at startup. * DEB packages declare `nbd-client` as a dependency. The running kernel must also provide a usable NBD module. Do not use the legacy CentOS 7 RPM or the prebuilt kernel module from the old installation procedure on newer Node operating systems. Run the following checks on the Node: ```bash command -v nbd-client ``` As root, verify that the module can be loaded: ```bash modprobe nbd ``` Verify that NBD devices are available: ```bash ls /dev/nbd* ``` If the client is missing, the module cannot be loaded, or no NBD devices are available, resolve the Node installation or kernel compatibility issue before running CBT incremental backups. Use a module compatible with the running kernel. The available NBD devices limit the number of simultaneous NBD connections. Account for concurrent backup tasks when sizing the Node configuration. ### Network Requirements The following connections originate from the Storware Backup & Recovery Node: | Destination | Protocol / port | Purpose | | ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Pool master and required pool hosts | HTTPS / TCP 443 | Inventory, authentication, snapshot management, and other XenAPI operations | | Hosts serving backup and restore transfers | HTTPS / TCP 443 | XVA full backups, XVA incremental VHD exports, CBT full RAW exports, metadata transfers, and restore imports | | NBD endpoints returned by XenAPI | TLS NBD / TCP port returned by XenAPI | Reading changed disk blocks during CBT incremental backups | Allow connections to all required host and transfer addresses, not only the initially configured pool address. HTTPS carries both management operations and backup or restore data. For NBD, Storware Backup & Recovery uses the address, port, and TLS information supplied by XenAPI. Configure firewall rules for those endpoints instead of assuming a fixed NBD port for every environment. ### Restore Considerations * **XVA backups:** Restore produces a VM, converting an imported template object when necessary. Network interfaces can be mapped to target networks. * **CBT backups, original VM still present:** The VM is restored as a new VM, with newly generated MAC addresses. * **CBT backups, original VM absent:** Storware Backup & Recovery attempts to preserve the original VM identity and configuration, including MAC addresses. * **Inventory accuracy:** Ensure that all pool hosts are configured and that VM availability information is current before relying on original-identity restore behavior. * **Excluded disks:** Disk contents omitted from a backup cannot be recovered from that backup. * **Retained snapshots:** Snapshots retained as backup references are required for subsequent incremental backups. Do not remove them manually while the corresponding incremental protection is in use. ## Protecting Citrix Hypervisor / XCP-ng ### Prerequisites * Configure **all hosts in the pool**, including the pool master, in Storware Backup & Recovery. Missing hosts can prevent connections to the pool master or cause incorrect VM availability information during inventory synchronization. * Ensure that the assigned Storware Backup & Recovery Node can resolve and reach every required pool host, including addresses used for data transfer. * Configure credentials with permissions to discover VMs, manage snapshots, and export backup data. Restore operations also require permissions to create and import VMs and virtual disks. * Ensure that HTTPS connections and, when used, NBD TLS connections can be established successfully with the certificates provided by the hypervisor. * For CBT incremental backups, enable the hypervisor NBD service and verify NBD availability on the Node as described below. CBT must be available for the hypervisor edition and license in use. If a dedicated transfer NIC is configured, its addresses must be reachable from the Node. Access to the management address alone may not be sufficient for data transfer. ### Adding hypervisor Before adding the environment, complete the requirements described in **Prerequisites**. For CBT incremental backups, also complete **CBT Configuration**. 1. Go to **Virtual Environments → Infrastructure → Hypervisors** and click **Add Hypervisor**. 2. Select **Citrix Hypervisor (XenServer) / XCP-ng** as the platform type. 3. Provide the host connection details: * Hostname or IP address reachable from the Node. * Username and password with the required hypervisor permissions. * Node configuration to use for backup and restore operations. 4. Select the backup strategy: * **VM image (full) + separate disks (incremental)** * **Separate disks (full/incremental) + Changed Block Tracking (incremental)** 5. If a dedicated network is used for data transfer, configure **Transfer NIC** in the hypervisor settings. For CBT incremental backups, the NBD endpoint is supplied by the hypervisor and is not controlled by this setting. 6. Save the configuration and repeat the procedure for **every host in the pool, including the pool master**. Adding only the master is insufficient. 7. Run **Inventory Synchronization**. Verify that the expected VMs, hosts, and storage repositories are discovered and that the VMs are shown as present. 8. Create or select a backup policy, configure its backup destination, retention, and schedules, and assign the VMs to be protected. 9. Run an initial full backup. If incremental backups are configured, run an incremental backup after the full backup completes. Perform a test restore to verify the configuration. ## Limitations * VM migration between clusters is not supported. * Cloning a VM to another cluster is not supported. * XVA backups do not support individual disk exclusion or file-level restore. * CBT incremental backups require working CBT and NBD access; full RAW exports alone do not verify that incremental backups will work. * Backup destination capabilities can further restrict available backup and restore operations. Verify compatibility for the selected strategy and destination type.