vagrant-xapi 0.0.1 → 1.0.0

data/docs/architecture.md

@@ -0,0 +1,1420 @@
+# Architecture
+
+This document describes what vagrant-xapi is, how it is built, and why. It
+is the reference for design decisions; together with the
+[README](../README.md) (user-facing options) and
+[operations.md](operations.md) (running, troubleshooting, developing) it is
+the complete description of the plugin.
+
+## 1. Purpose and scope
+
+vagrant-xapi is a Vagrant provider (gem `vagrant-xapi`, provider `:xapi`)
+that manages VMs on XenServer 8 and XCP-ng through XAPI. It supports every
+action and provider capability Vagrant core asks for. It replaces
+[xapi-project/vagrant-xenserver](https://github.com/xapi-project/vagrant-xenserver)
+0.0.18, which only supports the basic lifecycle and `public_network`.
+
+### Goals
+
+- All actions Vagrant core asks a provider for: `up`, `halt`, `destroy`,
+  `reload`, `suspend`, `resume`, `provision`, `ssh`, `ssh_run`, `package`,
+  `snapshot_save`, `snapshot_restore`, `snapshot_delete` (plus
+  `sync_folders`).
+- All provider capabilities core uses: `snapshot_list`, `forwarded_ports`,
+  `public_address`, `nic_mac_addresses`, `configure_disks`, `cleanup_disks`,
+  `validate_disk_ext`, `default_disk_exts`, `set_default_disk_ext`.
+- Works against a standalone host and against a pool, on every SR type XAPI
+  supports.
+- `vagrant up --provider=xapi` works with only a host and credentials.
+- Boxes of vagrant-xenserver and of libvirt work without manual conversion.
+- Vagrantfiles of vagrant-xenserver (`config.vm.provider :xenserver` with
+  `xs_*` options) keep working, with the machines that plugin created
+  (section 17).
+
+### Supported versions
+
+- Vagrant 2.4.x (Ruby 3.0 up to, not including, 3.5, as Vagrant's gemspec
+  requires); the tests run against Vagrant 2.4.9 (pinned in the Gemfile).
+- XenServer 8 and XCP-ng 8.3; only the current releases are supported.
+  Optional XAPI features (qcow2 import, vTPM) are detected at runtime. If one is missing, the user only gets an error when
+  they ask for that feature.
+
+### Non-goals
+
+- No dependency on Xen Orchestra, not even an optional one.
+- No PV guests (pygrub); only HVM with BIOS or UEFI. PV boxes are switched to
+  HVM boot on import, with a warning.
+- No Go plugin: vagrant-go was removed from Vagrant (GH-13622), although the
+  Go pages are still in the 2.4.9 docs.
+- No management of the pool itself (SRs, bonds, VLANs), except internal
+  networks for `private_network`.
+
+## 2. Compared with vagrant-xenserver 0.0.18
+
+vagrant-xapi does everything vagrant-xenserver does, and more. PV guests are
+dropped. Vagrantfiles written for it, with the provider name `:xenserver`
+and its `xs_*` options, keep working (section 17); `:xapi` is the provider
+for new Vagrantfiles. `use_himn` lives on as `ip_detection: [:himn]` with
+`ssh_via_host = true`. The left column comes from the old plugin's source
+(master, November 2024).
+
+| Area | vagrant-xenserver 0.0.18 | vagrant-xapi |
+| --- | --- | --- |
+| API transport | XML-RPC via gem `xenapi` (2011) and `xmlrpc`; load error in issue #54 | JSON-RPC with only the stdlib, no runtime gems |
+| Connection | Default `http` on port 80, password unencrypted; uploads with `curl --insecure` and `session_id` in the URL | HTTPS on 443 with certificate check or fingerprint pin; session as cookie |
+| Sessions | Never logged out | One shared session per process, logout at exit |
+| Pool | No handling of a pool member (issue #60) | Redirect to the master on `HOST_IS_SLAVE` |
+| Machine id and state | OpaqueRef; state as XAPI string | VM UUID; state as symbol, including `:paused` |
+| `up`, `halt`, `destroy`, `suspend`, `resume`, `provision`, `ssh` | Yes; `halt` only `clean_shutdown` without fallback | Yes; graceful, then clean, then hard shutdown |
+| `reload` | Halt and boot; config changes are not applied | Re-applies CPU, memory, firmware, VIFs and disks |
+| Boxes | `xenserver` box with XVA, XVA URL or VHD | Also qcow2 and raw; besides `xenserver` also `xapi` and `libvirt` boxes |
+| Template cache | Per box name and version, in-process mutex only; VHD reuse on md5 of the first MB | Per SHA-256 and SR, with a lock that works across processes and users |
+| CPUs | Not configurable (issue #42) | `cpus`, `cores_per_socket` |
+| Memory | Static | Static plus dynamic minimum |
+| Firmware | PV with pygrub or the template default | BIOS, UEFI, Secure Boot, vTPM; no PV |
+| Storage | Only the pool's default SR | `sr`, `template_sr`, SR per disk; `:fast` or `:full` clone |
+| Host placement | No | `affinity_host` |
+| `public_network` | Only by bridge name, and required unless HIMN | By name, UUID or bridge, with MAC, MTU and static IP; without one a default VIF |
+| `private_network` | No | Internal network or existing network |
+| `forwarded_port`, `vagrant port` | No | SSH tunnels |
+| IP detection | `0/ip` from guest metrics, or HIMN | Configurable order: guest metrics (`ipv4/N`), static via cloud-init, HIMN |
+| SSH through dom0 | Only with HIMN, host key checking off | Optional, host key checking on |
+| Hostname | Ignored (issue #43) | `SetHostname` |
+| Synced folders | rsync and NFS; host IP via `ip route` or `route get` | rsync, NFS and SMB; host IP in Ruby |
+| `config.vm.disk` | No | Disk, DVD/ISO, growing the primary disk |
+| `config.vm.cloud_init` | No | Yes, including `network-config` |
+| Snapshots | No | save, restore, delete, list, push, pop; optionally with memory |
+| `vagrant package` | No | XVA, VHD or qcow2 |
+| Own commands | No | `vagrant xapi info`, `console`, `adopt`, `templates`, `orphans` |
+| Error messages | Partly raw XAPI errors and stack traces (issue #20) | Always a `VagrantError` with readable text |
+| Cleanup on `destroy` | All disk VDIs of the VM | Only marked objects, including snapshots, cloud-init VDI and internal networks |
+| Tests | None | rspec against a fake XAPI, and acceptance scenarios for XCP-ng and XenServer |
+
+## 3. Constraints from Vagrant
+
+The plugin follows the rules of the
+[Vagrant 2.4.9 plugin documentation](https://developer.hashicorp.com/vagrant/docs/plugins)
+(all 15 pages, including the
+[source on GitHub](https://github.com/hashicorp/web-unified-docs/tree/main/content/vagrant/v2.4.9/content/docs/plugins)).
+Where the docs point to the source code, Vagrant main of November 2026
+applies.
+
+| Rule | Consequence for vagrant-xapi | Source |
+| --- | --- | --- |
+| A plugin is a RubyGem, set up with `bundle gem` | Gemfile with `vagrant` from git (pinned to a release tag) in group `:development` and the plugin in group `:plugins` (as `gem "vagrant-xapi", path: "."`: `gemspec` inside a group block ignores the group); test with `bundle exec vagrant` | [Development basics](https://developer.hashicorp.com/vagrant/docs/plugins/development-basics) |
+| The gemspec must not depend on the gem `vagrant` | Only our own runtime code; no runtime gems | [Packaging](https://developer.hashicorp.com/vagrant/docs/plugins/packaging) |
+| The plugin definition must always load; load components lazily in their block | `plugin.rb` only holds registrations, with `require_relative` inside each block | [Development basics](https://developer.hashicorp.com/vagrant/docs/plugins/development-basics) |
+| A stack trace is a bug | Every error is a subclass of `Vagrant::Errors::VagrantError` with text from `locales/en.yml`; XAPI errors are translated | [Development basics](https://developer.hashicorp.com/vagrant/docs/plugins/development-basics) |
+| No `puts`/`gets` | All output through `env[:ui]` or `machine.ui`; progress with `ui.clear_line` and `ui.detail` | [Development basics](https://developer.hashicorp.com/vagrant/docs/plugins/development-basics) |
+| Config with `UNSET_VALUE`, `finalize!`, `validate(machine)` | Defaults only in `finalize!`; `validate` starts with `_detected_errors` and returns an empty list when valid; own `merge` for lists and hashes | [Configuration](https://developer.hashicorp.com/vagrant/docs/plugins/configuration) |
+| The provider config is named after the provider | `config("xapi", :provider)`; works without a provider block once host and login are known (also from environment variables) | [Providers](https://developer.hashicorp.com/vagrant/docs/plugins/providers) |
+| The provider class documents itself in [provider.rb](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/plugin/v2/provider.rb) | `action(name)`, `state` (a `MachineState` with a symbol id), `ssh_info` (nil while SSH is impossible), class methods `usable?` and `installed?`, `machine_id_changed` | provider.rb |
+| `:not_created` clears the data_dir | A state lookup that does not find the VM returns `:not_created`; the plugin removes its own files in `data_dir` on destroy | provider.rb, [Providers](https://developer.hashicorp.com/vagrant/docs/plugins/providers) |
+| Box: `metadata.json` has `provider` equal to the provider name | Our own boxes have `"provider": "xapi"`; the rest of the box format is ours | [Providers](https://developer.hashicorp.com/vagrant/docs/plugins/providers) |
+| Parallel only with thread-safe action stacks | `provider("xapi", parallel: true, box_format: [...])`; no shared mutable state except the session cache and locks | [Providers](https://developer.hashicorp.com/vagrant/docs/plugins/providers) |
+| Use built-in middleware | Stacks are built on `HandleBox`, `ConfigValidate`, `Provision`, `SyncedFolders`, `SyncedFolderCleanup`, `WaitForCommunicator` (in a subclass that also retries a broken pipe, see below), `SetHostname`, `Disk`, `CleanupDisks`, `CloudInitSetup`, `CloudInitWait`, `GracefulHalt`, `HandleForwardedPortCollisions`, `ProvisionerCleanup`, `DestroyConfirm` | [builtin](https://github.com/hashicorp/vagrant/tree/main/lib/vagrant/action/builtin) |
+| Only public action hooks are stable | No hooks on internal Vagrant actions | [Action hooks](https://developer.hashicorp.com/vagrant/docs/plugins/action-hooks) |
+| Commands use `parse_options` and `with_target_vms` | The subcommands under `vagrant xapi` follow that pattern | [Commands](https://developer.hashicorp.com/vagrant/docs/plugins/commands) |
+| Test with vagrant-spec | Unit tests, and acceptance scenarios of our own against a real pool instead of vagrant-spec (section 15) | [Packaging](https://developer.hashicorp.com/vagrant/docs/plugins/packaging) |
+
+Not in the docs but in the source, and relevant: the provider options
+`box_format` (list of box providers the provider accepts), `priority` and
+`defaultable`; `config.vm.disk` and `config.vm.cloud_init` are no longer
+experimental; `CloudInitSetup` builds an ISO through the host capability
+`create_iso` and adds it as a `:dvd` disk, which the provider attaches in
+`configure_disks`.
+
+## 4. Layers
+
+The plugin has three layers. Only the client talks to the pool; only the
+integration layer knows Vagrant.
+
+```mermaid
+flowchart TB
+  subgraph local["Local machine (runs Vagrant)"]
+    subgraph integration["Vagrant integration (knows Vagrant)"]
+      plugin["plugin.rb: registrations"]
+      provider["provider.rb: state, ssh_info"]
+      actions["action.rb + action/*: middleware stacks"]
+      caps["cap.rb: capabilities"]
+      commands["command/*: vagrant xapi ..."]
+      config["config.rb, errors.rb, glue.rb, locales/en.yml"]
+    end
+    subgraph services["Services (XAPI logic, plain Ruby)"]
+      svc["template_cache, image_upload, vm_builder, networks,<br/>disks, snapshots, power, ip_detector, destroyer,<br/>exporter, inventory, console, lock, tunnels,<br/>differ, diff_disks, guest_files, file_diff"]
+    end
+    subgraph api["XAPI client (stdlib only)"]
+      client["client.rb: JSON-RPC, sessions, features"]
+      transport["transport.rb: TLS, pin, connection pool"]
+      task["task.rb: Async tasks via event.from"]
+      http["http_transfer.rb: /import, /export"]
+    end
+  end
+  pool[("XAPI pool master<br/>https://host/jsonrpc")]
+  guest[("Guest VM")]
+  integration --> services --> api --> pool
+  actions -. "ssh, tunnels (ssh -N -L)" .-> guest
+```
+
+SSH and the port-forward tunnels bypass XAPI: they go straight to the guest,
+or through dom0 with `ssh_via_host`.
+
+### Code map
+
+```
+lib/vagrant-xapi.rb              entry point: plugin + i18n
+lib/vagrant-xapi/
+  plugin.rb                      registrations only (provider, config, caps, command)
+  extensions.rb                  hook points for the layers below (section 17)
+  xenserver/                     compatibility with vagrant-xenserver Vagrantfiles (section 17)
+  legacy/                        temporary XenApi::Client stand-in for their triggers (section 17)
+  provider.rb                    action lookup, state, ssh_info
+  config.rb                      provider options, defaults, validation
+  action.rb                      the action stacks
+  action/                        our middleware (create, power, network, destroy,
+                                 snapshots, package, cloud_init, base)
+  cap.rb                         provider capabilities
+  command/                       vagrant xapi info|console|adopt|templates|orphans|
+                                 marked|hosts|diff
+  glue.rb                        Vagrant <-> services: client, context, VmSpec, VIF plan
+  errors.rb                      translation of client/service errors to VagrantErrors
+  api/                           XAPI client: client, transport, task, http_transfer,
+                                 session_registry, redactor, errors
+  services/                      XAPI logic, one class per concern
+locales/en.yml                   every user-facing text
+spec/                            unit tests and the fake XAPI
+test/acceptance/                 scenarios against a real pool
+```
+
+### Services contract
+
+Services get a `Services::Context` with:
+
+- `client`: the logged-in `Api::Client`;
+- `ui`: an object with `info/detail/warn(key, **params)`,
+  `progress(key, done, total, **params)` and `clear_progress`. Keys are
+  message keys under `vagrant_xapi.messages` in `locales/en.yml`.
+  `Glue::UiAdapter` maps them to the Vagrant UI;
+- `cancel`: a callable that returns true once the user pressed Ctrl-C
+  (`env[:interrupted]` in actions);
+- `logger`: a Log4r logger.
+
+Services raise `Services::Error(key, **params)` (key under
+`vagrant_xapi.errors`) or `Api::*` errors. They never raise Vagrant errors.
+
+## 5. Design decisions
+
+1. **XAPI client.** JSON-RPC 2.0 on `https://<host>/jsonrpc` with `net/http`
+   and `json` from the stdlib. No `xmlrpc` or `xenapi` gem: they caused load
+   errors in the old plugin (issue #54), and the gem `xenapi` is from 2011.
+   `client.call("VM.get_record", ref)` prepends the session. Capitalized
+   classes also have a proxy (`client.VM.get_record(ref)`); lowercase ones
+   (`host`, `pool`, ...) do not, because they would clash with the client's
+   own methods.
+2. **Pool master.** A `HOST_IS_SLAVE` error at login carries the master's
+   address; the client reconnects to it (at most two redirects). This was
+   issue #60 in the old plugin. With a single `tls_fingerprint` the
+   redirect is refused with a clear message instead (the pin belongs to the
+   member, not to the master): point `host` at the master. With several
+   pins (the certificates of all hosts) the redirect is followed and the
+   master's certificate must be one of them, so any host can be `host`,
+   also after the master changed.
+3. **Sessions.** One session per Vagrant process per pool, user and
+   timeouts (`Api::SessionRegistry`), shared between threads (Vagrant runs
+   machines in parallel). Login is behind a mutex and builds the session and
+   the feature list in local variables before swapping them in, so other
+   threads never see a half state. Each call takes the session once. On
+   `SESSION_INVALID` the client logs in again, unless another thread already
+   did, and retries the call once. All sessions are logged out in `at_exit`.
+   Login sends originator `vagrant-xapi/<version>`.
+4. **Long operations.** Always the `Async.` variant, waiting for the task with
+   `event.from` (5 s per call) and progress to the UI. If `event.from` fails
+   (RBAC, `EVENTS_LOST`) the client polls `task.get_record` every
+   second. A dropped connection or read timeout while waiting is retried
+   for up to 60 s: giving up would destroy the task record while XAPI goes
+   on with the work, e.g. a `VM.copy` whose VM nobody would then mark or
+   clean up. On Ctrl-C the task is cancelled with `task.cancel`; on timeout
+   too. Tasks are always destroyed afterwards.
+5. **HTTP transfers.** Uploads and downloads (`/import`, `/import_raw_vdi`,
+   `/export`, `/export_raw_vdi`) stream in Ruby with `net/http`. The
+   `session_id` travels as a cookie, never in the URL. The handlers answer
+   an expired or evicted session with 401; as for `SESSION_INVALID`, the
+   client then logs in again once and starts the transfer (or the qcow2
+   probe) over. There is no `curl`
+   subprocess, so no secrets in `ps`. Uploads that need a result create a task
+   with `task.create` and pass it as `task_id`. On Ctrl-C a watcher thread
+   cancels the task and closes the socket; a task that is never waited for is
+   cancelled and destroyed.
+   - **Which host.** XAPI answers these handlers with a 302 to another host
+     when the receiving host cannot reach the SR (e.g. a local SR of a pool
+     member). A streamed PUT cannot follow that, so the plugin picks the host
+     first: for an SR, a host with a `currently_attached` PBD (the master if
+     it is one of them); for an export, a host that sees all the VM's SRs
+     (master first, then the host the VM runs on). Downloads also follow
+     302s.
+   - **No `Expect: 100-continue`.** XAPI never answers it with
+     `100 Continue`, and Net::HTTP would then wait for a body it never sent.
+   - **Probing.** Where a handler must be asked whether it accepts something
+     (qcow2), an empty PUT is sent and only the status line is read.
+6. **Machine id.** The VM UUID, not the OpaqueRef. Every action looks the VM
+   up with `VM.get_by_uuid`; not found means `:not_created`.
+7. **Marking.** Every object the plugin creates carries a marking (section
+   6). Cleanup only ever touches marked objects; the subcommands use the
+   marking to find orphaned VMs.
+8. **Locks across processes.** A lock is a key `vagrant-xapi.lock.<name>` in
+   the pool's `other_config`, set with `pool.add_to_other_config`. XAPI refuses
+   an existing key with `MAP_DUPLICATE_KEY`, so taking it is atomic. The value
+   is JSON with owner (`user@hostname:pid:random`) and expiry. After adding the
+   key, the owner is read back; only a lock that carries our owner counts as
+   held. A lock is only released by its owner. Times come from the pool
+   master's clock (`host.get_servertime`), so machines with skewed clocks
+   agree. If that time cannot be read (RBAC, an unparsable value), the lock
+   falls back to the local machine's clock and logs a warning; then clock skew
+   between machines matters again.
+   - **Heartbeat.** While the lock is held, a thread refreshes
+     `vagrant-xapi.lock.<name>.alive.0` and `.alive.1` in turn every TTL/4,
+     so one of them is always fresh. A lock only counts as abandoned when its
+     own expiry and every heartbeat of the same owner have passed. A long
+     import (a slow upload plus a conversion) therefore never loses its lock,
+     and the TTL can stay short (15 minutes for templates): it only decides
+     how quickly the lock of a crashed process is taken over. While holding
+     the lock, a heartbeat replaces whatever is in its slot (e.g. a crashed
+     holder's key) and logs a warning if it cannot write. The heartbeat
+     thread is stopped and joined before the lock is released, so no beat
+     lands afterwards. A successful takeover also removes the crashed
+     holder's heartbeat keys; an expired takeover guard is only removed if it
+     still has the value that was read.
+   - **Taking over an expired lock.** XAPI has no compare-and-swap, so two
+     processes that both see the same stale value could both remove it and
+     each think they hold the lock. A takeover therefore first takes a second
+     key, `vagrant-xapi.lock.<name>.takeover` (atomic in the same way,
+     expires after 60 s), checks that the lock still has the same stale
+     value and is still abandoned, replaces it, and removes the guard.
+   - **Waiting** for a busy template lock lasts up to 2 × `task_timeout` +
+     25 minutes, which covers a live import and the takeover of a crashed
+     one.
+   - **Within one process** threads first serialize on a mutex per lock name,
+     so they do not poll XAPI against each other. Waiting for it has the same
+     deadline and reacts to Ctrl-C. An in-process mutex alone is not enough
+     (the old plugin had only that).
+9. **Feature detection.** At first login the client reads the API version and
+   product of the master and checks optional classes (`VTPM.get_all`).
+   `MESSAGE_METHOD_UNKNOWN` means "not available". qcow2 import is probed on
+   first use (see section 7) and remembered per session.
+10. **Errors.** `Errors.translate` turns every `Api::*` and `Services::Error`
+    into a `VagrantError` with text from `locales/en.yml`. Common XAPI codes
+    have their own text (`SESSION_AUTHENTICATION_FAILED`,
+    `RBAC_PERMISSION_DENIED`, `SR_FULL`, `SR_BACKEND_FAILURE_44`,
+    `HOST_NOT_ENOUGH_FREE_MEMORY`, `NO_HOSTS_AVAILABLE`, `VM_BAD_POWER_STATE`,
+    `LICENCE_RESTRICTION`, `VM_REQUIRES_SR`, `VM_REQUIRES_NETWORK`,
+    `OPERATION_NOT_ALLOWED`, `OTHER_OPERATION_IN_PROGRESS`,
+    `VM_MISSING_PV_DRIVERS`, `VDI_IN_USE`, `HOST_OFFLINE`); others show the
+    raw code, its parameters and the call. Every action stack starts with a
+    `TranslateErrors` middleware; capabilities, provider methods and commands
+    wrap their work in `Errors.wrap`. A missing interpolation value never
+    raises (it shows `?`), and messages pass through the redactor.
+11. **Secrets.** `Api::Redactor` keeps a process-wide list of secrets (the
+    password, whatever its length, and every session id) and removes them,
+    plus any `session_id=...` and any `user:password@` in a URL (e.g. an
+    `xva_url`), from every log line, error message and UI message. Login
+    parameters are logged as `[user], [REDACTED]`. `Config#inspect`, `to_s`
+    and `to_json` hide the password.
+12. **TLS.** Certificate checks are always on. A `tls_fingerprint` replaces
+    CA and hostname checks: the handshake's verify callback accepts the leaf
+    certificate only when its SHA-256 matches, and the peer certificate is
+    checked again after connecting. It may be a list (or a string with
+    commas), e.g. the certificates of all hosts of the pool; a certificate
+    is accepted when it matches one of them. `tls_ca_file` replaces the default trust
+    store. There is no "insecure" option; `tls_verify = false` without a
+    fingerprint is a validation error.
+    - **Other pool hosts** (transfers and consoles on a member) have their
+      own certificates, which a pin for the master or a hostname check
+      against an IP address would not match. The plugin asks the already
+      verified master for the member's certificate
+      (`host.get_server_certificate`) and pins exactly that one. Only if that
+      call fails are the configured settings used.
+
+## 6. Marking reference
+
+| Object | Key (in `other_config` unless noted) | Value |
+| --- | --- | --- |
+| VM | tag `vagrant` | |
+| VM | `vagrant-xapi.machine` | Vagrant machine name |
+| VM | `vagrant-xapi.project` | Project directory (where the Vagrantfile is) |
+| VM | `vagrant-xapi.user` | Login name on the local machine |
+| VM | `vagrant-xapi.client` | Hostname of the local machine |
+| VM | `vagrant-xapi.client_id` | Random id of the Vagrant installation (`~/.vagrant.d/data/vagrant-xapi/client-id`) |
+| VM | `vagrant-xapi.version` | Plugin version that created it |
+| VM | `vagrant-xapi.template` | UUID of the template it was cloned from |
+| VM | `vagrant-xapi.vtpm` | `true` when the plugin created its vTPM; with `vtpm` turned off, `reload` removes that vTPM (not one that came with the box or an adopted VM) |
+| Template | `vagrant-xapi.box`, `.box_version`, `.box_provider` | Box name, version, provider |
+| Template | `vagrant-xapi.box_digest` | SHA-256 of the box content |
+| Template | `vagrant-xapi.sr` | UUID of the SR the template is on |
+| Template VDI | `vagrant-xapi.of_template` | Template UUID |
+| VM's own VDI | `vagrant-xapi.vm` | VM UUID (disks of the clone, extra disks, ISOs, snapshot disks) |
+| VDI from `config.vm.disk` | `vagrant-xapi.disk` | Disk name from the Vagrantfile |
+| Uploaded ISO | `vagrant-xapi.sha256` | SHA-256 of the ISO, to detect changes |
+| CD drive (VBD) for an ISO from an ISO SR | `vagrant-xapi.iso` | Name or UUID from the `isos` option |
+| cloud-init ISO | `vagrant-xapi.cloud_init` | `true` |
+| Snapshot | `vagrant-xapi.snapshot_of` | VM UUID |
+| Clone of a snapshot disk (`vagrant xapi diff`) | `vagrant-xapi.vm`, `vagrant-xapi.diff`; name `vagrant-xapi diff of <vm uuid>` | VM UUID; id of the run |
+| VBD of such a clone | `vagrant-xapi.diff` | Id of the run |
+| Internal network | `vagrant-xapi.project`, `vagrant-xapi.network` | Project directory, network name |
+| Pool | `vagrant-xapi.lock.<name>` | Lock (section 5, item 8) |
+| Pool | `vagrant-xapi.lock.<name>.alive.0`, `.alive.1`, `.takeover` | Heartbeats and takeover guard of that lock |
+
+A VM counts as marked when it has both `vagrant-xapi.machine` and
+`vagrant-xapi.project`. The keys `vagrant-xapi.*` are reserved: the
+`other_config` option refuses them.
+
+## 7. Boxes and the template cache
+
+The provider accepts three kinds of boxes
+(`box_format: ["xapi", "xenserver", "libvirt"]`) and imports every box exactly
+once per SR as an XAPI template. Every VM is then a clone or copy of that
+template.
+
+| Box provider | Content | Import |
+| --- | --- | --- |
+| `xapi` | `metadata.json` with `provider`, `format` (`xva`, `vhd`, `qcow2` or `raw`) and `architecture: "amd64"`; one file `box.<format>` (without `format`, the first `box.*` found); optionally a Vagrantfile with provider defaults such as `firmware` | XVA via `/import`, disk image via `/import_raw_vdi` |
+| `xenserver` | Box of the old plugin: `box.xva`, `box.vhd`, or only a Vagrantfile with `xva_url` | Same paths; `xva_url` via `Async.VM.import` by the host itself |
+| `libvirt` | `box.img` (qcow2), or several disks in the newer libvirt format (`metadata.json` `disks: [{path: ...}]`) | `/import_raw_vdi?format=qcow2` when XAPI knows it and can read the image (no compressed clusters); otherwise `qemu-img convert -f qcow2 -O vpc -o subformat=dynamic` on the local machine and import as VHD, with a clear error when `qemu-img` is missing |
+
+The `xva_url` of an old-plugin box is read from the box Vagrantfile's
+`:xenserver` provider block (which Vagrant keeps as a `DummyConfig`), with a
+text match on `xva_url = "..."` as fallback. The provider option `xva_url`
+takes precedence. An `http://` URL gives a warning.
+
+Every file a box names (`box.<format>`, the paths in a libvirt
+`metadata.json`) must be a regular file inside the box directory, also after
+resolving symlinks; anything else is refused (`box_path_outside`). qcow2
+images that refer to other files (a backing file, or an external data file)
+are refused too: converting them would make `qemu-img` read files on the
+local machine and copy them into the image. Vagrant already runs a box's own
+Vagrantfile as Ruby, so this is defence in depth for users who set
+`config.vm.ignore_box_vagrantfile = true`, not the main trust boundary.
+
+### Importing a disk image
+
+1. Read the format and virtual size from the header: VHD footer (current size
+   at offset 48), qcow2 header (magic `QFI\xFB`, size at offset 24, 8 bytes
+   big endian), or the file size for raw. No `qemu-img` needed. The format
+   comes from the content, not the extension (`box.img` is usually qcow2).
+2. `VDI.create` on the target SR with that size.
+3. Stream to `/import_raw_vdi?vdi=<ref>&format=<fmt>` on the host that has
+   the SR attached, with progress in the UI. For qcow2 the plugin first asks
+   whether the pool can import it: it creates a 1 MiB scratch VDI, sends an
+   empty `PUT /import_raw_vdi?vdi=<scratch>&format=qcow2` and reads only the
+   status (XAPI rejects an unknown format before it reads the body; a known
+   one gets a 200), then removes the scratch VDI. The answer is remembered for
+   the session. If qcow2 is not supported, or there is no answer within 15 s,
+   the image is converted on the local machine with `qemu-img convert -f qcow2 -O vpc` and
+   uploaded as VHD. The answer is kept per transfer host, because pool
+   members can run different versions; if a host still refuses qcow2 after a
+   positive probe (a 4xx other than 401/403, or the connection closed while
+   the image is still being sent), the plugin converts, recreates the VDI
+   (the refused upload may have written part of it) and uploads the VHD. A
+   timeout, an unreachable host or a 5xx is raised as it is, not taken for
+   a refusal. XAPI's qcow2 import
+   (`qcow-stream-tool`) cannot read compressed clusters and fails only after
+   the whole upload with `VDI_IO_ERROR ... Compressed_unsupported`. Most
+   cloud images and many libvirt boxes use them, so before uploading the
+   plugin reads the L1 and L2 tables (a few MB) and converts an image with
+   compressed clusters, or with incompatible features other than the dirty
+   bit (zstd, extended L2 entries), straight away. A `VDI_IO_ERROR` from
+   `qcow-stream-tool` is also converted and retried, without marking the host
+   as unable to import qcow2. The same applies to qcow2 images in
+   `config.vm.disk`.
+4. Clone the template `Other install media`, remove its `disks` and
+   `install-methods` keys from `other_config` (otherwise `VM.provision` would
+   add an empty disk), attach the VDIs as `userdevice 0..n` (0 bootable), set
+   HVM boot policy `BIOS order`, boot order `cd` and firmware `bios`, and
+   raise memory to 1 GiB when it has less: "Other install media" has 256
+   MiB, too little for a current distribution, and under UEFI GRUB cannot
+   load the initramfs with it. The template is shared by everyone who uses
+   the box, so nothing from one user's configuration is baked into it:
+   `firmware` (also a default from the box's Vagrantfile) and `memory` are
+   set on each VM.
+5. `VM.set_is_a_template(true)`, switch PV boxes to HVM, set name, description
+   and the marking.
+
+### Cache key and marking
+
+A template carries `vagrant-xapi.box`, `.box_version`, `.box_provider`,
+`.box_digest` (SHA-256 of the box content; for `xva_url` boxes of the URL;
+for multi-disk boxes of the per-disk digests) and `.sr`. The digest is
+computed once and cached on the local machine in
+`~/.vagrant.d/data/vagrant-xapi/digests.json`, keyed on path, size and mtime.
+The environment variable `VAGRANT_XAPI_TEMPLATE_SALT`, when set, is mixed
+into the digest, so the same box imports as a new template; the acceptance
+scenarios use it to test imports on a pool that already has the box. The
+template is named `vagrant-xapi: <box> <version>`. Lookup first tries
+that name, then any marked template with the same digest and SR (a renamed
+box).
+
+### Concurrency
+
+Lookup and import run under the lock `template.<digest>.<sr-uuid>` (TTL
+15 minutes, kept alive by the heartbeat while the import runs). A second
+process or user waits ("Waiting for lock ... held by ...") and then uses the
+same template. An interrupted import leaves no half template: the VDIs and
+the template are only marked once the import succeeded, and on any error
+(including Ctrl-C) the lock owner removes everything it created.
+
+### Clone or copy
+
+`clone_mode: :fast` does `VM.clone`: fast, copy-on-write, on the template's
+SR. `:full` does `VM.copy` to `sr`, needed when VM and template are on
+different SRs. Both are followed by `VM.provision`. Removing a template is
+safe while clones exist: the SM layer keeps the shared base VHD.
+
+### Architecture
+
+XCP-ng and XenServer only run x86_64. With `box_architecture = :auto`,
+Vagrant picks the local machine's architecture, so on Apple silicon an amd64 box is
+not found. Therefore:
+
+- the README tells users to set `config.vm.box_architecture = "amd64"`;
+- `validate` warns (once per process) when the local machine is not amd64 and
+  `box_architecture` is `:auto`;
+- the import warns when a box's metadata names another architecture;
+- docs and scripts add local box files with `vagrant box add --architecture
+  amd64`: Vagrant stores a local box file under the local machine's architecture and
+  ignores `architecture` in its `metadata.json`;
+- boxes made by `vagrant package` set `box_architecture = "amd64"` in their
+  Vagrantfile.
+
+## 8. Actions and machine states
+
+Every action Vagrant asks for is a stack of built-in middleware plus our own
+steps; the order follows the VirtualBox provider. Every stack starts with
+`TranslateErrors`, `ConfigValidate` and `ConnectXapi` (which puts the shared
+session in `env[:xapi]` and a services context in `env[:xapi_ctx]`). `up`
+handles the box before validating, like VirtualBox, because the box
+Vagrantfile may supply provider defaults. The stacks that only act on an
+existing VM (`halt`, `reload`, `destroy`, `suspend`, `resume`, `provision`,
+`package` and the snapshots) first check whether it exists, and validate and
+connect only then. A machine without an id is `:not_created` without asking
+the pool, so for a machine that was never created or is destroyed they only
+say so; its Vagrantfile may not reach the pool, for example when `vagrant
+destroy` runs under the user's `VAGRANT_DEFAULT_PROVIDER`.
+
+### States
+
+`state` returns a `MachineState` with a symbol id (the old plugin returned
+XAPI strings).
+
+| XAPI | Vagrant id |
+| --- | --- |
+| VM not found, or no id | `:not_created` |
+| `Halted` | `:halted` |
+| `Running` | `:running` |
+| `Suspended` | `:suspended` |
+| `Paused` | `:paused` |
+
+When `current_operations` is not empty, the long description names the
+running operation, e.g. `clean_shutdown`.
+
+### Stacks
+
+| Action | Steps | XAPI |
+| --- | --- | --- |
+| `up` (new) | `HandleBox`, `ConfigValidate`, import template, create VM, then *start* | `VM.clone` or `VM.copy`, `VM.provision`, setters, `VIF.create` |
+| *create VM* | Clone/copy, provision, mark, apply CPU/memory/firmware/platform/vTPM/affinity/tags, create VIFs. All or nothing: on failure the VM and any new internal network are removed again | |
+| *start* | `running`: message, `Provision` (for `--provision`), and bring the port-forward tunnels in line with the Vagrantfile (restart dead or changed ones, e.g. after the local machine rebooted); `suspended`: *resume*; `paused`: unpause and the same for the tunnels; `halted`: *boot* | |
+| *boot* | `Provision`, stop leftover tunnels, `HandleForwardedPortCollisions`, `SyncedFolderCleanup`, `SyncedFolders`, `PrepareNFSSettings`, `SetHostname`, `CloudInitSetup`, `CleanupDisks`, `Disk`, remove disks an interrupted `vagrant xapi diff` left (section 12, under the diff lock of the VM), start VM (on an internal network: under the project's placement lock), wait for IP, `WaitForCommunicator`, configure static IPs in the guest, `CloudInitWait`, start tunnels. `Provision`, `SyncedFolders` and `SetHostname` do their work after the rest returns, so the effective order ends with hostname, synced folders, provisioning | `Async.VM.start` (or `VM.start_on` the host of an internal network) |
+| `halt` | Stop tunnels; `GracefulHalt` through the guest; otherwise clean shutdown, and hard shutdown after `shutdown_timeout` or straight away with `--force` | `Async.VM.clean_shutdown`, `Async.VM.hard_shutdown` |
+| `reload` | `halt`, re-apply CPU, memory, firmware, platform, tags and rebuild the VIFs, then *start* (disks through `Disk`/`CleanupDisks`) | as `halt` and `up` |
+| `destroy` | `DestroyConfirm`, check that the VM is marked for this machine and project (before anything touches it), `ProvisionerCleanup`, stop tunnels, hard shutdown, remove disks an interrupted `vagrant xapi diff` left, snapshots and own VDIs, remove the VM, remove unused internal networks, `SyncedFolderCleanup`, remove our files from `data_dir` | `VM.destroy`, `VDI.destroy` (never VDIs of a template) |
+| `suspend` | Only when running: stop tunnels, suspend; missing PV drivers or no suspend SR become a readable error | `Async.VM.suspend` |
+| `resume` | Only when suspended: stop leftover tunnels, port collision check (with repair, since the tunnels are set up anew), resume (on an internal network: on the host of a running peer, under the project's placement lock), wait for IP, `WaitForCommunicator`, start tunnels | `Async.VM.resume` (or `VM.resume_on` that host) |
+| `provision` | Only when running: `Provision` | none |
+| `ssh`, `ssh_run` | Check running, `SSHExec` / `SSHRun` | none |
+| `package` | See section 11 | `/export`, `/export_raw_vdi` |
+| `snapshot_save`, `_restore`, `_delete` | See section 11 | `VM.snapshot`, `VM.checkpoint`, `VM.revert` |
+| `sync_folders` | `SyncedFolders`, `PrepareNFSSettings` | none |
+
+### Cleanup rule
+
+The plugin only removes objects with this machine's marking: the VM (it must
+be marked with this machine's name and this project directory, otherwise
+`destroy` stops with an error; so a copied project directory cannot destroy
+the original's VM, and a moved project first re-adopts its VM with `vagrant
+xapi adopt`), the VDIs of its VBDs that
+carry `vagrant-xapi.vm` = this VM and are not used by any of our templates,
+its snapshots (with their disks and suspend image), its cloud-init ISO, its
+suspend image, and the snapshot clones of an interrupted `vagrant xapi diff`
+(marked with `vagrant-xapi.diff` and this VM). Unknown objects always stay.
+The one exception is the compatibility with vagrant-xenserver (section 17):
+for a `:xenserver` machine, `destroy` first marks the VM's exclusive disks
+as its own, as vagrant-xenserver removed every disk of the VM.
+
+### ssh_info
+
+`nil` while the VM is not running or has no IP. Otherwise: the IP from
+*IP detection* (one look, no waiting), port 22 (or `config.ssh.guest_port`),
+the user from `config.ssh`, and with `ssh_via_host` a `proxy_command` through
+dom0 of the host the VM runs on: `ssh -W %h:%p -l <host_ssh_user> -o
+BatchMode=yes <host address>`, with normal host key checking. The address and
+user are checked against a strict character set before they go into the
+command.
+
+## 9. Networks, IP detection and SSH
+
+XAPI has no NAT and no DHCP. Every VIF hangs on a real network of the pool,
+the IP comes from the guest itself, and port forwarding runs over SSH
+tunnels.
+
+**VIF order.** If the Vagrantfile has a `public_network`, the first one
+becomes device 0. Otherwise device 0 is a VIF on `default_network` (from the
+Vagrantfile, else `VAGRANT_XAPI_DEFAULT_NETWORK`, else the network of the
+master's management PIF). The other networks follow in
+Vagrantfile order. A HIMN VIF comes last (only when `ip_detection` contains
+`:himn` and `ssh_via_host` is on). `reload` rebuilds all VIFs; the MAC
+address per device is kept unless one is configured, so a cloud-init
+`network-config` that matches on MAC stays valid.
+
+| Vagrantfile | XAPI | Options |
+| --- | --- | --- |
+| `public_network` | VIF on an existing network | `network:` (UUID, name, or bridge, looked up in that order), `bridge:` (e.g. `xenbr0`, as in the old plugin), `mac:`, `mtu:` (default: the network's), `ip:` with `netmask:` and `gateway:` for a static address, `nameservers:`, `xapi__locking_mode:` |
+| `private_network` with `network:` or `bridge:` | VIF on an existing network (e.g. a VLAN) | as `public_network` |
+| `private_network` without `network:` | Internal network without PIF, created when missing (under the lock `network.<name>`), marked with the project; removed with the last VM that uses it. A network with that name that is not marked for this project is never joined (`internal_network_taken`) | `name:` (default `vagrant-xapi-<first 10 hex of SHA-256 of the project path>`), `ip:` required, because there is no DHCP |
+| `forwarded_port` | SSH tunnel from the local machine | `host`, `guest`, `host_ip` (default `127.0.0.1`), `guest_ip` (default `127.0.0.1`); TCP only |
+
+An internal network only exists per host. All VMs of a project on the same
+internal network therefore run on the same host. When a VM with internal
+networks starts, the plugin looks for another VM on those networks that is
+running and starts the new one with `VM.start_on` its host; with no such VM
+it starts normally and XAPI places it. This happens under the lock
+`placement.<project hash>`, so parallel machines of one project start one
+after the other and the second sees where the first runs. Nothing is stored,
+so a host that went offline is not used again once no VM runs there. Static addresses on devices other than 0 are set in
+the guest after `WaitForCommunicator` through the guest capability
+`configure_networks`, as the VirtualBox provider does: IPv4 as `:static`
+with a dotted netmask, IPv6 as `:static6` with a prefix length (default 64;
+`netmask:` may be a prefix or a dotted mask). A network with
+`auto_config: false` is left to the user: no `configure_networks` and no
+cloud-init `network-config` for it.
+
+### IP detection
+
+`ip_detection` sets the order of sources (default
+`[:guest_metrics, :static, :himn]`). Waiting stops after
+`config.vm.boot_timeout`, or earlier with an error when the VM stops.
+
+The values come from the guest agent and are untrusted: they end up in the
+SSH ProxyCommand (`%h`) and in NFS exports. Only a bare IPv4 or IPv6 literal
+is accepted (characters `0-9a-f:.`, parsed with `IPAddr`); loopback and
+unspecified addresses are ignored, and link-local ones too, except for HIMN.
+
+1. `:guest_metrics`: `VM_guest_metrics.networks`, key `0/ipv4/0`, with `0/ip`
+   as fallback, for VIF device 0. Works with xe-guest-utilities and
+   xen-guest-agent.
+2. `:static`: the `ip:` of the first VIF. The plugin puts the address in the
+   guest itself through a `network-config` in the cloud-init config drive
+   (section 10). That also works for boxes without a guest agent, such as
+   libvirt boxes.
+3. `:himn`: an extra VIF on the host internal management network, IP from
+   `network.assigned_ips` (a link-local 169.254.x.x lease, which is accepted
+   for this source). Only usable with `ssh_via_host`, because that
+   network is only reachable from dom0; `ip_detection = [:himn]` without
+   `ssh_via_host` is a validation error.
+
+### SSH
+
+Straight to the IP. With `ssh_via_host` the connection goes through dom0 as
+ProxyCommand (`ssh -W %h:%p`), with normal host key checking; the old plugin
+turned that off.
+
+### Port forwarding
+
+Per `forwarded_port` a background process
+`ssh -N -T -L <host_ip>:<host>:<guest_ip>:<guest>` runs through the guest,
+like [vagrant-libvirt](https://github.com/vagrant-libvirt/vagrant-libvirt)
+does, with `ExitOnForwardFailure=yes`, keep-alives, `BatchMode=yes`, the
+machine's SSH keys and, with `ssh_via_host`, the same ProxyCommand. Host key
+checking for the guest is off, as Vagrant does for guests. The processes are
+started with an argv array (no shell) in their own process group; their PIDs
+are in `data_dir/forwarded_ports.json`, their stderr in
+`data_dir/tunnels.log`. A tunnel that dies within a second is an error.
+Stopping checks on Linux that the PID still belongs to an `ssh` process.
+
+**Waiting for SSH.** The plugin's `WaitForCommunicator` is Vagrant's, with
+one addition. net-ssh raises `Errno::EPIPE` when sshd closes a connection
+right after accepting it. OpenSSH 9.8 and newer do that for a while after
+failed logins from the same address (`PerSourcePenalties`), e.g. while
+cloud-init on the first boot is still creating the `vagrant` user. Vagrant
+2.4 lists that error as retryable, but its `wait_for_ready` connects once and
+does not rescue it, so `vagrant up` ended with a stack trace. Within
+`boot_timeout` the plugin treats it as "not ready yet": it waits 5 seconds
+and tries again.
+
+Tunnels start after `WaitForCommunicator` and stop on `halt`, `suspend`,
+`destroy` and `package`, and before the collision check at boot and resume
+(for tunnels left over when the VM was stopped outside Vagrant).
+
+`vagrant up` of a running VM brings the tunnels in line with the
+Vagrantfile: tunnels that died or whose forward changed (address or port)
+are restarted, tunnels of removed forwards are stopped, and the others are
+not touched. A forward with `auto_correct: true` whose host port in the
+Vagrantfile is unchanged keeps the port it was auto-corrected to at boot;
+`forwarded_ports.json` stores both ports for that. Vagrant's collision
+check only runs at boot, so the plugin checks the host ports of the tunnels
+it is about to start itself, before it stops anything: a taken port moves
+to a free one from `usable_port_range` with `auto_correct`, and is
+Vagrant's collision error without, with all tunnels left as they were.
+IPv6 addresses go into the `-L` spec in brackets. `HandleForwardedPortCollisions` and the capability
+`forwarded_ports` make `vagrant port` and `auto_correct` work. Rules:
+
+- The default forward with id `ssh` (22 to 2222) is skipped unless
+  `forward_ssh_port = true`. It is also marked disabled, so Vagrant's
+  collision check ignores it and a taken port 2222 on the local machine
+  never blocks `up` or `resume`.
+- Host ports below 1024 and `protocol: "udp"` are validation errors.
+- Tunnels bind to `127.0.0.1` unless `host_ip:` says otherwise (VirtualBox
+  binds to all interfaces; here the safer default was chosen).
+
+### Capabilities
+
+`public_address` returns the detected IP, used for example by `vagrant rdp`.
+`nic_mac_addresses` returns the MAC per VIF in VirtualBox format: adapter
+number (device + 1) to the MAC in upper case without separators.
+`forwarded_ports` returns host port to guest port for the running tunnels.
+
+## 10. Disks, cloud-init and synced folders
+
+`config.vm.disk` and `config.vm.cloud_init` work through the capabilities
+`configure_disks` and `cleanup_disks`. Synced folders use rsync, NFS or SMB,
+because Xen has no shared folders like virtiofs or 9p.
+
+### Disks
+
+| Vagrantfile | XAPI |
+| --- | --- |
+| `:disk, primary: true, size:` | `VDI.resize` of the VDI on `userdevice 0` while the VM is halted; only growing, shrinking is an error. The filesystem in the guest does not grow along (cloud-init `growpart` usually does) |
+| `:disk, name:, size:` | `VDI.create` on `sr` or on `xapi__sr: "..."`, `VBD.create` on the first free `userdevice` (`VM.get_allowed_VBD_devices`), plugged when the VM runs; marking `vagrant-xapi.disk = <name>`; if the disk exists and `size` is larger, resize |
+| `:disk, name:, file:` | Import the image through `/import_raw_vdi`; the format comes from the header (`vhd`, `qcow2`, or raw for `raw`/`img`); qcow2 is probed and converted when needed, as for boxes (section 7) |
+| `:dvd, file:` (local ISO) | Upload the ISO as raw VDI on `sr` (size rounded up to whole MiB, to the host that has the SR), attach as VBD type `CD` in a free CD slot (see below); if XAPI refuses a CD for a VDI on a normal SR, or no CD slot is free, attach it as a read-only disk instead (cloud-init's NoCloud finds the `cidata` volume on any block device). Without a free CD slot that gives a warning, except for the cloud-init ISO. When the ISO's SHA-256 changes, the VDI is replaced; the checksum comes from the digest cache (path, size, mtime), so an unchanged ISO is not hashed again on every boot |
+| `:floppy` | Not supported; validation error |
+
+`configure_disks` returns the disks with their VDI UUID, so Vagrant keeps them
+in its disk metadata (`data_dir/disk_meta`). `cleanup_disks` detaches and
+removes disks that left the Vagrantfile; it only destroys VDIs with this VM's
+marking (other disks are only detached). `validate_disk_ext`
+accepts `vhd`, `qcow2`, `raw` and `img`; the default is `vhd`; for new empty
+disks the SR decides the actual format. Disks larger than 2 TiB give a
+warning, because VHD-based SRs have that limit.
+
+**ISOs from an ISO SR.** Vagrant requires a local file for every `:dvd` disk,
+so ISOs that already live on an ISO SR are a provider option instead:
+`xapi.isos = ["debian-12.iso"]` (names or UUIDs). On create and on `reload`
+each one is attached as a CD drive whose VBD carries `vagrant-xapi.iso`;
+drives the plugin attached for ISOs that are no longer listed are removed.
+The ISO VDIs themselves are never destroyed, and CD drives the plugin did
+not attach are left alone.
+
+**CD slots.** Xen emulates four IDE devices for an HVM guest, in device
+slots (`userdevice`) 0-3, and a guest only sees CD drives there: the PV
+drivers leave CD drives to the emulation (Linux's xen-blkfront skips them in
+an HVM guest). XAPI accepts a CD drive in slot 4 or later, but the guest never
+sees it. So the plugin puts a CD drive only in a free slot 0-3. Slot 0 is the
+boot disk, extra disks take the first free slot, and many boxes bring an
+empty CD drive of their own, usually in slot 3 (`vagrant package` removes CD
+drives, so its boxes do not), which leaves one to three CD drives. An uploaded
+ISO without a free CD slot becomes a read-only disk (above); an ISO from
+`isos` without one is an error that lists what takes the slots. Extra disks
+keep the first free slot: moving them to slot 4 and up would change their
+names in the guest (`xvde` instead of `xvdb`). `vagrant xapi info` lists the
+slots.
+
+### Cloud-init
+
+1. The plugin uses a subclass of the built-in `CloudInitSetup` and runs it in
+   the *boot* steps, like VirtualBox. It builds the NoCloud ISO (label
+   `cidata`) with `user-data`, `meta-data` (`instance-id` from the machine id)
+   and, when VIF device 0 has a static `ip:`, a `network-config`, through the
+   host capability `create_iso`. With only network config and no user-data,
+   it still builds the ISO with an empty `#cloud-config`.
+2. `network-config` is version 2, matched on MAC: device 0 gets its static
+   address, `routes` to the `gateway` and `nameservers`; the other non-internal
+   VIFs without static IP get `dhcp4: true, optional: true` (cloud-init's
+   fallback DHCP is off once a network-config exists). Static addresses on
+   other devices are left to `configure_networks`.
+3. The ISO is written to `data_dir/vagrant-xapi-cidata-<sha>.iso` and reused
+   while its content (SHA-256 of all files) is unchanged
+   (`data_dir/xapi_cloud_init_iso`).
+4. `configure_disks` receives the ISO as `:dvd` named
+   `vagrant-cloud_init-disk`, uploads it and attaches it; when the content
+   changed, the VDI is replaced. The VDI belongs to the machine and is
+   removed on `destroy`.
+5. After boot the built-in `CloudInitWait` waits for
+   `cloud-init status --wait` (only with `config.vm.cloud_init` configs).
+   Vagrant's `cloud_init_first_boot_only` applies: after the first boot the
+   ISO is no longer in the config and `CleanupDisks` removes it.
+
+This works without Xen Orchestra, and with boxes without guest agent, as long
+as the box has cloud-init.
+
+### Synced folders
+
+- rsync always works, provided `rsync` is on the local machine; Vagrant installs it
+  in the guest when it can.
+- NFS needs the guest to reach the local machine. `PrepareNFSSettings` takes the
+  host IP as the source address of the route to the guest IP, found with a
+  UDP socket in Ruby (no `ip route` or `route get` as in the old plugin).
+  `PrepareNFSValidIds` returns the UUIDs of all VMs marked with this
+  installation's client id on this pool, plus the VM UUIDs of all xapi
+  machines in Vagrant's machine index (other pools, older markings), so
+  their exports are kept. That reads every VM record of the pool, so it
+  only runs for a machine with NFS folders (now or at its last boot);
+  without the list Vagrant's NFS cleanup prunes nothing.
+- SMB works when the guest can reach the local machine.
+
+For a folder without a type Vagrant picks the usable type with the highest
+priority. SMB (7) beats rsync and NFS (5) on every macOS and Windows host;
+it asks for credentials on each `up`, fails without a terminal, and needs
+the guest to reach the local machine. So when the Vagrantfile does not set
+`config.vm.allowed_synced_folder_types`, the provider sets it to
+`[:rsync, :nfs, :smb]` as soon as Vagrant loads the machine
+(`Provider#initialize`), before any command computes the types; rsync is
+then the default, also for vagrant-xenserver Vagrantfiles. A folder with an
+explicit type keeps it, and a Vagrantfile that sets the list keeps its own.
+Boxes made by `vagrant package` set the same list in their Vagrantfile.
+
+## 11. Snapshots and package
+
+All `vagrant snapshot` subcommands work, including `push` and `pop`.
+`vagrant package` makes an `xapi` box the plugin can import again.
+
+| Command | Behaviour | XAPI |
+| --- | --- | --- |
+| `snapshot save NAME` | Snapshot of the disks. With `snapshot_memory = true` and a running VM: checkpoint including memory. The snapshot gets `vagrant-xapi.snapshot_of = <vm uuid>`, its disks `vagrant-xapi.vm`. An existing name is an error | `Async.VM.snapshot` or `Async.VM.checkpoint` |
+| `snapshot list` and capability `snapshot_list` | Names from the VM's snapshots, sorted on `snapshot_time` (push and pop depend on that order) | `VM.get_snapshots` |
+| `snapshot restore NAME` | Like VirtualBox: halt first (forced), then revert. With `env[:snapshot_delete]` (pop) then delete; with `env[:snapshot_start]` (default) the *start* steps. A checkpoint comes back as `suspended` and is resumed | `Async.VM.revert` |
+| `snapshot delete NAME` | First the snapshot's VDIs (and suspend image), then the snapshot object; coalescing the VHD chain is done by the SM layer in the background | `VDI.destroy`, `VM.destroy` |
+
+`destroy` removes all snapshots of the machine.
+
+### Package
+
+The stack follows the VirtualBox provider and uses Vagrant's general package
+middleware (`PackageSetupFolders`, `PackageSetupFiles`, `Package`):
+
+1. Stop the VM (graceful, then hard), stop tunnels, `SyncedFolderCleanup`,
+   and remove disks an interrupted `vagrant xapi diff` left attached; that
+   and the export run under the diff lock of the VM.
+2. Make a temporary clone with `VM.clone`. From the clone remove CD drives and
+   uploaded ISOs (including the cloud-init ISO), all VIFs, all
+   `vagrant-xapi.*` keys of the VM and its disks, and the tag `vagrant`, so the
+   box takes nothing of this pool along.
+3. Export according to `package_format`:
+   - `:xva` (default): `GET /export?uuid=<clone>&use_compression=zstd`.
+   - `:vhd` or `:qcow2`: only disk 0, through
+     `GET /export_raw_vdi?vdi=<ref>&format=<fmt>`. Smaller, and usable outside
+     XAPI. A host that refuses the format gives a readable error.
+
+   Both get a `task_id`, and the task is waited for once the body is in: the
+   end of the stream does not say that the export on the host succeeded. A
+   body shorter than its `Content-Length` is an error too (Net::HTTP ignores
+   an early end by default).
+4. Remove the clone and its disks (never the original's).
+5. Assemble the box: `metadata.json` (`provider: "xapi"`, `format`,
+   `architecture: "amd64"`), `box.<format>`, and a Vagrantfile with
+   `firmware`, `cpus` and `memory` (read from the VM) as provider defaults,
+   plus `box_architecture = "amd64"` and
+   `allowed_synced_folder_types = [:rsync, :nfs, :smb]`. Vagrant core copies a
+   `--vagrantfile` to `include/_Vagrantfile` and `--include` files to
+   `include/`; the generated Vagrantfile loads `include/_Vagrantfile` at the
+   end, so it can override the defaults.
+6. Compress it with `bsdtar -czf`, as Vagrant does, but check the exit
+   status: Vagrant's own step ignores it, so a failure (e.g. a full disk) left
+   a truncated box and only `vagrant box add` noticed. On failure the box is
+   removed and the error shows bsdtar's message. The local disk needs room for
+   the exported image and the box together.
+
+Cleaning the guest for publication (SSH keys, machine-id) stays the user's
+job, as with other providers.
+
+## 12. The `vagrant xapi` command
+
+One command `vagrant xapi` with subcommands for what Vagrant core does not
+cover: insight, console, and cleanup of templates and orphaned VMs. It is
+registered with `command("xapi", primary: false)` (not shown in `vagrant -h`;
+the README documents it), uses `parse_options` and `with_target_vms`, and
+asks for confirmation before anything that removes, unless `--force` is
+given.
+
+| Subcommand | Purpose |
+| --- | --- |
+| `vagrant xapi info [vm]` | UUID, name, state, host, affinity, CPUs, memory, firmware, template, disks with SR, VIFs with IPs, snapshots (issue #57 of the old plugin) |
+| `vagrant xapi console [vm] [--port N] [--no-open]` | VNC console through the XAPI console tunnel (HTTP `CONNECT` to the console location, session as cookie) on `127.0.0.1`, and open the viewer (`open vnc://:<password>@127.0.0.1:<port>` on macOS; `xdg-open` with the URL without password on Linux, where the viewer asks for it). The proxy does the RFB handshake on both sides (`Services::Rfb`): towards the viewer it offers only VNC authentication with a one-time password of 8 characters, and only a viewer that knows it gets a connection to XAPI; towards XAPI, which offers no authentication of its own, it chooses None. After that the bytes pass through. For when the VM boots but SSH does not work |
+| `vagrant xapi adopt [vm] UUID [--force]` | Attach an existing VM to a machine that has none, or re-adopt the machine's own VM after the project moved; marks the VM and the disks that only it uses (a sharable disk, or one also attached to another VM, is never marked, so `vagrant destroy` cannot delete it). `--force` is needed for a VM without marking, and for a VM marked for another machine, project or installation (taking over someone else's VM) (issue #56) |
+| `vagrant xapi templates list` | Marked templates with box, version, provider, SR, size and number of clones |
+| `vagrant xapi templates prune [--keep N]` | Per box, provider and SR (by UUID: local SRs usually share the name "Local storage") keep only the newest N versions (default 1) |
+| `vagrant xapi templates remove NAME\|UUID` | Remove one template (by UUID, name, or `"<box> <version>"`) |
+| `vagrant xapi hosts [--plain\|--json\|--pem]` | The pool's hosts (`host.get_all_records`) with address, role (master or member), enabled, and the SHA-256 fingerprint of the certificate from `host.get_server_certificate`, so read through the verified connection to the master; ready to paste into `tls_fingerprint`. `--pem` prints the certificates. Used by acceptance scenario A5 to find a member and its fingerprints |
+| `vagrant xapi marked [--mine] [--project DIR] [--vm UUID] [--box NAME] [--plain\|--json]` | Every object in the pool with the plugin's marking (VMs, snapshots, templates, VDIs, internal networks, locks), of all users; the filters (repeatable, combined with "or") narrow it to this installation's VMs (`--mine`: same client id, or for older VMs the same login and hostname; with their snapshots, disks and the internal networks of their projects; not the shared templates), a project, a VM with its snapshots and disks, or a box's templates. Read through XAPI with the normal connection settings, so neither operators nor the acceptance scenarios need dom0 access |
+| `vagrant xapi diff [vm] --from SNAPSHOT [--to SNAPSHOT] \| --with MACHINE` | Files that differ between a snapshot and the running guest, two snapshots, or two running machines; see below |
+| `vagrant xapi orphans [--destroy]` | VMs of this Vagrant installation whose machine no longer exists: no machine in Vagrant's machine index (which knows custom `VAGRANT_DOTFILE_PATH`s) and no `.vagrant/machines/<name>/xapi/id` in the project has that VM's UUID. "This installation" means the same `vagrant-xapi.client_id`; VMs created before that key existed match on login name and local hostname. `--destroy` shuts each one down with a task, like `vagrant destroy`; one that cannot be removed is reported, the others still go, and the command exits with 1 |
+
+### `vagrant xapi diff`
+
+`vagrant xapi diff [vm] --from SNAPSHOT [--to SNAPSHOT]` lists the files
+that differ between a snapshot and the running guest, or between two
+snapshots; `--with MACHINE` compares two running machines (both of
+vagrant-xapi: another provider is refused). Snapshots are made
+with `vagrant snapshot save`, and the names are those of `vagrant snapshot
+list`. Vagrant only knows snapshots by name (save, restore, delete, list), so
+reading a snapshot's files goes through XAPI. Services: `Differ`
+(orchestration), `DiffDisks` (XAPI), `GuestFiles` (commands in the guest),
+`FileDiff` (comparison); the guest is reached through `Glue::GuestShell`,
+Vagrant's communicator with `sudo`.
+
+1. The machine must be running and its communicator ready: the files are
+   read in the guest. Everything from here on runs under the lock
+   `diff.<vm uuid>`, so a run never removes what another run on the VM is
+   using; `--with` takes the locks of both VMs, in the order of their names,
+   so that two runs on the same VMs cannot deadlock (one waits for the
+   other). The guest needs GNU findutils, coreutils and util-linux; a missing
+   tool is named. A temporary directory `/tmp/vagrant-xapi-diff.XXXXXXXXXX`
+   (0700, owned by the SSH user so that upload and download work; that user
+   can sudo anyway) holds everything the run writes.
+2. Before anything is attached, snapshot mounts and LVM devices an
+   interrupted run left in the guest are removed, with the directories of
+   interrupted runs (also those without a mount left), and then their disks
+   in the pool (see Leftovers). A directory only counts as a run's when it
+   is a real directory, not a symlink, owned by root or the SSH user, as the
+   run made it; `/tmp` is sticky, so after that check no other user can
+   rename or replace it. What another user of the guest made under such a
+   name is left alone, with its mounts. Only after that, so that a
+   leftover copy cannot block every later run, the live layout is read
+   (`findmnt -r`: mount point, device, type, file system UUID, mount options;
+   no bind mounts, loop devices, media or snapshot mounts of runs; of two
+   mounts on one mount point only the one mounted last, which hides the
+   other, so a file system below a tmpfs, bind or loop mount is not
+   compared at all), and
+   storage whose identifiers must not appear twice and cannot be renamed is
+   refused (`lsblk`: LUKS, btrfs, ZFS, RAID, other device-mapper targets).
+   With LVM, the LVM tools are checked here, before anything is attached.
+   Then a temporary udev rule (`/run/udev/rules.d/99-vagrant-xapi-diff.rules`)
+   keeps udev and systemd on the guest's own devices: a copy has their file
+   system and GPT partition UUIDs, so udev could point
+   `/dev/disk/by-uuid/...` at the copy and systemd tie the device unit of
+   that name to it, and a mount from fstab by `UUID=` (`/boot`,
+   `/boot/efi`, `/home`) is bound to its device unit (`BindsTo=`, or
+   `StopPropagatedFrom=` in newer systemd), so it could be unmounted when
+   the copy is detached. The rule gives every new block device with one of
+   the live identifiers (`lsblk -o KNAME,UUID,PARTUUID`, strictly checked)
+   `SYSTEMD_READY=0`, so systemd ignores it, and `link_priority=-100`, so
+   the links stay on the guest's device. The copies are mounted by kernel
+   name, and systemd binds no mount it only learns from
+   `/proc/self/mountinfo` to its device. Without `udevadm` nothing is done;
+   a failure is reported and the run goes on. The rule goes after the
+   copies (step 10), or with the next run's cleanup.
+3. Every disk of the snapshot with file systems is cloned with `VDI.clone`
+   (copy-on-write on VHD and qcow2 SRs). CD drives, read-only disks and
+   uploaded ISOs (such as the cloud-init ISO) are skipped. The clone is not
+   cancellable: a clone cancelled half-way could exist without marking;
+   Ctrl-C takes effect right after it. When waiting for it fails anyway
+   (`task_timeout`, or a lost connection), XAPI may still finish the clone
+   without marking. The VDIs that were not there before and look like a
+   clone of the source (its name, SR and `other_config`, no VBD, not a
+   snapshot) are then marked and removed; when there is none yet, the user
+   is told how to find a clone that appears later. A clone is named first
+   (`vagrant-xapi diff of <vm uuid>`), because the name is how a clone
+   without VBD is found again, and gets `vagrant-xapi.diff` right after
+   that, so a run that dies from then on leaves a clone that the next run or
+   `destroy` finds. `VDI.clone` copies `other_config`, so the clone usually
+   carries `vagrant-xapi.vm` of this VM already; it is only written when it
+   differs, so it is never missing in between, and a clone with the name and
+   `vagrant-xapi.diff` but no `vagrant-xapi.vm` yet (a run that died while
+   marking it) counts as a leftover of this VM too. The clone's other
+   `vagrant-xapi.*` keys (disk name, cloud-init, checksum) are removed;
+   otherwise it could be taken for one of the VM's own disks.
+4. The clone is attached read-write and plugged into the running VM. XAPI
+   refuses read-only disks for HVM guests
+   (`DISK_VBD_MUST_BE_READWRITE_FOR_HVM`), and a writable device lets the
+   guest replay the journal of the crash-consistent snapshot. Plugging into a
+   running VM needs PV drivers reported by a guest agent. The device name
+   comes from `VBD.device`, which XAPI fills in from the xenopsd event; for
+   an HVM guest that may be `hdX` or `sdX` while Linux's blkfront shows the
+   disk as `xvdX`, so both names are tried.
+5. In the guest the plugin waits for every attached disk and checks its size
+   against the VDI (it never mounts a device it cannot identify). A snapshot
+   disk with LUKS, btrfs, ZFS or RAID (the layout may have changed since the
+   snapshot) stops the run. LVM on the copies is imported (see LVM below).
+   Then the file systems on the disks and on the copies' logical volumes are
+   read with `lsblk -r`. Each is paired with the live one with the same UUID,
+   which says where it belongs, and mounted below the temporary directory
+   with `ro,nosuid,nodev,noexec` (it is only read; old setuid binaries and
+   device nodes of the snapshot stay unusable), XFS also with `nouuid`.
+   vfat stores no owners or permissions, and the names it shows depend on
+   the mount options, so a vfat copy gets the `uid`, `gid`, `umask`, `fmask`,
+   `dmask`, `codepage`, `iocharset`, `shortname`, `utf8` and `uni_xlate`
+   options of its live partner (values from the guest, so only those that
+   pass a strict check); otherwise every file in `/boot/efi` would show a
+   mode change, and a name with other characters a removal and an addition.
+   File systems without a live
+   partner, of another type than ext2/3/4, XFS and vfat, or with a UUID
+   already seen on another disk of the snapshot are skipped with a warning.
+   So is, the other way round, a live file system the snapshot does not
+   have at all (e.g. a disk added and mounted since), and with two
+   snapshots one that neither has: it is not compared, and its mount point
+   stays left out of the tree above it.
+   A logical volume with extents on two copies is listed under both disks
+   and taken once, without a warning. Two snapshots are both paired with the
+   live layout.
+6. Both sides are listed with `find -xdev -printf` (type, mode, owner, size,
+   mtime, link target and path, NUL-separated) into files that are
+   downloaded: Vagrant's SSH communicator strips escape sequences from
+   stdout. The current state is the live tree, not a new snapshot, because a
+   snapshot misses writes still in the page cache. A snapshot file system is
+   mounted on its own, so it shows files the running guest has hidden below
+   another mount point (e.g. under `/home` when `/home` is a file system of
+   its own). A live mount point nested in a tree, and what lies below it, is
+   therefore left out of that tree on every side: the entry of the mount
+   point differs per side (live `find -xdev` shows the root of the mounted
+   file system, e.g. `/proc` as 0555; the snapshot the empty directory below
+   it), and a live tree would show the content of a bind mount of the same
+   device. The root of each file system (find's `.`) is compared under its
+   mount point, so a mode or owner change of `/` or of `/home` on its own
+   file system is reported. A full `/tmp` in the guest cuts a listing off at
+   any point, and every file after the cut would show as added or removed.
+   So a listing ends with an end field written after find, which a full
+   `/tmp` cuts off as well, also when the cut falls between two records;
+   find runs in the C locale and must not report a write error, nor fail
+   without naming a path it could not read. Otherwise the run stops
+   (`diff_listing_invalid`); paths find names on stderr are counted as read
+   errors and reported with a warning.
+7. With `--path`, find starts at that path inside the file system it belongs
+   to (the deepest mount point above it), and only for paths that pass a
+   strict character check; other paths list the whole file system and the
+   filter narrows the result. So does a path with a symlink in a directory
+   above it (its `realpath` in the guest is not where the path says): the
+   kernel would follow it, and in a snapshot an absolute link points into
+   the running system. As without `--path`, nothing below a symlink matches;
+   a path that is a symlink itself is compared as the link.
+8. The comparison runs on the local machine. As in rsync's quick check, files
+   with the same size and mtime count as equal; same-size files with another
+   mtime are hashed in the guest (`sha256sum`, the paths in an uploaded
+   file), so a file that was only touched is not reported. Right before
+   hashing, a shell loop of builtins keeps only the paths that are still a
+   regular file and not a symlink, and one `sha256sum` per batch reads them:
+   a path that changed type since it was listed is neither followed nor
+   waited on. `sha256sum -z` (coreutils 8.30 and later) keeps names as they
+   are; older ones escape them. `--checksum` hashes every regular file.
+   Changes: `A` added, `D` removed, `M` other
+   content (link target for symlinks; possibly also mode or owner), `m` mode
+   or owner only, `T` another type. Device nodes are compared by type, mode
+   and owner only: find prints no device numbers, so a changed major or
+   minor number is not reported.
+   With `--content`, while the snapshot copies are still mounted, the guest
+   copies both versions of every added, removed or changed regular file up
+   to `--content-limit` (default 1 MiB) as root into the temporary
+   directory: the paths come in an uploaded NUL-separated file and reach the
+   shell only as arguments (`xargs -0 sh -c '...' dir limit budget`),
+   symlinks are not followed (`[ -f ] && [ ! -h ]`), and `head -c` caps each
+   copy at one byte more than the limit: a file that grew past the limit
+   since it was listed is not shown cut off but named with its size. A file
+   with a NUL byte in its first 8000 bytes counts as binary:
+   the guest only marks it and does not copy it. Each side copies at most
+   16 MiB in all (`ContentDiff::BUDGET`, or one file of the limit if that is
+   larger), in the order of the list; xargs may start `sh` more than once,
+   so the bytes used so far are kept in a file. Without that budget a diff
+   after a large upgrade would fill the guest's `/tmp`, often RAM. One tar
+   archive per side is downloaded and read with RubyGems'
+   `Gem::Package::TarReader`; the copies are removed as soon as the archive
+   is made, also when tar fails, and the cleanup of the temporary directory
+   removes those of an interrupted run. The local machine's `diff -u` makes
+   the unified diff (labels `a/<path>` and `b/<path>`, `/dev/null` for an
+   added or removed file). The output goes to a terminal, so invalid bytes
+   and control and format characters other than tab and newline are written
+   as `\xHH` or `\u{HHHH}`, as in paths: a file in the guest cannot send
+   escape sequences, also not 8-bit C1 ones such as U+009B, and cannot
+   reorder the output with bidi characters. Larger, binary, unreadable and
+   files beyond the budget are named with the reason, and so is a file whose
+   two copies turn out the same (when hashing it failed on one side). A
+   local `diff` that fails or is killed by a signal stops the run instead of
+   showing what it wrote so far. With two machines each version is copied in
+   its own guest.
+9. `--path DIR` limits the comparison; `.` and `..` in it are resolved
+   lexically, as a listing has none. `--exclude PATTERN` leaves out a path
+   when the path itself or one of its parent directories matches the glob
+   (`*` also matches `/`). A pattern that does not start with `/` matches at
+   any depth, as in rsync: `node_modules` leaves out every file or directory
+   of that name. Default excludes: `/tmp`, `/var/tmp`, `/var/cache`,
+   `/var/log` (logs change all the time, e.g. `lastlog` and `wtmp` at every
+   login), `/var/lib/systemd/random-seed` and `/usr/src` (kernel headers and
+   module sources that every kernel update replaces);
+   `--no-default-excludes` compares them too. The temporary directory is
+   always left out.
+10. Afterwards, also after errors and Ctrl-C: unmount (lazily as fallback),
+    deactivate the copies' volume groups, unplug, destroy VBD and clone,
+    remove the udev rule, and remove the temporary directory (only
+    plain files in it and empty directories, so never anything below a
+    mount). Unplug runs as a task without cancel and with a timeout of two
+    minutes; when the guest refuses or the unplug does not finish, the clone
+    is forced off (`VBD.unplug_force`): it is a throwaway copy, and a copy
+    left attached is worse.
+11. With `--with`, nothing is attached: what interrupted runs left in either
+    guest is removed as in step 2, and both machines' live file systems are
+    paired by mount point and listed in place. The mount points of both
+    machines are left out on both sides (step 6): a path that is a file
+    system of its own on only one machine is named and not compared, instead
+    of showing as all added on one side.
+
+**LVM.** A copy of a PV has the PV and VG UUIDs and the VG name of the
+running guest's, so LVM would see duplicates and could not activate it.
+After all disks of a snapshot are attached (a VG may span disks), the plugin
+gives each VG on the copies new identifiers and a name of its own,
+`vagrant_xapi_diff_<run>_<side><n>`, with `vgimportclone` (all PVs of a VG
+together), and activates it. The copies' file systems keep their UUIDs, so
+they pair with the running guest's logical volumes as before. Rules:
+
+- Every LVM command only sees the copies: `--devices` for each of their PVs
+  (lvm2 2.03.12 and later; it also bypasses a devices file such as RHEL's
+  `system.devices`), and always a `filter` and `global_filter` that accept only
+  those PVs (a restrictive `global_filter` in `lvm.conf` would hide them, and
+  older lvm2 has no `--devices`). The running guest's PVs are never read or
+  written.
+- No trace in the running system: no metadata backups or archives
+  (`backup { backup = 0 archive = 0 }`, otherwise `/etc/lvm/backup` and
+  `/etc/lvm/archive` would change, and show up in the next diff), no change
+  to the devices file (no `--importdevices`), and activation limited to the
+  copy's VG (`activation { volume_list = [...] }`, which also overrides a
+  `volume_list` in `lvm.conf` that would refuse it).
+- udev may activate a copy when it appears, if the running guest has no VG
+  of that name. Before importing, the plugin removes the device-mapper
+  devices that sit on the copies' disks (from `lsblk` of those disks), never
+  by VG name, so never a logical volume of the running guest.
+- Cleanup deactivates the copies' VGs (`vgchange -an`) before the disks are
+  detached; a device that is still open is removed with `dmsetup remove
+  --deferred` as soon as it is closed. Device-mapper devices with the prefix
+  `vagrant_xapi_diff_` that a killed run left are removed by the next run,
+  under the lock.
+- Needs lvm2 in the guest (`lvm`, `pvs`, `vgchange`, `vgimportclone`,
+  `dmsetup`); a missing tool is named. Shared VGs (lvmlockd) fail with the
+  error of `vgimportclone`.
+
+**Leftovers.** A killed run leaves marked clones. While one is attached, the
+guest has two disks with the same file system UUIDs, so a reboot from inside
+the guest could mount the copy. They are removed by the next `diff` (under
+the lock), before every boot (`RemoveDiffDisks` in the boot steps, before the
+disk steps, so these never number around a leftover; only VBDs of the VM, no
+pool-wide search), before `package` exports, and on `destroy` (also clones
+without VBD, found by name and checked by marking; best effort, so that a
+destroy or the rollback of a failed create never fails on this search). Boot
+and `package` take the diff lock of the VM for it, waiting at most five
+minutes: a diff still running there (the VM was halted under it) keeps its
+disks, and none is attached while a box is made. A VBD marked
+`vagrant-xapi.diff` is always removed; its VDI only when that is marked as a
+diff clone of this VM. A copy that is still attached afterwards (XAPI refused
+to unplug or destroy it) stops the boot and `package` with an error that says
+how to remove it: the guest could mount or boot from it, and a box would take
+it along without marking. `destroy` tries a copy it could not remove again
+once the VM and its VBDs are gone; nothing looks for a copy of a destroyed VM
+later, so one that still cannot be removed is named with its UUID, how
+`vagrant xapi marked --vm` finds it and how `xe vdi-destroy` removes it.
+
+**Guest data.** Paths, link targets and error output come from the guest.
+Control characters, format characters (zero-width, bidirectional, soft
+hyphen, byte order mark), line and paragraph separators and invalid UTF-8 are
+escaped before they reach the terminal or JSON, unambiguously: `\xHH` is an
+ASCII control character or a byte that is not UTF-8, `\u{H}` a character,
+`\\` a backslash. Only values the plugin created or checked go into commands
+in the guest: the temporary directory, kernel device names, file system
+types, VG names (the copies' own, and those `pvs` reports, checked against
+LVM's character set), and mount points and `--path` values that pass a
+strict character check (live mount points that do not are skipped with a
+warning).
+File paths never go into a command; they travel in files. `--plain` prints
+`kind<TAB>path<TAB>detail`; `--json` an object with `compared` (mount
+points), `read_errors` (the number of paths that could not be read, so a
+script can tell an incomplete result) and `changes`. With either, progress is dropped and
+warnings go to stderr.
+
+Templates are shared by all users of a pool. `prune` and `remove` therefore
+show which other users have clones of a template before asking for
+confirmation. Templates and orphans need a connection: they use the first
+machine of the Vagrantfile in the current directory that uses the xapi
+provider.
+
+## 13. Security
+
+The plugin talks to a hypervisor pool, often with root rights. These rules
+apply without exception:
+
+- **TLS.** Certificate checks are on by default and cannot be turned off.
+  Self-signed certificates go through `tls_fingerprint` or `tls_ca_file`.
+  There is no `insecure` option.
+- **Secrets.** Password and `session_id` never appear in logs, error messages,
+  URLs or process arguments. The client also filters them from
+  `VAGRANT_LOG=debug`. Credentials may come from environment variables, so
+  they are not in a Vagrantfile in git.
+- **Box content.** Files named by a box must stay inside the box directory
+  (symlinks resolved), and qcow2 images with a backing file or external data
+  file are refused, so a box cannot make the plugin upload files from the
+  local machine. A box's own Vagrantfile is Ruby that Vagrant runs anyway, so boxes
+  remain trusted code; this protects users who ignore box Vagrantfiles.
+- **Subprocesses.** External commands (`ssh` for tunnels, `qemu-img`,
+  `open`/`xdg-open`) always run with an argv array (`Process.spawn` or
+  `Vagrant::Util::Subprocess`), never through a shell string. The old plugin
+  used backticks with paths in them. The SSH ProxyCommand (run by ssh through
+  a shell) only contains a host address and user that passed a strict
+  character check.
+- **Console.** `vagrant xapi console` listens on `127.0.0.1` only and asks
+  viewers for a one-time VNC password before it opens the console tunnel,
+  so other local users cannot watch. VNC authentication is weak (DES), but
+  it only guards a local port for as long as the command runs. The password
+  is shown in the terminal. On macOS it is also passed to `open` in the URL
+  for Screen Sharing; `open` exits at once, so it is only briefly in the
+  process list. On Linux it stays out of the URL: `xdg-open` starts the
+  viewer with the URL in its command line for the whole session, readable
+  by every local user, so the viewer asks for it instead. A Ruby without
+  3DES gets a warning and a console without password.
+- **Cleanup.** Destroy, prune and orphans only touch objects with the plugin's
+  marking. `adopt` of an unmarked VM needs `--force`.
+- **dom0.** SSH to dom0 (`ssh_via_host`, HIMN) uses normal host key checking.
+- **Guest file systems.** `vagrant xapi diff` mounts a snapshot's file
+  systems only in the guest they came from, never in dom0 or on the local
+  machine. Names from the guest are escaped before they are shown, and only
+  checked values go into the commands it runs in the guest.
+- **Downloads.** An `xva_url` with `http://` gives a warning, because the host
+  then downloads the image unencrypted.
+- **Least privilege.** `pool-admin` is enough; the README says what
+  `vm-admin` may lack.
+- **Supply chain.** No runtime gems. Development gems (Vagrant, rspec,
+  webmock) are only in the Gemfile.
+
+## 14. Testing and acceptance
+
+A change is done when the unit tests are green and the acceptance scenarios
+it affects pass on a XenServer 8 or XCP-ng 8.3 pool.
+
+### Layers
+
+- **Unit (rspec)**, `spec/unit`, against `spec/support/fake_xapi.rb`: an
+  in-memory pool behind WebMock that answers JSON-RPC (generic accessors for
+  every class plus the specific calls the plugin uses) and the HTTP transfer
+  handlers, and can inject XAPI errors.
+  - `api/`: login, `HOST_IS_SLAVE` (also refused with a pin), `SESSION_INVALID`
+    (one re-login for many threads), error format, tasks (event.from and
+    polling, cancel, timeout, progress), secrets in logs and URLs, session
+    registry; transfer host selection, member certificate pinning, following
+    302s on downloads, the qcow2 probe, no `Expect` header, untrusted guest
+    IPs; real TLS against a local server for CA, pin and wrong pin.
+  - `services/`: disk image headers, box sources, digest cache, lock
+    semantics (including takeover races and in-process waits), template cache (one import, qcow2 and fallback, interrupted
+    import, two processes racing), VM building, network planning and internal
+    networks, IP detection, power, snapshots, destroy (cleanup rule), export,
+    inventory, disks, tunnels, file comparison, and `diff` (snapshot clones,
+    guest commands, cleanup after errors and Ctrl-C, leftovers) against an
+    in-memory guest (`spec/support/fake_guest.rb`).
+  - `vagrant/`: config defaults and validation, error texts for every key,
+    and the real Vagrant action stacks (`up`, `halt`, `reload`, `suspend`,
+    `resume`, snapshots, `package`, `destroy`, disks and cloud-init) in a
+    real `Vagrant::Environment`, plus the subcommands. Only the SSH
+    communicator and the guest are stubbed.
+- **Acceptance scenarios** against a real pool, as a script
+  (`test/acceptance/scenarios.sh`), not vagrant-spec (section 15).
+
+### Acceptance scenarios
+
+| # | Scenario |
+| --- | --- |
+| A1 | `vagrant up --provider=xapi` with only host and login, and an XVA box of the old plugin: SSH works within `boot_timeout` |
+| A2 | A libvirt box without guest agent, with static IP via cloud-init: SSH works |
+| A3 | Two processes run `vagrant up` at the same time with the same new box: one imports, the other waits for the template lock and then uses that template; exactly one template is created |
+| A4 | Ctrl-C during the template import: no half template, and no VM or VDI in the pool that was not there before (an interrupted import is not marked yet); the next `up` succeeds |
+| A5 | Connecting to a pool member: with a pin on its certificate only a readable refusal naming the master; with the pins of all hosts automatically on to the master; `vagrant xapi console` of a VM on the member returns its screen |
+| A6 | `halt`, `reload` with changed CPUs and memory, `suspend`, `resume`, `halt`, `up`: the state is right each time, the change shows in the guest, and `vagrant ssh` fails while the VM is suspended or halted |
+| A7 | Extra disk, bigger primary disk and three ISOs via `config.vm.disk`; after `reload` all are visible in the guest, the first ISO as a CD drive; an ISO without a free CD slot (0-3) is a read-only disk with a warning, and no CD drive is in slot 4 or later |
+| A8 | `snapshot push`, change, `snapshot pop`: the change is gone |
+| A9 | `package`, `box add`, `up` from the new box; then the same again with that box, packaged as qcow2 |
+| A10 | UEFI with Secure Boot and vTPM, from a box built for UEFI: the guest boots with UEFI, Secure Boot is on and it sees the TPM |
+| A11 | Multi-machine on a `private_network`: the machines ping each other |
+| A12 | `forwarded_port` 8080 to 80 with `auto_correct`: `curl` on the port `vagrant port` shows works, after `halt` the tunnel is gone |
+| A13 | `destroy` leaves no marked objects (checked with `vagrant xapi marked --project <dir> --vm <uuid>`) |
+| A14 | Wrong password, unreachable host, full SR, unknown network: each gives a readable message, never a stack trace |
+| A15 | An unchanged vagrant-xenserver Vagrantfile (provider `:xenserver` with `xs_*` options, VirtualBox as second choice, triggers that use `XenApi::Client`): `vagrant up` picks `:xenserver` and says the compatibility is in use and the XenApi stand-in temporary, the trigger's extra disk shows in the guest and is gone after `destroy`; then the Vagrantfile moves to `:xapi`, `vagrant xapi migrate` moves the machine, and `destroy` removes the trigger's disk too |
+| A16 | `vagrant xapi diff`: a snapshot against the running guest and against a second snapshot lists exactly the added, changed and removed files and no mount points such as `/proc`; `--content` shows the line added to `/etc/hosts`; afterwards no marked object, disk, mount or udev rule of the diff is left, and the guest has the same mounts as before; optionally on another SR (`XAPI_DIFF_SR`) |
+| A17 | `vagrant xapi diff` on a guest with its root file system on LVM, with `XAPI_BOX_LVM`: the change is listed; afterwards the guest's volume groups are unchanged, and no LVM device or metadata backup of the copy is left |
+| A18 | A Vagrantfile as `vagrant init` writes it: `up` without a terminal syncs the default `/vagrant` folder with rsync and asks nothing; the guest can write to it, `vagrant rsync` brings a change across, after a reboot of the guest SSH comes back with the folder intact; `vagrant xapi info` shows the VM |
+| A19 | Optional, with `XAPI_XVA_URL`: a box of vagrant-xenserver with only `xva_url`; the host imports the XVA from the URL |
+
+A3, A4, A13 and A14 are also covered by unit tests against the fake XAPI;
+the scenarios prove them against real XAPI.
+
+## 15. Decisions
+
+| Decision | Reason |
+| --- | --- |
+| Support both XenServer 8 and XCP-ng | Both use XAPI; differences are detected at runtime |
+| The gem is published on rubygems.org; the repository stays private for now | `vagrant plugin install vagrant-xapi` and `vagrant plugin update` work as for any plugin, without the GitHub CLI or access to the repository. The source is public through the gem (MIT). While the repository is private the gemspec has no homepage or source links, which would only lead outsiders to a 404, and `docs/*.md` ship in the gem, so that the README and the code comments that point there still lead somewhere; add the links when the repository becomes public. Version 0.0.1 is a placeholder without code that held the name. GitHub Packages was not an option: it needs a classic personal access token per user, even to install, and Vagrant keeps the source URL with that token in plain text in `~/.vagrant.d/plugins.json` |
+| No boxes of our own | Teams use existing `xapi`, `xenserver` or `libvirt` boxes or build one; `docs/operations.md` describes building one with packer-plugin-xenserver |
+| The console proxy asks viewers for a one-time VNC password | XAPI's console has no authentication of its own; without a password any local user could connect to the forwarded port, and macOS Screen Sharing always asks for one. The password goes into the vnc:// URL |
+| VNC's DES through OpenSSL's 3DES with the key three times | OpenSSL 3 keeps single DES in its legacy provider, which Vagrant's Ruby does not load; 3DES with one key three times is the same cipher and is in the default provider |
+| No Xen Orchestra, not even optional | No extra component or dependency for users |
+| Name: gem `vagrant-xapi`, provider `:xapi` | Neutral for both platforms; free on rubygems; no clash with `:xenserver` |
+| Ruby plugin, no Go | vagrant-go was removed from Vagrant (GH-13622) |
+| No runtime gems | Avoid the old plugin's load problems and keep the supply chain small |
+| License MIT | Like vagrant-xenserver and Vagrant itself |
+| `vagrant xapi` hidden from `vagrant -h` (`primary: false`) | The README documents it |
+| Migration guide in the README (`xs_*` to the new options, `use_himn` to `ip_detection`) | Users of vagrant-xenserver must be able to switch without the old docs |
+| Provider registered with `defaultable: false` | It needs a remote pool and credentials; Vagrant should only pick it when the Vagrantfile configures `:xapi` or `--provider=xapi` is given |
+| `CloudInitSetup` runs in the boot steps, not only on the first `up` | Same as VirtualBox, so `cloud_init_first_boot_only = false` works; the ISO is cached on its content |
+| MAC addresses are kept per device when VIFs are rebuilt | A cloud-init `network-config` matches on MAC; a new MAC after `reload` would break the static IP |
+| Forwarded ports bind to `127.0.0.1` by default | Safer than all interfaces; `host_ip:` can widen it |
+| `tls_verify = false` is only accepted together with a fingerprint | There is deliberately no insecure mode; a pin is the safe alternative for self-signed certificates |
+| The HIMN VIF is only added with `ssh_via_host` | HIMN is only reachable from dom0; without the proxy it is useless and only adds a NIC |
+| Uploaded ISOs are attached as CD, with a read-only disk as fallback | Not every SR may accept a CD VBD for one of its VDIs; NoCloud finds `cidata` on any block device |
+| qcow2 support is probed with an empty PUT on a scratch VDI | XAPI has no API to ask for it. Trying the real upload does not work: XAPI never answers `Expect: 100-continue`, and without it a refused upload is only noticed after streaming the whole file |
+| HTTP transfers go to a host that has the SR attached | XAPI redirects (302) otherwise, and a streamed PUT cannot follow a redirect |
+| Pool members are reached with the certificate the master reports for them | A pin or a hostname check made for the master does not match another host |
+| `tls_fingerprint` may hold several pins | One pin cannot cover a redirect from a member to the master, nor a change of master; the self-signed certificates of XCP-ng and XenServer do not contain the IP addresses XAPI redirects to, so a CA file does not help either |
+| Guest-reported IPs must be bare IP literals | They are written by the guest and end up in a shell (ProxyCommand) and in NFS exports |
+| `destroy` checks that the VM is marked with this machine and project | A copied project directory must not destroy the original project's VM |
+| Orphans match on a random installation id, not only on login and hostname | Login and hostname collide across containers, CI runners and identically named machines |
+| ISOs from an ISO SR are a provider option (`isos`), not a `:dvd` disk | Vagrant's config validation requires a local file for every `:dvd` disk |
+| PV boxes are switched to HVM on import instead of refused | Old-plugin boxes often only used pygrub for convenience; the warning explains the risk |
+| `up` of a running VM runs `Provision` after the message | So `vagrant up --provision` works, like VirtualBox |
+| Internal networks place their VMs with `VM.start_on` the host of a running peer, not affinity, and store no host | Affinity is only a preference, and VMs on different hosts could not reach each other; a stored host goes stale when it goes offline |
+| Locks are kept alive with heartbeats and use the master's clock | An import may outlast any fixed TTL; the clocks of the machines running Vagrant differ |
+| Templates get no user configuration (firmware is set per VM) | A template is shared; one user's choice must not become another user's default |
+| `destroy` checks ownership before halting; `adopt` of another owner's VM needs `--force` | A copied project or a mistyped UUID must not stop or take over someone else's VM |
+| `destroy` refuses an unmarked VM | Even with an id file pointing at it, an object the plugin did not create or adopt must stay |
+| `vagrant xapi diff` mounts snapshot disks in the guest itself | The guest wrote these file systems; parsing them in dom0 or on the local machine would cross a trust boundary. No helper VM, box or download is needed |
+| `diff` reads snapshots through XAPI, not by `vagrant snapshot restore` | Restoring halts and boots the VM twice, and the boot steps write to the guest (synced folders, hostname, cloud-init), which pollutes the result |
+| The current state in `diff` is the live tree, not a temporary snapshot | A snapshot misses writes still in the page cache; the live tree is what `vagrant ssh` shows |
+| Snapshot clones are attached read-write | XAPI refuses read-only disk VBDs for HVM guests; a writable throwaway device lets the guest replay the journal of a crash-consistent snapshot |
+| `diff` renames LVM on the copy with `vgimportclone` | Its identifiers would appear twice next to the running system; the copy is a throwaway clone, so changing it costs nothing, and LVM limited to the copy's devices never touches the running guest's |
+| `diff` refuses LUKS, btrfs, ZFS and RAID | Their identifiers would appear twice next to the running system, and the plugin does not rename them |
+| `diff` deactivates a copy that udev activated by its devices, not by VG name | With a name, a copy and an active logical volume of the running guest cannot be told apart; the devices on the copy's disks can |
+| `diff` downloads listings as files instead of reading stdout | Vagrant's SSH communicator strips escape sequences from stdout |
+| `diff` takes the lock of the VM (with `--with` of both VMs) before it touches the guest | Leftover mounts and directories in the guest can only be removed safely when no other run on that VM is using them |
+| `diff` forces a clone off when a clean unplug fails or hangs | It is a throwaway copy; left attached, the guest has two disks with the same file system UUIDs |
+| Acceptance tests are our own scenarios, not vagrant-spec | On a real pool 8 of vagrant-spec's 20 provider tests failed. Seven assume a hypervisor on the local machine or a particular box: VirtualBox's device names (`/dev/sda`, `/dev/sr3`), a guest reachable from the local machine on a private network, Python 2's `SimpleHTTPServer` in the box, a guest that is back 10 seconds after a reboot. `disk/dvd` found the box's own empty CD drive at `/dev/sr0`, and `disk/dvd_multiple` that a guest sees at most three CD drives, which showed that the plugin put CD drives where the guest cannot see them (section 10, "CD slots"; fixed). What they covered beyond our scenarios is now in A18, A6 and A9: the default synced folder (where they found Vagrant choosing SMB), `vagrant ssh` while the VM is suspended or halted, and packaging a packaged box. vagrant-spec has no releases and needed two workarounds to run on Ruby 3 |
+
+## 16. Verified against a real pool
+
+The calls, parameters, record fields, the JSON-RPC error format
+(`error.message` as code, `error.data` as parameters), int64 values as JSON
+numbers, `event.from` on a single task, `task_id` and cookie authentication
+on the HTTP handlers, the format names `raw`/`vhd`/`qcow2`,
+`use_compression=zstd` and the redirect behaviour of the handlers were first
+checked against the xen-api source (`api_server.ml`, `xapi_http.ml`,
+`import.ml`, `import_raw_vdi.ml`, `export.ml`, `importexport.ml`). The
+acceptance scenarios A1-A18 have since all passed in one full run on an
+XCP-ng 8.3 pool of two (nested) hosts. Besides the normal
+lifecycle that covers the upload of a qcow2 disk image of a libvirt box
+(A2), the CD slots (A7: with a box that has its own empty CD drive in slot 3
+and a data disk in slot 1, the first ISO was a CD drive in slot 2,
+`/dev/sr0`, and the two without a slot read-only disks in slots 4 and 5,
+`/dev/xvde` and `/dev/xvdf`, all three found by their label),
+`host.get_server_certificate` and the console `CONNECT` through a member
+host (A5: a VNC handshake through `vagrant xapi console` with a VM on that
+member), the default `/vagrant` folder over rsync and a guest reboot (A18),
+packaging a packaged box, also as qcow2 through
+`/export_raw_vdi?format=qcow2` and up again from that box (A9), and for
+`vagrant xapi diff` the plug of a cloned snapshot disk into a running guest
+with its device name, on an `lvm` and an `nfs` SR (A16, once with
+`XAPI_DIFF_SR`) and with LVM on one guest (A17). Since `package` waits for
+the export's task, A9 has passed again: `/export` and `/export_raw_vdi`
+finish the task passed as `task_id` once the body is complete. A4 has passed
+again with the comparison of all VMs and VDIs of the pool: the interrupted
+import left nothing behind.
+
+## 17. Compatibility with vagrant-xenserver
+
+Vagrantfiles written for vagrant-xenserver keep working, with everything
+that plugin did. That is permanent: teams switch plugins without touching
+their Vagrantfiles, and `:xapi` is for new Vagrantfiles and the options
+vagrant-xenserver never had. Only the stand-in for the `xenapi` gem, which
+triggers in such Vagrantfiles use, is temporary.
+
+### Permanent: lib/vagrant-xapi/xenserver
+
+| Part | File | Behaviour |
+| --- | --- | --- |
+| Provider `:xenserver` | `xenserver/plugin.rb`, `xenserver/provider.rb` | The `:xapi` provider under the old name, with the same capabilities and box formats. Not defaultable, like `:xapi`; Vagrant still picks it when a Vagrantfile configures it (`config.vm.provider "xenserver"` before `"virtualbox"`). Says once per run that the compatibility is in use. Not registered when vagrant-xenserver is installed too |
+| `xs_*` options | `xenserver/config.rb` | `xs_host`, `xs_username`, `xs_password`, `name`, `memory`, `api_timeout`, `xva_url` map to the new options; every `:xapi` option works as well. HTTPS always: the old default port 80 becomes 443, `xs_use_ssl` is ignored. `use_himn` becomes `ip_detection = [:himn]` with `ssh_via_host`. `pv` is ignored with a warning. After finalize the `xs_*` readers return the values in effect (`xs_use_ssl` true, `xs_port` the HTTPS port), for code in Vagrantfiles that reads them |
+| Takeover | `xenserver/takeover.rb` | A machine whose id is an OpaqueRef was created by vagrant-xenserver. The first `state` looks the VM up by that ref, gives it and its exclusive disks this machine's marking (like `vagrant xapi adopt`) and stores the UUID. A ref XAPI no longer knows (`HANDLE_INVALID`) means not created, as with vagrant-xenserver; other errors go up. Never by name: another VM with that name, e.g. a colleague's from the same Vagrantfile, would be marked as this machine's and later destroyed. A VM marked for another machine stays as it is; this machine is not created, with a warning that points to `vagrant xapi adopt --force`, which replaces an id that is no VM UUID |
+| `destroy` | `xenserver/plugin.rb` | vagrant-xenserver removed every disk of the VM, also disks that triggers attached (`extra_disks`). For `:xenserver` machines the VM's exclusive disks are marked as its own before `destroy`; sharable disks and disks of other VMs stay |
+| `vagrant xapi migrate` | `xenserver/migrate.rb` | For moving a project to `:xapi` after `:xenserver` became `:xapi` in its Vagrantfile: locks the machine's entry in Vagrant's machine index (a machine another process holds is left alone), moves `.vagrant/machines/<name>/xenserver` to `xapi` and updates the entry, so Vagrant does not create new VMs, and marks the VM's exclusive disks as its own, so `destroy` under `:xapi` still removes disks that triggers attached. Machines with an OpaqueRef as id are left alone until a command took them over |
+| Texts | `locales/en.yml` | `vagrant_xapi.xenserver`, plus the `migrate_*` and `xenserver_*` keys |
+
+TLS needs one setting where vagrant-xenserver needed none:
+`VAGRANT_XAPI_TLS_FINGERPRINT` (the pins of all hosts, separated by commas)
+or `VAGRANT_XAPI_TLS_CA_FILE`, unless the local machine trusts the pool's
+certificates. vagrant-xenserver hardly used TLS. Its API calls, the login
+with the password included, went through the `xenapi` gem, which uses TLS
+only on port 443 (`XMLRPC::Client.new(..., @uri.port == 443, ...)`) and
+ignores the scheme. `xs_port` defaulted to 80, so even with
+`xs_use_ssl = true` they went over plain HTTP. Box uploads went to
+`https://<host>/` with `curl --insecure`, with the session id in the URL.
+
+### Temporary: the XenApi::Client stand-in in lib/vagrant-xapi/legacy
+
+Triggers in Vagrantfiles of vagrant-xenserver may `require "xenapi"`, a gem
+vagrant-xenserver brought along, to do what that plugin could not (extra
+disks, vCPUs). `legacy/xenapi.rb`, loaded through `lib/xenapi.rb`, stands in
+for its client: `XenApi::Client.new(uri, timeout)`, `login_with_password`,
+`xc.<Class>.<method>(...)` for any XAPI call and `xc.session.logout`, on
+vagrant-xapi's own client. That means HTTPS with the port and TLS settings
+of the provider config for that host (`legacy/plugin.rb` learns them through
+`Extensions.on_config_finalized`) or `VAGRANT_XAPI_TLS_*`, its own session,
+and `HOST_IS_SLAVE` handling. XAPI errors become
+`XenApi::Errors::<CamelCaseCode>`. Machine ids are VM UUIDs where
+vagrant-xenserver used OpaqueRefs; code that uses `machine.id` as a
+reference gets `HANDLE_INVALID` and, as written for stale references, looks
+the VM up by name. The first `XenApi::Client` of a run says that the
+stand-in is temporary and points to the provider's own options (`cpus`,
+`config.vm.disk`). Its text is in `locales/legacy.en.yml`. When
+vagrant-xenserver is installed too, `lib/xenapi.rb` loads the real gem
+instead, also when it comes first on the load path: vagrant-xapi leaves the
+old plugin alone.
+
+### Hook points
+
+The core does not know either layer. `extensions.rb` offers hook points
+that do nothing without them:
+
+- `Extensions.provider_names`: the providers whose machines the plugin runs
+  (data dirs, machine index, `vagrant xapi`); `xenserver/` adds `:xenserver`.
+- `Extensions.on_foreign_id`: called from `Provider#state` when the machine
+  id is not a VM UUID; `xenserver/` takes over machines of vagrant-xenserver.
+- `Extensions.on_before_destroy`: called by `DestroyVm`; `xenserver/` marks
+  the exclusive disks of `:xenserver` machines.
+- `Extensions.on_config_finalized`: called at the end of `Config#finalize!`;
+  `legacy/` remembers the connection settings per host.
+- `Extensions.add_subcommand`: extra `vagrant xapi` subcommands;
+  `xenserver/` adds `migrate`.
+
+`spec/unit/legacy/boundary_spec.rb` fails when anything outside
+`lib/vagrant-xapi/legacy` and `lib/xenapi.rb` refers to the stand-in,
+`xenserver/` included, except the one `require_relative` in `plugin.rb`.
+
+### Removing the stand-in
+
+1. Announce it in the CHANGELOG one release ahead; the stand-in already says
+   on every run that uses it that it is temporary. Remove it in a new major
+   version (2.0.0), because Vagrantfiles whose triggers use it stop working.
+2. Delete `lib/vagrant-xapi/legacy/`, `lib/xenapi.rb`,
+   `locales/legacy.en.yml` and `spec/unit/legacy/`.
+3. Delete the `require_relative "legacy/plugin"` line at the end of
+   `lib/vagrant-xapi/plugin.rb`.
+4. In scenario A15 of `test/acceptance/scenarios.sh`, drop the triggers and
+   the checks of the extra disk; keep the rest (provider `:xenserver`,
+   migrate).
+5. Delete what documents it:
+   - here: the "Temporary" subsection above, the `legacy/` line in the code
+     map (section 4) and `legacy/` in the `on_config_finalized` hook point;
+   - README: the paragraph on triggers that call XAPI themselves;
+   - docs/operations.md: the sentence on the stand-in in section 2 and the
+     troubleshooting rows "a trigger uses XenApi::Client" and "Stale VM
+     reference";
+   - AGENTS.md: the `legacy/` line in the layout and the paragraph on the
+     stand-in;
+   - test/acceptance/README.md: the triggers in the A15 row;
+   - CHANGELOG.md: a line that the stand-in is gone.
+6. `Extensions.on_config_finalized` may stay; it costs nothing.