vagrant-xapi 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b665195065d9fd736cebdd45799af247bfef431d9a727ac5345a3231cb14d1b7
-  data.tar.gz: 1d828520cad20e7273e4cc46bb096c2d42b53be7f98b010071538242470fde3f
+  metadata.gz: a2972d8295d44e74480cd9a521aaee0347efe2198c0bbaac979b6ef5dadd54a8
+  data.tar.gz: c67899b85bcee85063cac86e678bc53c7fdc73b18efd8fe2228b6e8cd78638dd
 SHA512:
-  metadata.gz: 0c7e262ed79ac66a8c2c9ecd834f007f88f5f46724943ba4c9fcb2e3252b133e2efa90e236ca68c6799a81e2a45b672cd7e7da4729a2766c829fccf7815ac5c6
-  data.tar.gz: f6a5720932d74e45ffe8b2ffe3a9ca66bc05820db871b9c34f095b51c3eafc22261d6d40ad94284cb00ad1d5734a8562c9f3abec42b6f60b2ba8be4213e52c89
+  metadata.gz: 7eb3f9724b380016e93ced343b0ef11561ec7d934e8d45db2eaeba2632c8191f7cc083835359500c94e953a7127e786eb7ffc25e75efb86a5e68f56f00299f7e
+  data.tar.gz: 7559cf78e3888f431117ce29b0ec503a260e685554c2e29fcba2eda398f94c332dac18021755e6a4f38a45300babd5de977fda8b9aeb8e1a42a0f0b2b040af70

data/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 1.0.0 (2026-11-09)
+
+First version, published on rubygems.org: `vagrant plugin install
+vagrant-xapi`.
+
+- XAPI client over JSON-RPC without runtime gems: TLS with CA or SHA-256
+  fingerprint pin, redirect to the pool master, one shared session per
+  process, long operations as tasks via `event.from`, streaming transfers with
+  the session as cookie, secrets filtered from logs and errors. Waiting for
+  a task survives a connection loss of up to a minute, and a transfer logs
+  in again when the session expired.
+- Box templates imported once per box and SR, under a pool-wide lock; `xapi`,
+  `xenserver` and `libvirt` boxes (XVA, `xva_url`, VHD, qcow2, raw).
+- All Vagrant actions: `up`, `halt`, `reload`, `suspend`, `resume`,
+  `destroy`, `provision`, `ssh`, `ssh_run`, `package` (XVA, VHD, qcow2) and
+  snapshots (including memory, push and pop). On a machine that was never
+  created they do not connect to the pool. `package` fails with bsdtar's
+  message when compressing the box fails, instead of leaving a truncated box,
+  and when the export fails on the host or its download ends early.
+  `resume` keeps a machine on an internal network on the host of its peers,
+  like `up`.
+- CPUs, memory, BIOS/UEFI, Secure Boot, vTPM, SR choice, fast or full clones,
+  affinity host. Turning `vtpm` off, or moving to `:bios`, removes the vTPM
+  the plugin created and Secure Boot on the next `reload`.
+- Networks on existing pool networks (by name, UUID or bridge; the default
+  network also from `VAGRANT_XAPI_DEFAULT_NETWORK`), internal networks for
+  `private_network`, static IPs, IP detection from guest metrics, cloud-init
+  or HIMN, SSH via dom0, port forwarding through SSH tunnels. A network that
+  does not resolve on `reload` leaves the VM's network interfaces and MACs
+  as they were.
+- `config.vm.disk` (extra disks, growing the primary disk, images, ISOs),
+  ISOs from ISO SRs through the `isos` option, and `config.vm.cloud_init`
+  with `network-config`. CD drives only go in the device slots 0-3 that a
+  guest sees; an uploaded ISO without a free slot becomes a read-only disk.
+- Synced folders with rsync, NFS or SMB; rsync is the default unless the
+  Vagrantfile sets `config.vm.allowed_synced_folder_types` (Vagrant would
+  otherwise pick SMB on macOS and Windows and ask for credentials).
+- `vagrant xapi info`, `console`, `adopt`, `templates`, `orphans`,
+  `marked` (everything the plugin created, optionally only your own), and
+  `hosts` (the pool's hosts with their certificate fingerprints). `adopt`
+  without `--force` only takes VMs of the same Vagrant installation.
+- `vagrant xapi diff`: which files were added, changed or removed since a
+  snapshot (`--from`), between two snapshots (`--to`) or between two running
+  machines (`--with`), with `--path`, `--exclude`, `--checksum`, `--plain` and
+  `--json`, and with `--content` what changed in them (unified diff, up to
+  `--content-limit` per file and 16 MiB per side, or the limit when that is
+  larger). By default `/tmp`, `/var/tmp`, `/var/cache`, `/var/log`, the
+  systemd random seed and `/usr/src` are left out (`--no-default-excludes`
+  compares them too); an `--exclude` without a leading `/` matches at any
+  depth, and `.` and `..` in a `--path` are resolved. Symlinks are compared
+  as links, also when a `--path` goes through one. Of two file systems on one
+  mount point only the visible one is compared. The roots of the file systems
+  are compared too; a file system that only one side has is named and not
+  compared, also a mount point that only one machine of `--with` has; a
+  listing that is cut off stops the run. Snapshot disks are read through
+  throwaway clones mounted read-only in the guest itself, while a temporary
+  udev rule keeps udev and systemd on the guest's own disks; disks left by an
+  interrupted run are removed by the next diff, before the VM boots, before
+  `package` (which stop when one cannot be removed) and on `destroy`, and its
+  mounts and directories in the guest by the next diff (only directories owned
+  by root or the SSH user). LVM works: the copy gets identifiers and a VG name
+  of its own (`vgimportclone`, limited to the copy's devices, without metadata
+  backups), so the guest's own volume groups are never touched.
+- `tls_fingerprint` takes several pins (the certificates of all hosts), so
+  any host of the pool can be `host`, also after the master changed.
+- `VAGRANT_XAPI_TLS_FINGERPRINT` and `VAGRANT_XAPI_TLS_CA_FILE` set the TLS
+  options from the environment.
+- Vagrantfiles of vagrant-xenserver keep working: the provider `:xenserver`
+  with its `xs_*` options, takeover of machines it created, its `destroy`
+  that removes all of the VM's own disks, and `vagrant xapi migrate` to move
+  machines to `:xapi`.
+- Templates made from a disk image (libvirt, qcow2, raw, VHD boxes) get 1 GiB
+  of memory instead of the 256 MiB of "Other install media"; under UEFI GRUB
+  could not load the initramfs with that.
+- `vagrant xapi console` asks viewers for a one-time VNC password and puts
+  it in the URL it opens, so macOS Screen Sharing connects without asking
+  and other local users cannot connect to the forwarded console.
+- Temporary: a stand-in for `XenApi::Client` of the `xenapi` gem, for
+  triggers in those Vagrantfiles that `require "xenapi"`. It says so when
+  used and will be removed in a later major release. With vagrant-xenserver
+  installed too, `require "xenapi"` loads the real gem.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exonet B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,6 +1,462 @@
-# vagrant-xapi (placeholder)
+# vagrant-xapi
 
-This version reserves the name `vagrant-xapi` for Exonet B.V. It contains no
-Vagrant plugin. If you installed it, remove it again:
+A [Vagrant](https://www.vagrantup.com) provider for **XenServer 8** and **XCP-ng 8.3**.
+It talks to XAPI directly over JSON-RPC and has no runtime gem dependencies.
+It needs no Xen Orchestra.
 
-    vagrant plugin uninstall vagrant-xapi
+The provider is called `:xapi`. It replaces
+[vagrant-xenserver](https://github.com/xapi-project/vagrant-xenserver) and
+supports every action and provider capability Vagrant core asks for.
+Vagrantfiles written for vagrant-xenserver keep working unchanged (see
+[Migrating from vagrant-xenserver](#migrating-from-vagrant-xenserver)).
+
+| Area | What works |
+| --- | --- |
+| Lifecycle | `up`, `halt` (graceful, then clean, then hard), `reload` (re-applies CPU, memory, firmware, VIFs, disks), `suspend`, `resume`, `destroy`, `provision`, `ssh`, `ssh_run` |
+| Boxes | `xapi` boxes (XVA, VHD, qcow2, raw), boxes of vagrant-xenserver (XVA, VHD, `xva_url`), and `libvirt` boxes (qcow2) |
+| VM | `cpus`, `cores_per_socket`, `memory`, `memory_dynamic_min`, BIOS/UEFI, Secure Boot, vTPM, `affinity_host`, tags |
+| Storage | `sr`, `template_sr`, a different SR per disk, fast (copy-on-write) or full clones |
+| Networks | `public_network` and `private_network` on existing networks (name, UUID or bridge), internal networks for `private_network`, static IPs, `forwarded_port` via SSH tunnels, `vagrant port` |
+| Disks | `config.vm.disk`: extra disks, growing the primary disk, disk images, ISOs |
+| cloud-init | `config.vm.cloud_init`, plus a `network-config` for a static IP on the first network |
+| Snapshots | `save`, `restore`, `delete`, `list`, `push`, `pop`, optionally with memory |
+| Package | `vagrant package` as XVA, VHD or qcow2 |
+| Synced folders | rsync (the default), NFS and SMB |
+| Extra | `vagrant xapi info`, `console`, `adopt`, `templates`, `orphans`, `marked`, `hosts`, `diff` |
+
+## Requirements
+
+- Vagrant 2.4.x (Ruby 3.0 to 3.4, as Vagrant's gemspec requires).
+- XenServer 8 or XCP-ng 8.3. Only the current releases are supported.
+- A box with a guest agent (xe-guest-utilities or xen-guest-agent), **or**
+  cloud-init and a static IP on the first network. XAPI has no DHCP of its own.
+- On the machine that runs Vagrant ("local machine" below: a workstation,
+  a build server or a CI runner): `ssh`; `qemu-img` only for qcow2 boxes
+  that the host cannot import itself (no qcow2 support, or compressed
+  clusters, which most cloud images and many libvirt boxes use); `rsync` if
+  you use rsync synced folders.
+
+## Install
+
+From [rubygems.org](https://rubygems.org/gems/vagrant-xapi):
+
+```sh
+vagrant plugin install vagrant-xapi
+vagrant plugin update vagrant-xapi   # later, to update
+```
+
+From a checkout (the repository is private):
+
+```sh
+git clone https://github.com/exonet/vagrant-xapi.git
+cd vagrant-xapi
+gem build vagrant-xapi.gemspec
+vagrant plugin install ./vagrant-xapi-1.0.0.gem
+```
+
+## Quick start
+
+Only `host`, `username` and `password` are required. All three can come
+from environment variables, so they never end up in a Vagrantfile in git:
+
+```sh
+export VAGRANT_XAPI_HOST=xcp-master.example.com
+export VAGRANT_XAPI_USERNAME=root
+export VAGRANT_XAPI_PASSWORD='...'
+```
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "acme/debian-12"
+  # XenServer and XCP-ng only run amd64 guests. Without this, Vagrant on an
+  # Mac with Apple silicon looks for an arm64 box.
+  config.vm.box_architecture = "amd64"
+
+  config.vm.provider :xapi do |xapi|
+    xapi.cpus = 2
+    xapi.memory = 2048
+  end
+end
+```
+
+```sh
+vagrant up --provider=xapi
+```
+
+The provider is never picked as the default by accident: Vagrant only
+chooses it when the Vagrantfile has a `config.vm.provider :xapi` block or
+you pass `--provider=xapi`.
+
+## Provider options
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | String | `VAGRANT_XAPI_HOST` | Pool master or standalone host. A pool member works too: the plugin follows `HOST_IS_SLAVE` to the master. |
+| `port` | Integer | 443 | HTTPS port |
+| `username` | String | `VAGRANT_XAPI_USERNAME` | XAPI user (root, local or AD with an RBAC role) |
+| `password` | String | `VAGRANT_XAPI_PASSWORD` | Never logged or shown in errors |
+| `tls_verify` | Boolean | true | Cannot be turned off; see TLS below |
+| `tls_ca_file` | String | `VAGRANT_XAPI_TLS_CA_FILE` | Your own CA bundle |
+| `tls_fingerprint` | String, Array | `VAGRANT_XAPI_TLS_FINGERPRINT` | SHA-256 pin of the host certificate, with or without colons; replaces the CA check for self-signed certificates. Several pins (a list, or separated by commas) for the certificates of all hosts of the pool, so any host can be `host`: `vagrant xapi hosts` shows them |
+| `api_timeout` | Integer (s) | 60 | Timeout per API call |
+| `task_timeout` | Integer (s) | 3600 | Timeout for imports, exports and copies |
+| `name_label` | String | `<project dir>_<machine>` | VM name in XAPI |
+| `cpus` | Integer | from template | `VCPUs_max` and `VCPUs_at_startup` |
+| `cores_per_socket` | Integer | from template | Must divide `cpus` (or, without `cpus`, the template's vCPUs) |
+| `memory` | Integer (MiB) | from template | Static and dynamic maximum. Templates the plugin makes from a disk image (libvirt, qcow2, raw, VHD) have 1024, instead of the 256 of XAPI's "Other install media" |
+| `memory_dynamic_min` | Integer (MiB) | `memory` | Lower bound for ballooning |
+| `firmware` | `:bios`, `:uefi` | from template | |
+| `secure_boot` | Boolean | false | Only with `:uefi`; with `:bios` it is turned off |
+| `vtpm` | Boolean | false | Only with `:uefi`, and when the pool supports vTPM. Turned off, `vagrant reload` removes the vTPM the plugin created, with its contents; a vTPM that came with the box or an adopted VM stays |
+| `sr` | String | pool default SR | Name or UUID; target for VM disks |
+| `template_sr` | String | `sr` | SR that holds the box template |
+| `clone_mode` | `:fast`, `:full` | `:fast` | `VM.clone` (copy-on-write, same SR as the template) or `VM.copy` (full copy to `sr`) |
+| `affinity_host` | String | nil | Name or UUID of the preferred host |
+| `default_network` | String | `VAGRANT_XAPI_DEFAULT_NETWORK`, else the master's management network | Network (name, UUID or bridge) of the first VIF when the Vagrantfile names no `public_network` |
+| `ip_detection` | Array | `[:guest_metrics, :static, :himn]` | Order of IP sources, see below |
+| `ssh_via_host` | Boolean | false | SSH to the guest through dom0 (ProxyCommand) |
+| `host_ssh_user` | String | `root` | dom0 user for `ssh_via_host` and `:himn` |
+| `shutdown_timeout` | Integer (s) | 120 | After this, `hard_shutdown` |
+| `xva_url` | String | nil | Let the host download the XVA itself (usually in a box's Vagrantfile) |
+| `isos` | Array | `[]` | ISOs on an ISO SR (name or UUID) to attach as CD drives |
+| `tags` | Array | `[]` | Extra XAPI tags |
+| `platform` | Hash | `{}` | Extra `platform` keys, as an escape hatch |
+| `other_config` | Hash | `{}` | Extra `other_config` keys; `vagrant-xapi.*` is reserved |
+| `forward_ssh_port` | Boolean | false | Also tunnel Vagrant's default 2222 → 22 forward |
+| `snapshot_memory` | Boolean | false | `snapshot save` of a running VM includes memory (checkpoint) |
+| `package_format` | `:xva`, `:vhd`, `:qcow2` | `:xva` | Format of `vagrant package` |
+
+Validation runs without a connection. Names of SRs, networks and hosts are
+looked up at `vagrant up`.
+
+## Boxes
+
+The provider accepts three kinds of boxes and imports each box **once per
+SR** as an XAPI template named `vagrant-xapi: <box> <version>`. Every VM is a
+clone (or copy) of that template. Templates are shared by all users of a
+pool; an import runs under a pool-wide lock, so two people running
+`vagrant up` with the same new box get one template.
+
+| Box provider | Content |
+| --- | --- |
+| `xapi` | `metadata.json` with `provider`, `format` (`xva`, `vhd`, `qcow2` or `raw`) and `architecture: "amd64"`; one file `box.<format>`; optionally a Vagrantfile with provider defaults such as `firmware` |
+| `xenserver` | A box of vagrant-xenserver: `box.xva`, `box.vhd`, or only a Vagrantfile with `xva_url` |
+| `libvirt` | `box.img` (qcow2), or several disks in the newer libvirt format |
+
+qcow2 is imported directly when the host supports it and the image has no
+compressed clusters (XAPI's qcow2 import cannot read those); otherwise the
+plugin converts it with `qemu-img convert -f qcow2 -O vpc` on the local
+machine. Files a box names must lie inside the box, and qcow2 images with a backing file are refused.
+
+A minimal `xapi` box:
+
+```sh
+echo '{"provider":"xapi","format":"xva","architecture":"amd64"}' > metadata.json
+cp my-vm.xva box.xva
+tar czf my.box metadata.json box.xva
+vagrant box add --architecture amd64 --name my/box my.box
+```
+
+`vagrant package` makes such a box from a VM: the VM is halted, a temporary
+clone is stripped of everything that belongs to this pool (VIFs, our
+markings, ISOs), exported, and removed again. Cleaning the guest for
+publication (SSH host keys, machine-id) is up to you, as with other providers.
+
+## Networks
+
+XAPI has no NAT and no DHCP. Every VIF hangs on a real network of the pool,
+the IP comes from the guest, and port forwarding runs over SSH tunnels.
+
+- The first `public_network` becomes VIF device 0. Without one, device 0 is a
+  VIF on `default_network` (or `VAGRANT_XAPI_DEFAULT_NETWORK`). Then the
+  other networks follow in Vagrantfile order. `reload` rebuilds the VIFs (MAC
+  addresses are kept per device).
+- `public_network` / `private_network` with `network:` (name, UUID or bridge)
+  or `bridge:` (e.g. `xenbr0`) use an existing network. Options: `mac:`, `mtu:`,
+  `ip:` (IPv4 or IPv6) with `netmask:` and `gateway:` for a static address,
+  `nameservers:` (for the first network), `xapi__locking_mode:`.
+- `private_network` without `network:` becomes an **internal network** (no
+  PIF), created when missing, marked with the project, and removed with the
+  last VM that uses it. `ip:` is required. An internal network only exists
+  per host, so all VMs of a project on it run on the same host (the host of
+  a VM that already runs on it). A name that belongs to another project is
+  refused.
+- Static addresses on device 0 are set through cloud-init (`network-config`
+  in the config drive); others through Vagrant's `configure_networks` guest
+  capability after boot.
+
+### IP detection
+
+`ip_detection` sets the order of sources; waiting stops after
+`config.vm.boot_timeout`.
+
+1. `:guest_metrics`: `<device>/ipv4/0` of VIF 0 from the guest agent.
+2. `:static`: the `ip:` of the first network.
+3. `:himn`: an extra VIF on the host internal management network. Only
+   reachable from dom0, so only together with `ssh_via_host = true`.
+
+### SSH and port forwarding
+
+SSH goes straight to the guest IP. With `ssh_via_host = true` it goes through
+dom0 as a ProxyCommand (`ssh -W %h:%p`) with normal host key checking: add
+the host's key to your `known_hosts` first.
+
+Each `forwarded_port` starts a background `ssh -N -L` through the guest. The
+default `22 → 2222` forward is skipped unless `forward_ssh_port = true`. Host
+ports below 1024 and UDP are refused. Tunnels bind to `127.0.0.1` unless you
+set `host_ip:`.
+
+## Disks and cloud-init
+
+```ruby
+config.vm.disk :disk, primary: true, size: "40GB"          # grow (never shrink)
+config.vm.disk :disk, name: "data", size: "100GB", xapi__sr: "fast-ssd"
+config.vm.disk :disk, name: "seed", file: "./seed.qcow2"   # import an image
+config.vm.disk :dvd, name: "tools", file: "./tools.iso"    # upload an ISO
+```
+
+ISOs that already live on an ISO SR are not a `config.vm.disk` (Vagrant
+requires a local file for every `:dvd`), but a provider option:
+
+```ruby
+config.vm.provider :xapi do |xapi|
+  xapi.isos = ["debian-12.iso"]
+end
+```
+
+Disks are only resized while the VM is halted; the filesystem in the guest
+does not grow by itself (cloud-init `growpart` usually takes care of it).
+
+A guest only sees CD drives in the device slots 0-3. Slot 0 is the boot
+disk, extra disks take the first free slots, and many boxes have an empty CD
+drive of their own (usually slot 3); `vagrant xapi info` shows the slots. An
+uploaded ISO that finds no free slot is attached as a read-only disk instead,
+with a warning; in the guest it is a disk such as `/dev/xvde` that mounts
+like the CD would. An ISO from `isos` gives an error.
+Disks larger than 2 TiB give a warning, because VHD-based SRs cannot hold them.
+
+`config.vm.cloud_init` works as in other providers: the plugin builds the
+NoCloud ISO (volume `cidata`), uploads it and attaches it. When its content
+changes, it is replaced.
+
+## Snapshots
+
+All `vagrant snapshot` subcommands work. `snapshot_memory = true` makes
+`save` of a running VM a checkpoint including memory; restoring a checkpoint
+resumes the VM.
+
+## Comparing files
+
+`vagrant xapi diff` lists the files that changed since a snapshot:
+
+```sh
+vagrant snapshot save before
+vagrant provision
+vagrant xapi diff --from before
+```
+
+```
+A /etc/nginx/sites-enabled/app
+M /etc/hosts  (content)
+m /etc/sudoers.d/app  (mode 0440 -> 0640)
+T /opt/app  (directory -> symlink)
+D /var/www/html/index.nginx-debian.html
+```
+
+`A` added, `D` removed, `M` other content, `m` other mode or owner only,
+`T` another type (device nodes are compared by type, mode and owner, not by
+their device numbers). `--to SNAPSHOT` compares two snapshots, `--with MACHINE`
+two running machines of the Vagrantfile. `--path /etc` limits the
+comparison (symlinks are compared as links, also in a `--path`: nothing
+below a symlink matches), `--exclude '*.log'` leaves paths out (a pattern
+without a leading `/` matches at any depth, so `--exclude node_modules`
+leaves out every `node_modules`; by default `/tmp`, `/var/tmp`, `/var/cache`,
+`/var/log`, the systemd random seed and `/usr/src` are left out, and
+`--no-default-excludes` compares them too), `--checksum` compares the content
+of every file instead of trusting size and modification time, and `--plain`
+or `--json` are for scripts.
+
+`--content` also shows what changed in each file, as a unified diff after
+the list:
+
+```sh
+vagrant xapi diff --from before --content --path /etc
+```
+
+```
+--- a/etc/hosts
++++ b/etc/hosts
+@@ -1 +1,2 @@
+ 127.0.0.1 localhost
++10.0.0.5 db
+```
+
+Added and removed files show their whole content. Binary files and files
+larger than `--content-limit` (default `1M`) are named but not shown, also
+when a file grew past it while the diff ran. Each side copies at most
+16 MiB in all, or `--content-limit` when that is larger; after a large
+upgrade the files beyond that are named too. The content appears in your
+terminal, also of files
+such as `/etc/shadow` when they changed; narrow it with `--path`. It needs
+`diff` on the local machine.
+With `--json` each change gets a `diff` field, or `diff_skipped` with the
+reason; `--plain` does not take `--content`.
+
+The machine must be running: the plugin attaches throwaway copies of the
+snapshot's disks to the VM, mounts them read-only in the guest, compares
+there and removes the copies again. It needs a Linux guest with GNU
+findutils, coreutils and util-linux, a guest agent (XAPI only attaches disks
+to a running VM with PV drivers), and ext4, XFS or vfat file systems, also on
+LVM (with lvm2 in the guest: the copy gets LVM identifiers of its own, the
+guest's own volume groups are not touched). Guests with LUKS, btrfs, ZFS or
+RAID are refused; compare two machines with `--with` instead.
+
+## `vagrant xapi`
+
+| Command | Purpose |
+| --- | --- |
+| `vagrant xapi info [vm]` | UUID, host, SR, template, VIFs with IPs, snapshots |
+| `vagrant xapi console [vm]` | VNC console through the XAPI console tunnel on a local port, with a one-time VNC password; opens the viewer (`open vnc://` on macOS with the password in the URL, so Screen Sharing connects without asking; `xdg-open` on Linux, where the viewer asks for the password the terminal shows) |
+| `vagrant xapi adopt [vm] UUID` | Attach an existing VM to this machine (or re-adopt its own VM after moving the project); a VM without vagrant-xapi marking, or one that belongs to someone else, needs `--force` |
+| `vagrant xapi templates list` | Templates with box, version, SR, size and number of clones |
+| `vagrant xapi templates prune [--keep N]` | Keep only the newest N versions per box (default 1) |
+| `vagrant xapi templates remove NAME\|UUID` | Remove one template |
+| `vagrant xapi orphans [--destroy]` | VMs of this Vagrant installation whose Vagrant machine no longer exists |
+| `vagrant xapi migrate` | Moves this project's machines of a vagrant-xenserver Vagrantfile from `:xenserver` to `:xapi`, after the Vagrantfile was changed (see Migrating) |
+| `vagrant xapi hosts [--plain\|--json\|--pem]` | The pool's hosts with address, role and the SHA-256 fingerprint of their TLS certificate, as the master reports them; `--pem` prints the certificates, e.g. for `tls_ca_file` |
+| `vagrant xapi diff [vm] --from SNAPSHOT [--to SNAPSHOT]` or `--with MACHINE` | Files that differ between a snapshot and the running machine, two snapshots, or two running machines (see above) |
+| `vagrant xapi marked [--mine] [--project DIR] [--vm UUID] [--box NAME]` | Everything in the pool that vagrant-xapi created (all users); `--mine` for only your own VMs with their snapshots, disks and networks, or narrow it to a project, VM or box; `--plain` or `--json` for scripts |
+
+Everything that deletes asks for confirmation unless `--force` is given.
+`prune` and `remove` first show which other users still have clones.
+Removing a template is safe while clones exist: the storage layer keeps the
+shared base disk.
+
+## Security
+
+- **TLS** is always verified. For a self-signed certificate set
+  `tls_fingerprint` (SHA-256 of the host certificate) or `tls_ca_file`. There
+  is no "insecure" option. Get the fingerprint with:
+
+  ```sh
+  openssl s_client -connect xcp-master:443 </dev/null 2>/dev/null \
+    | openssl x509 -noout -fingerprint -sha256
+  ```
+
+  Each pool member has its own certificate. Pin the **master** and use it as
+  `host`; with a pin on a member the plugin stops and names the master.
+  Transfers and consoles that run on another pool member use the
+  certificate the master reports for that member.
+- **Secrets**: the password and the session id never appear in logs
+  (also not with `VAGRANT_LOG=debug`), error messages, URLs or process
+  arguments. Uploads and downloads stream in Ruby with the session as a
+  cookie; there is no `curl`.
+- **Subprocesses** (`ssh` for tunnels, `qemu-img`) always run with an argv
+  array, never through a shell.
+- **Cleanup** only touches objects carrying the plugin's marking: the tag
+  `vagrant` and `other_config` keys `vagrant-xapi.*` (machine, project, user,
+  local hostname, installation id, version). `destroy` removes the VM, its snapshots, its own disks and
+  its cloud-init ISO; never a template's disks.
+- **Downloads**: an `http://` `xva_url` gives a warning, because the host
+  then downloads the image unencrypted.
+- **Supply chain**: no runtime gems.
+
+### Which XAPI role is needed?
+
+The plugin creates and destroys VMs, VDIs, VBDs and VIFs, uses
+`pool.other_config` for its locks, and creates internal networks for
+`private_network`. With `pool-admin` everything works.
+
+`vm-admin` covers the VM lifecycle, but may not be allowed to write the
+pool's `other_config` or to create networks. In that case the plugin stops
+with a readable message (`lock_permission_denied`).
+
+## Migrating from vagrant-xenserver
+
+Vagrantfiles written for vagrant-xenserver keep working unchanged:
+
+```sh
+vagrant plugin uninstall vagrant-xenserver   # both cannot be installed
+# install vagrant-xapi as described under Install
+export VAGRANT_XAPI_TLS_FINGERPRINT=AB:CD:...,12:34:...   # once; see below
+vagrant up
+```
+
+- `config.vm.provider "xenserver"` with `xs.xs_host`, `xs.name` and the
+  other `xs_*` options works, and so do boxes of vagrant-xenserver. Every run
+  says once that the compatibility with vagrant-xenserver is in use.
+- Existing machines are taken over: vagrant-xapi finds their VMs by the
+  reference vagrant-xenserver stored, marks them and their own disks, and
+  carries on with them. No second VM is created.
+- `vagrant destroy` removes all disks of the VM that no other VM uses, as
+  vagrant-xenserver did, including disks that triggers attached.
+- The one new setting is TLS. vagrant-xenserver sent its API calls, the
+  login included, over plain HTTP on port 80 (also with `xs_use_ssl = true`);
+  vagrant-xapi always uses HTTPS and checks the certificate. Set
+  `VAGRANT_XAPI_TLS_FINGERPRINT` to the fingerprints of all hosts of the
+  pool, separated by commas, or `VAGRANT_XAPI_TLS_CA_FILE`, unless your
+  machine already trusts the pool's certificates. Once connected to the
+  master with one pin, `vagrant xapi hosts` shows the fingerprints of all
+  hosts.
+
+**Triggers that call XAPI themselves** (`require "xenapi"` and
+`XenApi::Client`, e.g. to add extra disks or set vCPUs) keep working in 1.x,
+through a stand-in for that gem. The stand-in is **temporary** and says so
+when a trigger uses it. Replace such triggers with the provider's own
+options, which `xs` has as well: `xs.cpus` for vCPUs and `config.vm.disk`
+for extra disks. The plugin chooses the disk slots itself, so check device
+names such as `/dev/xvdi` that other tools rely on.
+
+`:xapi` is the provider for new Vagrantfiles. To move a project to it,
+change the provider block with the table below and run `vagrant xapi
+migrate`: it moves the machines from `.vagrant/machines/<name>/xenserver` to
+`xapi`, without which Vagrant would create new VMs.
+
+| vagrant-xenserver | vagrant-xapi |
+| --- | --- |
+| `config.vm.provider :xenserver do \|xs\|` | `config.vm.provider :xapi do \|xapi\|` |
+| `xs.xs_host` | `xapi.host` (or `VAGRANT_XAPI_HOST`) |
+| `xs.xs_username` | `xapi.username` |
+| `xs.xs_password` | `xapi.password` |
+| `xs.xs_port` / `xs.xs_use_ssl` | `xapi.port`; always HTTPS (port 443) |
+| `xs.name` | `xapi.name_label` |
+| `xs.memory` | `xapi.memory` |
+| `xs.api_timeout` | `xapi.api_timeout` |
+| `xs.pv = true` | not supported; HVM only (PV boxes are switched to HVM) |
+| `xs.use_himn = true` | `xapi.ip_detection = [:himn]` plus `xapi.ssh_via_host = true` |
+| `xs.xva_url` | `xapi.xva_url` |
+| `config.vm.network :public_network, bridge: "xenbr0"` | the same |
+| Bridges from your own variables, e.g. `bridge: ENV["VAGRANT_XS_BRIDGE_EXTERNAL"]` | The same works; or set `VAGRANT_XAPI_DEFAULT_NETWORK=xenbr1` and leave the external `public_network` out |
+
+New compared to vagrant-xenserver: CPUs, UEFI and vTPM, choice of SR,
+private networks, port forwarding, disks, cloud-init, snapshots, package,
+proper TLS, and the `vagrant xapi` commands.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake            # unit tests (rspec, against a fake XAPI)
+bundle exec vagrant ...     # run Vagrant with the plugin from this checkout
+```
+
+The unit tests run the real Vagrant action stacks against an in-memory XAPI
+(`spec/support/fake_xapi.rb`). Acceptance tests against a real pool are in
+`test/acceptance`; see the README there.
+
+## Documentation
+
+- [docs/architecture.md](docs/architecture.md): scope, design, how every
+  action and feature maps to XAPI, security, tests and decisions.
+- [docs/operations.md](docs/operations.md): connecting, RBAC, boxes,
+  templates, finding and cleaning up objects, locks, troubleshooting,
+  development and releasing.
+- [test/acceptance/README.md](test/acceptance/README.md): acceptance tests
+  against a real pool.
+
+Both files under `docs/` are also in the gem, in
+`~/.vagrant.d/gems/<ruby version>/gems/vagrant-xapi-<version>/docs/`.
+
+## License
+
+MIT, like vagrant-xenserver and Vagrant itself.