Quick Start

ZSvirt QuickStart: From Installation to Your First VM

This guide walks administrators new to ZSvirt through a complete minimal workflow: preparing the installation environment, deploying the management node, completing basic initialization, adding hosts/storage/networks/images, and creating the first VM you can log in to.

When to use this guide:

• You want to set up a single-management-node ZSvirt environment from scratch.
• You already have the ZSvirt installation package, servers, and storage/network planning details ready.
• Your goal is to get the compute, storage, network, image, and VM chain working end to end.

What this guide does not cover:

• Dual management node HA deployment.
• Disaster recovery, migration, unified authentication, bare metal, and other modules.
• Production cutover plans, capacity planning, and security hardening.

1. Overall Workflow

The complete QuickStart workflow is:

Prepare the h84r ISO installation media
  -> Install the management node OS from the h84r ISO (compute node mode)
  -> Configure basic networking and time on the management node
  -> Prepare the ZSvirt installation package
  -> Install the ZSvirt management node
  -> Verify the management node and Web UI
  -> Log in to ZSvirt
  -> Initialize the datacenter and cluster
  -> Add a host
  -> Add a datastore
  -> Add image storage
  -> Create a distributed switch
  -> Create a distributed port group
  -> Add a system image
  -> Create the first VM from the system image
  -> Verify console access, IP, gateway, and login

Minimal resource relationship:

Datacenter
  └─ Cluster
      ├─ Host
      ├─ Datastore
      └─ Distributed Switch
          └─ Distributed Port Group
              └─ VM NIC
Datacenter
  └─ Image Storage
      └─ System Image
VM
  ├─ System Image
  ├─ Datastore
  └─ Distributed Port Group

2. Before You Begin

2.1 Management Node Hardware Recommendations

Prepare at least one management node server. For a minimal All-in-One environment, the hardware requirements are:

2.2 Install the OS from the h84r ISO and Deploy the ZSvirt Management Node

This step runs on the management node server itself to install its operating system. You are not creating a VM inside ZSvirt.

Prepare the h84r ISO installation media:

1. h84r ISO: ZSvirt-x86_64-DVD-<version>-h84r.iso
2. Installation method: physical optical drive, a bootable USB drive, or an ISO mounted through the server's remote console
3. Installation target: the local system disk of the management node server

After the server boots, follow the h84r installation wizard to complete the OS and management node installation:

2.3 Installation Log Locations

If the installation fails, check these first:

ls -lh /tmp/zstack_installation-*.log
ls -lh /tmp/zstack_ctl_installation-*.log
ls -lh /tmp/zstack_installation_timestamp-*.log

Common way to view them:

tail -n 200 /tmp/zstack_installation-*.log
tail -n 200 /tmp/zstack_ctl_installation-*.log

If the Web UI installation fails, check:

tail -n 200 /usr/local/zstack/zstack-ui/logs/ui-install.log

2.4 Post-Installation Verification

(1) Check the management node service, UI service, and version information

zstack-ctl status

If the node is not running:

zstack-ctl start_node

Check the management node IP:

zstack-ctl show_configuration | grep management.server.ip

3. Initialize the ZSvirt Management Node

ip addr
ip route
ping -c 4 <gateway IP>
ping -c 4 223.5.5.5
ping -c 4 www.baidu.com

4. Management Node CLI Verification

Enter the CLI on the management node:

zstack-cli

Log in:

LogInByAccount accountName=admin password=<admin password>

Query the basic resources:

QueryHost fields=uuid,name,managementIp,state,status
QueryPrimaryStorage fields=uuid,name,type,state,status
QueryBackupStorage fields=uuid,name,type,state,status,availableCapacity,totalCapacity
QueryL3Network fields=uuid,name,type
QueryImage fields=uuid,name,state,status
QueryVmInstance name=<vm-name> fields=uuid,name,state,hostUuid

Expected results:

Host state=Enabled status=Connected
PrimaryStorage state=Enabled status=Connected
BackupStorage state=Enabled status=Connected
Image state=Enabled status=Ready
VmInstance state=Running

5. Quick Troubleshooting

6. Minimum Success Criteria

When you finish, you should have at least:

• A successfully installed ZSvirt management node.
• A Web UI you can log in to.
• At least 1 host in the Enabled and Connected state.
• At least 1 datastore in the Enabled and Connected state.
• At least 1 image storage in the Enabled and Connected state.
• At least 1 distributed switch attached to the cluster.
• At least 1 distributed port group with available IP addresses.
• At least 1 usable system image.
• Your first VM in the Running state.
• A working VM console.
• A VM that obtains an IP address and can ping the gateway.

If all of the above pass, your minimal ZSvirt deployment and resource chain are working end to end.

7. Recommended Next Steps Before Production

After completing QuickStart, we recommend the following before moving to production:

• Change the default admin password and create individual administrator accounts.
• Configure NTP so the management node, hosts, storage, and network devices share the same time.
• Create distributed switches, distributed port groups, and network segments according to your service plan.
• Prepare standard Linux/Windows template images.
• Install or configure VMTools for more complete in-guest monitoring and management.
• Set up backup policies for the management node, database, images, and critical service VMs.
• Document the datacenter, cluster, hosts, datastores, image storage, VLANs, IP ranges, gateways, DNS, and service ownership.