Citrix Hypervisor / XenServer / XCP-ng

Agentless, image-based protection for virtual machines on Citrix Hypervisor 8.2 CU1, XenServer 8 and XCP-ng 8.2 / 8.3. NGBackup talks to the pool master through XAPI (the same management API XenCenter and Xen Orchestra use): nothing is installed in the guests or on the hosts. One FD plugin (xen-fd.so) plus one backend binary (xen-backend), written in Rust.

Capabilities

Snapshot-based backup of running or halted VMs. With quiesce=try (default) NGBackup asks XAPI for a quiesced snapshot and falls back to a crash-consistent snapshot when the host or guest cannot quiesce; quiesce=yes makes quiescing mandatory.
Full backups stream each disk through the XAPI export_raw_vdi handler as a raw image (or as VHD with format=vhd).
Incremental and Differential backups with Changed Block Tracking. NGBackup enables CBT on every disk automatically, asks XAPI for the 64 KiB blocks that changed since the previous backup (VDI.list_changed_blocks) and reads only those blocks over the XAPI NBD service. After each backup the snapshot data is released (VDI.data_destroy) and only the CBT metadata is kept as the next reference point, so no full snapshot stays on your storage between jobs.
Works without NBD too. When no pool network has the nbd or insecure_nbd purpose, changed blocks are taken from an export_raw_vdi stream: storage stays incremental, the whole disk is read over the network.
Automatic VM discovery by policy. Select VMs by name or glob (vm=), UUID (uuid=), name pattern (include= / exclude=), XenServer tag (tag=) or the whole pool (all=yes). The selection is evaluated on every run, so new VMs that match the policy are protected automatically.
Full VM definition captured with every backup: vCPU, memory, boot order and firmware (BIOS or UEFI, including NVRAM), platform flags, disk layout, CD drives, network interfaces with MAC and MTU, plus the XAPI export_metadata archive.
Full-VM restore: as a new VM or replacing the original (overwrite=yes), to the original or an alternate SR, host or pool, with network remapping and optional power-on. Full, Differential and Incremental backups are applied as one chain in a single restore.
File-level restore through Granular Restore: browse the guest filesystems (Linux ext2/3/4, Windows NTFS) of any Full or Incremental point and download individual files, without restoring the VM.
Secure by default: HTTPS with certificate verification, SHA-256 certificate pinning for self-signed pool certificates, NBD over TLS pinned to the certificate XAPI returns, and credentials kept in the encrypted secrets store.

Requirements

Citrix Hypervisor 8.2 CU1, XenServer 8, or XCP-ng 8.2 / 8.3.
A pool user with the Pool Admin role (or root). The plugin always talks to the pool master; if you point it at a pool member it follows the redirect to the master.
HTTPS access (TCP 443) from the backup client to the pool master and, for exports, to the host that serves each SR.
For efficient incrementals: a pool network with the nbd purpose (TLS) or insecure_nbd, and TCP 10809 reachable from the backup client:

xe network-param-add param-name=purpose param-key=nbd uuid=<network-uuid>

Free space on the backup client for restores: disks are composed in a staging directory before upload (zero-filled blocks are kept sparse).

Installation

Install the plugin on the client host that runs the jobs (any Linux client with network access to the pool), then restart the File Daemon so it loads the plugin:

install -m 0755 xen-backend /opt/backup/bin/xen-backend
install -m 0755 xen-fd.so   /opt/backup/plugins/xen-fd.so
systemctl restart ngbackup-fd

Credentials

Keep the pool password out of plain-text configuration:

In the Content (FileSet), reference a sealed secret: password=@secret:xen-pool1.
Or put the connection in /opt/backup/etc/xen.conf (mode 0640), where @secret: references are resolved with the client’s own secrets store:

printf '%s' 'the-pool-password' | backup-secrets set xen-pool1
cat > /opt/backup/etc/xen.conf <<'EOF'
host = xcp-master.example.com
user = root
password = @secret:xen-pool1
fingerprint = 3f:a1:...:9c
EOF

Or use passfile=/path (mode 0600, the first line is the password).

Values on the Plugin = line override xen.conf.

TLS verification

Setting	Behavior
default	Certificate chain and host name verified against the public CA bundle plus `ca_file=`
`fingerprint=<sha256>`	Accept exactly the pool certificate with this SHA-256 fingerprint (recommended for the default self-signed XenServer / XCP-ng certificates)
`tls_verify=no`	No verification (lab use; the job log warns)

Get the fingerprint on the pool master with openssl x509 -in /etc/xensource/xapi-ssl.pem -noout -fingerprint -sha256.

Configure

FileSet {
  Name = "xen-production"
  Include {
    Options { Signature = MD5 }
    Plugin = "xen: host=xcp-master.example.com user=root password=@secret:xen-pool1 \
              fingerprint=3f:a1:...:9c all=yes exclude=*-test"
  }
}

Job {
  Name = "backup-xen-production"
  Type = Backup
  Client = backup-proxy-fd
  FileSet = "xen-production"
  Schedule = "WeeklyCycle"
  Storage = dedup-store
  Pool = Daily
}

A weekly Full with daily Incrementals (or Differentials) is the typical schedule: every Incremental reads only the blocks changed since the previous backup.

Parameters

Parameter	Default	Meaning
`host`		Pool master (`name`, `name:port` or `https://name`)
`user` / `password` / `passfile`	`root`	XAPI credentials (see Credentials)
`config_file`	`/opt/backup/etc/xen.conf`	Connection file
`fingerprint` / `ca_file` / `tls_verify`	verify	TLS verification (see above)
`vm`		VM names or globs, comma separated or repeated
`uuid`		VM UUIDs
`include` / `exclude`		Name globs to add / remove (`exclude` also matches UUIDs)
`tag`		Protect VMs carrying any of these XenServer tags
`all`	`no`	Protect every VM in the pool
`power_state`	`any`	`running` or `halted` to filter
`quiesce`	`try`	`try`, `yes` or `no`
`cbt`	`yes`	`no` stores every disk in full on every level
`cbt_read`	`auto`	`nbd`, `export` or `auto` (NBD when available)
`format`	`raw`	`vhd` for Full-only VHD images
`export_metadata`	`yes`	Also store the XAPI metadata archive
`abort_on_error`	`no`	Stop the job at the first VM that fails
`timeout`	`3600`	Seconds allowed for each XAPI transfer

A VM that cannot be backed up (for example, a snapshot is refused) is named in the job log as a warning and the remaining VMs continue; the job fails if no VM could be backed up or with abort_on_error=yes.

List the VMs of a pool with ready-to-use plugin lines:

list pluginobjects client=backup-proxy-fd plugin=xen: config_file=/opt/backup/etc/xen.conf

Restore

Restore the latest point of a VM, applying the Full and every Incremental or Differential in one pass:

restore jobid=<last-job> chain=1 where=/ pluginoptions="xen: restore_name=web01-restored power_on=yes" yes

Restore option	Meaning
`restore_name`	Name of the restored VM. Default: the original name; when that name is taken and `overwrite` is not set, `(restored <jobid>)` is appended
`overwrite=yes`	Replace the existing VM. The new VM is built and imported first; only then is the old VM (with disks no other VM uses) removed and the new one renamed
`restore_sr`	Target SR (UUID or name) for every disk; default: the original SR when it exists, otherwise the pool default SR
`restore_host`	Host (UUID, name or address) to place and start the VM on
`restore_network` / `no_network=yes`	Network (UUID or name) for every interface, or no interfaces; default: the original network by UUID, then by name
`keep_mac`	`auto` (default) keeps MAC addresses when replacing the VM or when the original no longer exists; `yes` / `no` to force
`power_on=yes`	Start the VM after the restore
`restore_server` / `restore_user` / `restore_password`	Restore into another pool
`restore_staging` / `keep_staging=yes`	Staging directory on the client, and keep it after the restore

The restore job reports success only after every VM has been created and every disk import has been confirmed by XAPI. A VM whose restore fails is removed again (no half-restored VM is left behind) and the job fails with the reason.