xapi-project · changlei-li · Jul 21, 2025 · Jun 18, 2025 · Jun 18, 2025 · Jun 19, 2025
diff --git a/Makefile b/Makefile
@@ -147,7 +147,8 @@ install-extra:
 	DESTDIR=$(DESTDIR) SBINDIR=$(SBINDIR) QEMU_WRAPPER_DIR=$(QEMU_WRAPPER_DIR) XENOPSD_LIBEXECDIR=$(XENOPSD_LIBEXECDIR) ETCDIR=$(ETCDIR) ./ocaml/xenopsd/scripts/make-custom-xenopsd.conf
 
 # common flags and packages for 'dune install' and 'dune uninstall'
-DUNE_IU_PACKAGES1=-j $(JOBS) --destdir=$(DESTDIR) --prefix=$(PREFIX) --libdir=$(LIBDIR) --mandir=$(MANDIR)
+DUNE_IU_COMMON=-j $(JOBS) --destdir=$(DESTDIR) --libdir=$(LIBDIR) --mandir=$(MANDIR)
+DUNE_IU_PACKAGES1=$(DUNE_IU_COMMON) --prefix=$(PREFIX)
 DUNE_IU_PACKAGES1+=--libexecdir=$(XENOPSD_LIBEXECDIR) --datadir=$(SDKDIR)
 DUNE_IU_PACKAGES1+=xapi-client xapi-schema xapi-consts xapi-cli-protocol xapi-datamodel xapi-types
 DUNE_IU_PACKAGES1+=xen-api-client xen-api-client-lwt rrdd-plugin rrd-transport
@@ -163,17 +164,17 @@ install-dune1:
 # dune can install libraries and several other files into the right locations
 	dune install $(DUNE_IU_PACKAGES1)
 
-DUNE_IU_PACKAGES2=-j $(JOBS) --destdir=$(DESTDIR) --prefix=$(OPTDIR) --libdir=$(LIBDIR) --mandir=$(MANDIR) --libexecdir=$(OPTDIR)/libexec --datadir=$(DOCDIR)  xapi xe
+DUNE_IU_PACKAGES2=$(DUNE_IU_COMMON) --prefix=$(OPTDIR) --libexecdir=$(OPTDIR)/libexec --datadir=$(DOCDIR)  xapi xe
 
 install-dune2:
 	dune install $(DUNE_IU_PACKAGES2)
 
-DUNE_IU_PACKAGES3=-j $(JOBS) --destdir=$(DESTDIR) --prefix=$(OPTDIR) --libdir=$(LIBDIR) --mandir=$(MANDIR) --libexecdir=$(OPTDIR)/libexec --bindir=$(OPTDIR)/debug --datadir=$(OPTDIR)/debug xapi-debug
+DUNE_IU_PACKAGES3=$(DUNE_IU_COMMON) --prefix=$(OPTDIR) --libexecdir=$(OPTDIR)/libexec --bindir=$(OPTDIR)/debug --datadir=$(OPTDIR)/debug xapi-debug
 
 install-dune3:
 	dune install $(DUNE_IU_PACKAGES3)
 
-DUNE_IU_PACKAGES4=-j $(JOBS) --destdir=$(DESTDIR) --prefix=$(PREFIX) --libdir=$(LIBDIR) --libexecdir=/usr/libexec --mandir=$(MANDIR) vhd-tool forkexec
+DUNE_IU_PACKAGES4=$(DUNE_IU_COMMON) --prefix=$(PREFIX) --libexecdir=/usr/libexec vhd-tool forkexec qcow-stream-tool
 
 install-dune4:
 	dune install $(DUNE_IU_PACKAGES4)
@@ -186,7 +187,7 @@ install:
 	chmod +x $(DESTDIR)$(DOCDIR)/doc-convert.sh
 	# backward compat with existing specfile, to be removed after it is updated
 	find $(DESTDIR) -name '*.cmxs' -delete
-	for pkg in xapi-debug xapi xe xapi-tools xapi-sdk vhd-tool; do for f in CHANGELOG LICENSE README.markdown; do rm $(DESTDIR)$(OPTDIR)/doc/$$pkg/$$f $(DESTDIR)$(PREFIX)/doc/$$pkg/$$f -f; done; for f in META dune-package opam; do rm $(DESTDIR)$(LIBDIR)/$$pkg/$$f -f; done; done;
+	for pkg in xapi-debug xapi xe xapi-tools xapi-sdk vhd-tool qcow-stream-tool; do for f in CHANGELOG LICENSE README.markdown; do rm $(DESTDIR)$(OPTDIR)/doc/$$pkg/$$f $(DESTDIR)$(PREFIX)/doc/$$pkg/$$f -f; done; for f in META dune-package opam; do rm $(DESTDIR)$(LIBDIR)/$$pkg/$$f -f; done; done;
 
 
 uninstall:

diff --git a/doc/content/design/sm-supported-image-formats.md b/doc/content/design/sm-supported-image-formats.md
@@ -2,7 +2,7 @@
 title: Add supported image formats in sm-list
 layout: default
 design_doc: true
-revision: 2
+revision: 3
 status: proposed
 ---
 
@@ -22,32 +22,16 @@ available formats.
 # Design Proposal
 
 To expose the available image formats to clients (e.g., XenCenter, XenOrchestra, etc.),
-we propose adding a new field called `supported-image-formats` to the Storage Manager (SM)
-module. This field will be included in the output of the `SM.get_all_records` call.
+we propose adding a new field called `supported_image_formats` to the Storage Manager
+(SM) module. This field will be included in the output of the `SM.get_all_records` call.
 
-The `supported-image-formats` field will be populated by retrieving information
-from the SMAPI drivers. Specifically, each driver will update its `DRIVER_INFO`
-dictionary with a new key, `supported_image_formats`, which will contain a list
-of strings representing the supported image formats
-(for example: `["vhd", "raw", "qcow2"]`).
-
-The list designates the driver's preferred VDI format as its first entry. That
-means that when migrating a VDI, the destination storage repository will
-attempt to create a VDI in this preferred format. If the default format cannot
-be used (e.g., due to size limitations), an error will be generated.
-
-If a driver does not provide this information (as is currently the case with existing
-drivers), the default value will be an empty array. This signifies that it is the
-driver that decides which format it will use. This ensures that the modification
-remains compatible with both current and future drivers.
-
-With this new information, listing all parameters of the SM object will return:
+- With this new information, listing all parameters of the SM object will return:
 
 ```bash
 # xe sm-list params=all
 ```
 
-will output something like:
+Output of the command will look like (notice that CLI uses hyphens):
 
 ```
 uuid ( RO)                         : c6ae9a43-fff6-e482-42a9-8c3f8c533e36
@@ -65,12 +49,118 @@ required-cluster-stack ( RO)       :
 supported-image-formats ( RO)       : vhd, raw, qcow2
 ```
 
-This change impacts the SM data model, and as such, the XAPI database version will
-be incremented.
+## Implementation details
+
+The `supported_image_formats` field will be populated by retrieving information
+from the SMAPI drivers. Specifically, each driver will update its `DRIVER_INFO`
+dictionary with a new key, `supported_image_formats`, which will contain a list
+of strings representing the supported image formats
+(for example: `["vhd", "raw", "qcow2"]`). Although the formats are listed as a
+list of strings, they are treated as a set-specifying the same format multiple
+times has no effect.
+
+### Driver behavior without `supported_image_formats`
+
+If a driver does not provide this information (as is currently the case with
+existing drivers), the default value will be an empty list. This signifies
+that the driver determines which format to use when creating VDI. During a migration,
+the destination driver will choose the format of the VDI if none is explicitly
+specified. This ensures backward compatibility with both current and future drivers.
+
+### Specifying image formats for VDIs creation
+
+If the supported image format is exposed to the client, then, when creating new VDI,
+user can specify the desired format via the `sm_config` parameter `image-format=qcow2` (or
+any format that is supported). If no format is specified, the driver will use its
+preferred default format. If the specified format is not supported, an error will be
+generated indicating that the SR does not support it. Here is how it can be achieved
+using the XE CLI:
+
+```bash
+# xe vdi-create \
+    sr-uuid=cbe2851e-9f9b-f310-9bca-254c1cf3edd8 \
+    name-label="A new VDI" \
+    virtual-size=10240 \
+    sm-config:image-format=vhd
+```
+
+### Specifying image formats for VDIs migration
+
+When migrating a VDI, an API client may need to specify the desired image format if
+the destination SR supports multiple storage formats.
+
+#### VDI pool migrate
+
+To support this, a new parameter, `dest_img_format`, is introduced to
+`VDI.pool_migrate`. This field accepts a string specifying the desired format (e.g., *qcow2*),
+ensuring that the VDI is migrated in the correct format. The new signature of
+`VDI.pool_migrate` will be
+`VDI ref pool_migrate (session ref, VDI ref, SR ref, string, (string -> string) map)`.
+
+If the specified format is not supported or cannot be used (e.g., due to size limitations),
+an error will be generated. Validation will be performed as early as possible to prevent
+disruptions during migration. These checks can be performed by examining the XAPI database
+to determine whether the SR provided as the destination has a corresponding SM object with
+the expected format. If this is not the case, a `format not found` error will be returned.
+If no format is specified by the client, the destination driver will determine the appropriate
+format.
+
+```bash
+# xe vdi-pool-migrate \
+    uuid=<VDI_UUID> \
+    sr-uuid=<SR_UUID> \
+    dest-img-format=qcow2
+```
+
+#### VM migration to remote host
+
+A VDI migration can also occur during a VM migration. In this case, we need to
+be able to specify the expected destination format as well. Unlike `VDI.pool_migrate`,
+which applies to a single VDI, VM migration may involve multiple VDIs.
+The current signature of `VM.migrate_send` is `(session ref, VM ref, (string -> string) map,
+bool, (VDI ref -> SR ref) map, (VIF ref -> network ref) map, (string -> string) map,
+(VGPU ref -> GPU_group ref) map)`. Thus there is already a parameter that maps each source
+VDI to its destination SR. We propose to add a new parameter that allows specifying the
+desired destination format for a given source VDI: `(VDI ref -> string)`. It is
+similar to the VDI-to-SR mapping. We will update the XE cli to support this new format.
+It would be `image_format:<source-vdi-uuid>=<destination-image-format>`:
+
+```bash
+# xe vm-migrate \
+        host-uuid=<HOST_UUID> \
+        remote-master=<IP> \
+        remote-password=<PASS> \
+        remote-username=<USER> \
+        vdi:<VDI1_UUID>=<SR1_DEST_UUID> \
+        vdi:<VDI2_UUID>=<SR2_DEST_UUID> \
+        image-format:<VDI1_UUID>=vhd \
+        image-format:<VDI2_UUID>=qcow2 \
+        uuid=<VM_UUID>
+```
+The destination image format would be a string such as *vhd*, *qcow2*, or another
+supported format. It is optional to specify a format. If omitted, the driver
+managing the destination SR will determine the appropriate format.
+As with VDI pool migration, if this parameter is not supported by the SM driver,
+a `format not found` error will be returned. The validation must happen before
+sending a creation message to the SM driver, ideally at the same time as checking
+whether all VDIs can be migrated.
+
+To be able to check the format, we will need to modify `VM.assert_can_migrate` and
+add the mapping from VDI references to their image formats, as is done in `VM.migrate_send`.
 
 # Impact
 
-- **Data Model:** A new field (`supported-image-formats`) is added to the SM records.
+It should have no impact on existing storage repositories that do not provide any information
+about the supported image format.
+
+This change impacts the SM data model, and as such, the XAPI database version will
+be incremented. It also impacts the API.
+
+- **Data Model:**
+  - A new field (`supported_image_formats`) is added to the SM records.
+  - A new parameter is added to `VM.migrate_send`: `(VDI ref -> string) map`
+  - A new parameter is added to `VM.assert_can_migrate`: `(VDI ref -> string) map`
+  - A new parameter is added to `VDI.pool_migrate`: `string`
 - **Client Awareness:** Clients like the `xe` CLI will now be able to query and display the supported image formats for a given SR.
 - **Database Versioning:** The XAPI database version will be updated to reflect this change.
 
diff --git a/dune-project b/dune-project
@@ -577,6 +577,15 @@
     :with-test
     (>= "2.4.0")))))
 
+(package
+  (name qcow-stream-tool)
+  (synopsis "Minimal CLI wrapper for qcow-stream")
+  (depends
+    qcow-stream
+    cmdliner
+  )
+)
+
 (package
  (name varstored-guard))
 

diff --git a/ocaml/idl/datamodel_errors.ml b/ocaml/idl/datamodel_errors.ml
@@ -68,7 +68,7 @@ let _ =
       "The license-server connection details (address or port) were missing or \
        incomplete."
     () ;
-  error Api_errors.license_checkout_error ["reason"]
+  error Api_errors.license_checkout_error ["code"; "message"]
     ~doc:"The license for the edition you requested is not available." () ;
   error Api_errors.license_file_deprecated []
     ~doc:
@@ -532,31 +532,14 @@ let _ =
       "You attempted an operation on a VM which requires a more recent version \
        of the PV drivers. Please upgrade your PV drivers."
     () ;
-  error Api_errors.vm_lacks_feature_shutdown ["vm"]
-    ~doc:
-      "You attempted an operation which needs the cooperative shutdown feature \
-       on a VM which lacks it."
-    () ;
-  error Api_errors.vm_lacks_feature_vcpu_hotplug ["vm"]
-    ~doc:
-      "You attempted an operation which needs the VM hotplug-vcpu feature on a \
-       VM which lacks it."
-    () ;
-  error Api_errors.vm_lacks_feature_suspend ["vm"]
-    ~doc:
-      "You attempted an operation which needs the VM cooperative suspend \
-       feature on a VM which lacks it."
-    () ;
-  error Api_errors.vm_lacks_feature_static_ip_setting ["vm"]
-    ~doc:
-      "You attempted an operation which needs the VM static-ip-setting feature \
-       on a VM which lacks it."
-    () ;
   error Api_errors.vm_lacks_feature ["vm"]
     ~doc:"You attempted an operation on a VM which lacks the feature." () ;
+  error Api_errors.vm_non_suspendable ["vm"; "reason"]
+    ~doc:"You attempted an operation on a VM which is not suspendable." () ;
   error Api_errors.vm_is_template ["vm"]
     ~doc:"The operation attempted is not valid for a template VM" () ;
-  error Api_errors.other_operation_in_progress ["class"; "object"]
+  error Api_errors.other_operation_in_progress
+    ["class"; "object"; "operation_type"; "operation_ref"]
     ~doc:"Another operation involving the object is currently in progress" () ;
   error Api_errors.vbd_not_removable_media ["vbd"]
     ~doc:"Media could not be ejected because it is not removable" () ;
@@ -2071,6 +2054,9 @@ let _ =
        enable it in XC or run xe pool-enable-tls-verification instead."
     () ;
 
+  error Api_errors.sysprep ["vm"; "message"]
+    ~doc:"VM.sysprep error with details in the message" () ;
+
   message
     (fst Api_messages.ha_pool_overcommitted)
     ~doc:

diff --git a/ocaml/idl/datamodel_lifecycle.ml b/ocaml/idl/datamodel_lifecycle.ml
@@ -239,6 +239,8 @@ let prototyped_of_message = function
       Some "25.2.0"
   | "host", "set_numa_affinity_policy" ->
       Some "24.0.0"
+  | "VM", "sysprep" ->
+      Some "25.24.0"
   | "VM", "get_secureboot_readiness" ->
       Some "24.17.0"
   | "VM", "set_uefi_mode" ->

diff --git a/ocaml/idl/datamodel_vm.ml b/ocaml/idl/datamodel_vm.ml
@@ -2211,6 +2211,7 @@ let operations =
         ; ("reverting", "Reverting the VM to a previous snapshotted state")
         ; ("destroy", "refers to the act of uninstalling the VM")
         ; ("create_vtpm", "Creating and adding a VTPM to this VM")
+        ; ("sysprep", "Performing a Windows sysprep on this VM")
         ]
     )
 
@@ -2369,6 +2370,19 @@ let restart_device_models =
     ~allowed_roles:(_R_VM_POWER_ADMIN ++ _R_CLIENT_CERT)
     ()
 
+let sysprep =
+  call ~name:"sysprep" ~lifecycle:[]
+    ~params:
+      [
+        (Ref _vm, "self", "The VM")
+      ; (String, "unattend", "XML content passed to sysprep")
+      ; (Float, "timeout", "timeout in seconds for expected reboot")
+      ]
+    ~doc:
+      "Pass unattend.xml to Windows sysprep and wait for the VM to shut down \
+       as part of a reboot."
+    ~allowed_roles:_R_VM_ADMIN ()
+
 let vm_uefi_mode =
   Enum
     ( "vm_uefi_mode"
@@ -2571,6 +2585,7 @@ let t =
       ; set_blocked_operations
       ; add_to_blocked_operations
       ; remove_from_blocked_operations
+      ; sysprep
       ]
     ~contents:
       ([

diff --git a/ocaml/idl/schematest.ml b/ocaml/idl/schematest.ml
@@ -3,7 +3,7 @@ let hash x = Digest.string x |> Digest.to_hex
 (* BEWARE: if this changes, check that schema has been bumped accordingly in
    ocaml/idl/datamodel_common.ml, usually schema_minor_vsn *)
 
-let last_known_schema_hash = "a030fa0233a69a33200b628af0f030c7"
+let last_known_schema_hash = "7586cb039918e573594fc358e90b0f04"
 
 let current_schema_hash : string =
   let open Datamodel_types in