Source and classification

• Source: Site case from the Veeam integration Technical Support group.
• Classification: Configuration and environment issue.
• Confirmation basis: The site used HTTP and a non-default ZSphere access port. API Proxy lacked the actual platform address, port, and context path, so its Java service timed out connecting to the platform. An in-place API Proxy installation with the actual parameters restored service.
• Internal tracking: No related Jira.

Issue metadata

• Issue ID: None.
• Component/product: ZSphere, Cloud, and Veeam API Proxy.
• Status: Resolution available.
• Priority/severity: General.
• Affected versions: Confirmed in API Proxy 1.0.x site environments; for other versions using a non-default platform address, check actual configuration.
• First fixed version: Not applicable; correct platform-access parameters resolve this issue.
• Confirmation date: June 5, 2026.
• Last updated: September 1, 2026.

Problem description

When Veeam connects to ZSphere or Cloud through API Proxy, API Proxy must access the platform management API. The installer usually generates service configuration from the default protocol, port, and context path.

If the site uses HTTP, a non-default port, or a custom context path without explicitly providing those parameters during installation, API Proxy might continue using the default address. Even if network connectivity to the destination IP exists, the Java service times out because it accesses the wrong protocol, port, or path, and Veeam cannot load or manage platform resources.

Distinguish these connections:

• Veeam server to API Proxy, usually using the external API Proxy address and port 16443.
• API Proxy to the ZSphere or Cloud management API, using the actual management node or VIP, protocol, backend port, and context path.

Verifying only that Veeam can reach 16443 does not prove API Proxy can reach the platform management API.

Symptoms

• Adding or refreshing a ZSphere/Cloud platform in Veeam fails.
• API Proxy logs show a Java timeout connecting to the platform or a platform API request that does not respond for a long time.
• The management node can ping or telnet the destination IP, but API Proxy still cannot connect normally.
• The platform uses HTTP rather than default HTTPS; its backend uses port 8080 and the zstack context path.
• Testing the actual platform API succeeds:

  curl -v http://<MN-IP>:8080/zstack

• Installation did not specify the actual zstack.host, zstack.port, and zstack.context-path.

Site screenshot

Impact

• Veeam cannot add or refresh ZSphere/Cloud.
• Veeam might not retrieve platform virtual machines, clusters, storage, and other resources.
• Backup, recovery, and Worker management operations that depend on API Proxy cannot continue.
• This is control-plane access failure caused by mismatched connection parameters. There is no evidence that it directly damages existing backup data or VM disk data.

Resolution

Confirm actual platform access parameters

1. Confirm that API Proxy is deployed on a ZSphere or Cloud management node.
2. Confirm whether the environment has one or two management nodes, and record the management-node IP or VIP that API Proxy must access.
3. Confirm the actual platform-management API protocol, port, and context path. Do not infer them only from the browser URL or default port.
4. Test the actual address from the API Proxy management node. For HTTP, port 8080, and context path zstack, run:

   curl -v http://<MN-IP>:8080/zstack

5. Check ZStack service status:

   zstack-ctl status

6. Inspect the API Proxy log and confirm the timeout is on API Proxy-to-platform rather than Veeam-to-API Proxy:

   less /opt/api-proxy/logs/api-proxy.log

Install API Proxy in place with actual parameters

1. Enter the extracted API Proxy installer directory.
2. Run an in-place installation with site-specific parameters:

   APP_OPTS="--zstack.host=<management-node-ip-or-vip> --zstack.port=<actual-platform-port> --zstack.context-path=<platform-context-path>" \
     ./install-api-proxy.sh --install

3. For a platform at management node 192.168.20.13, HTTP backend port 8080, and context path zstack, run:

   APP_OPTS="--zstack.host=192.168.20.13 --zstack.port=8080 --zstack.context-path=zstack" \
     ./install-api-proxy.sh --install

4. After the in-place installation, check and restart API Proxy:

   systemctl status api-proxy
   systemctl restart api-proxy

5. Check the log again and confirm that the platform connection no longer times out:

   tail -f /opt/api-proxy/logs/api-proxy.log

6. From the Veeam server, verify access to the external API Proxy address and port 16443, then retry adding the platform, refreshing resources, or the original failed operation in Veeam.

Collect information if failure remains

If failure continues after the in-place installation, collect:

• ZSphere or Cloud version and single- or dual-management-node deployment;
• API Proxy version and installation command, with sensitive credentials redacted;
• Actual platform protocol, management-node IP or VIP, port, and context path;
• zstack-ctl status output;
• curl -v from API Proxy to the platform API;
• Connectivity test from Veeam to API Proxy port 16443;
• Logs for the reproduced failure after reinstallation from /opt/api-proxy/logs/api-proxy.log.

To record detailed API calls, enable API logging during deployment and reproduce:

./install-api-proxy.sh --install --enable-api-logging

Before running it, use the help in the current installer package to confirm parameter order and combinations.

Precautions

• Do not confuse external API Proxy port 16443 with the backend platform-management API port.
• Do not infer API availability from successful ping or telnet; verify the full URL including protocol, port, and context path.
• API Proxy supports in-place installation and usually need not be uninstalled first. Some older uninstall versions might leave configuration residue, so in-place installation reduces that risk.
• For dual management nodes, select the correct VIP or management-node address for the site's deployment; do not copy the example IP.
• If curl reports only an untrusted certificate but reaches the correct service, that is a certificate-trust issue, not the port/context-path mismatch described here.

Affected products

• Products: ZSphere and ZStack Cloud.
• Product line: ZVF and Cloud-related Veeam integration scenarios.
• Component: Veeam API Proxy.
• Confirmed version: API Proxy 1.0.x.
• Trigger: The platform uses HTTP, a non-default port, or a custom context path, while API Proxy installation retains default platform-access parameters.

Fix status

• Current status: Configuration remediation available.
• Fix: Specify the actual platform host, port, and context path with APP_OPTS, and install API Proxy in place.
• Fixed version: Not applicable.
• Related patch/fix package: No separate patch required.

Related information

• API Proxy log: /opt/api-proxy/logs/api-proxy.log.
• External API Proxy port: 16443, subject to actual installation configuration.
• Confirmed backend example: HTTP, port 8080, and context path zstack.
• Veeam API Proxy installer and deployment documentation: Use the release directory and bundled documentation for the applicable product version.