ZSvirt FAQ: 20 questions from global users, Part 2

This is Part 2 of the ZSvirt FAQ. Part 1 answered 10 questions on installation and login, Windows, GPU, and ARM support, and networking and storage. Part 2 covers migration and backup/recovery, API and SDK, documentation and community, and open-source scope and platform selection.

What this FAQ covers

  • Migration and backup/recovery
    • Q11: Migrating from VMware: how do I choose a migration method?
    • Q12: How do I import an OVF? What if the data disk is not recognized?
    • Q13: What are the plans for Veeam integration? How do built-in backup, recovery, and off-site sync work?
  • API and SDK
    • Q14: How do I initialize the Java SDK? How do I get the final result of an HTTP 202?
    • Q15: Does ZSvirt support API integration? How do authentication and calls work?
  • Documentation and community
    • Q16: Where is the official documentation? Why are the ZStack/ZSphere names still used?
    • Q17: How do I report a fault, a feature request, or a UI translation issue?
    • Q18: How are security vulnerabilities reported and handled?
  • Open-source scope and platform selection
    • Q19: Can the open-source edition be used in production for free? How does it relate to OpenStack?
    • Q20: How do I evaluate the platform and its performance? What automation entry points are available?

Migration and backup/recovery

Q11: Migrating from VMware: how do I choose a migration method?

Choose ZMigrate live migration, full OVF import, or VMDK disk import based on your downtime window and the files you already have.

ZMigrate live migration

Fits bulk migrations or cases that need minimal downtime. No agent is installed in the source VM; data syncs while the source VM runs, and the final cutover is the only downtime.

Sequence: deploy ZMigrate → upload the VDDK → configure the data gateway → add the VMware source platform → create a migration task → sync and verify → stop the source VM and cut over.

Live migration has a concurrency limit; OVF and VMDK offline imports are not subject to it.

Full OVF import

Fits cases where a downtime window for export is acceptable. Power off the source VM, export the complete file set — the .ovf file, the associated VMDKs, and the MF file — then import it through New VM > Import VM.

VMDK disk import

Fits cases where the VMDK already exists and only the disk data needs to move. Add the VMDK as a platform image; the platform converts it to qcow2 or raw depending on the image storage type, then create a VM from the image. CPU, memory, and networking are configured again, and the BIOS mode must match the source VM.

References: Three migration methods and workflows, Agentless migration, Concurrency scope

Q12: How do I import an OVF? What if the data disk is not recognized?

An OVF import needs the complete file set, matching references, and usable image storage.

Standalone and distributed image repositories are supported, and the temporary template created by the import is cleaned up automatically by default after the VM is created.

  1. Prepare the .ovf file, all associated VMDKs, and the MF file. File names, count, and configuration must match the OVF description.
  2. Go to New VM > Import VM, upload the file set, select the image storage, run location, and target datastore, and submit the import.
  3. Disk 1 uses IDE by default and data disks use VirtIO. If the guest lacks the VirtIO driver, the data disk is only recognized after VM Tools is installed and started. Do not initialize the original data disk.

Reference: Import guide

Q13: What are the plans for Veeam integration? How do built-in backup, recovery, and off-site sync work?

The API Proxy package for Veeam integration is planned for a later release; the release date will follow the official announcement.

Built-in backup and recovery are available now:

  1. Add backup storage. To reuse image storage, select an enabled, connected standalone image repository and enter the backup network CIDR.
  2. Create a VM backup plan: choose the objects, backup storage, and policy. Run one backup and wait for a successful restore point.
  3. Under Data Protection > Protected Resources, select the VM and the successful backup, click New VM, and configure the run location and network. Attach the restored VM to an isolated network for verification so it does not conflict with the source VM.

Prerequisites

Before creating a backup plan, confirm that backup quota is available, the VM is running or suspended, and it is not bound to another backup plan. Shared disks and RDM disks are not covered by backup.

Off-site sync

Add off-site backup storage first, then configure off-site sync in the backup plan. To create a VM from an off-site backup, sync the backup back to local backup storage first.

References: Backup plans, Reusing image storage, Restore steps

API and SDK

Q14: How do I initialize the Java SDK? How do I get the final result of an HTTP 202?

Initialize the Java SDK with ZSClient.configure(config). An HTTP 202 means the request was accepted; the final result still has to be retrieved.

The setConfig() error

Before calling an Action’s call() method, create and configure a ZSConfig object, then call ZSClient.configure(config). The setConfig() in the error message is a wrong method name in the hint text.

Reference: SDK initialization source

Handling an HTTP 202

The Java SDK polls for the final result by default. With a WebHook configured and callback handling in place, the result arrives through the callback. When calling the REST API directly, send a GET request to the location in the response body; if it also returns 202, keep polling until the final business result arrives. Failure details are in the error field.

References: SDK async result handling, Server-side result query

Q15: Does ZSvirt support API integration? How do authentication and calls work?

ZSvirt provides a RESTful API with Session and AccessKey authentication.

  • Session: after the account login API succeeds, use the inventory.uuid from the response as the Session UUID and send Authorization: OAuth <SessionUUID> in the request header.
  • AccessKey: fill in accessKeyId and accessKeySecret on the Action object in the Java SDK and let the SDK sign the request. For direct REST calls, generate Authorization: ZStack <AccessKeyID>:<Signature> as documented, and include a Date header that matches the signature calculation.

Query VMs with a valid session:

curl -H 'Authorization: OAuth <SessionUUID>' \
  'http://<management-node-IP>:8080/zstack/v1/vm-instances'

Replace the URL with the actual API address. On success, the VM list is in the inventories field.

References: Account login API, Query VM API, AccessKey authentication

Documentation and community

Q16: Where is the official documentation? Why are the ZStack/ZSphere names still used?

Installation docs, the user guide, the API reference, and categorized FAQs are all available from the documentation center.

ZSvirt was open-sourced from the ZStack ZSphere commercial product and now develops independently. Some code, configuration, and documentation still use the ZStack/ZSphere naming — environment variables, configuration items, dependencies, paths, and commands. These names exist for compatibility and do not affect normal use of ZSvirt.

Reference: Naming note

Q17: How do I report a fault, a feature request, or a UI translation issue?

Fault reports need reproducible information; feature requests need the use case.

Submit faults, feature requests, and UI translation issues to Issues; use Discussions for usage questions. A fault report should include:

ZSvirt/SDK version and deployment method:
Server, OS, CPU, network, and storage:
Reproduction steps, expected result, and actual result:
Time of failure with time zone, task/resource ID:
Raw error and logs from the corresponding period:

Remove passwords, tokens, and business-sensitive data from logs before posting an Issue or Discussion. For UI translation issues, include the page path and the original text.

Reference: Contributing guide

Q18: How are security vulnerabilities reported and handled?

Report suspected vulnerabilities privately by email: security@zsvirt.io (preferred) or community@zsvirt.io (fallback).

Do not disclose vulnerability details in a public Issue. Include the affected version, reproduction conditions, impact scope, sanitized evidence, and a way to reach you.

Maintainers receive and verify reports under the security policy, assess fixes or mitigations, and coordinate disclosure.

Open-source scope and platform selection

Q19: Can the open-source edition be used in production for free? How does it relate to OpenStack?

ZSvirt was open-sourced from ZSphere and develops independently. The source code is GPL 3.0, can be used in production, and carries no platform license fee.

ZSvirt follows its own technical path and is not an OpenStack derivative. Vendor drivers, third-party software, and commercial services follow their own licenses and pricing.

References: Open-source scope, Production use and technical path

Q20: How do I evaluate the platform and its performance? What automation entry points are available?

For features and management, see the comparison article. For performance and compatibility, validate on your target hardware, storage, and workloads following the PoC guide.

Automation entry points: REST API, SDK, Terraform provider.

Installation and login, Windows, GPU, and ARM support, and networking and storage are covered in Part 1.

Join the Community