The agent can serve its operations over HTTPS, with or without NATS. This guide covers enabling it, calling it and reading the results. Every operation and parameter is listed in operations.md.
In agent.yaml (a ready-made sample is configs/agent.https.yaml):
nats:
enabled: false # HTTPS-only: no NATS connection and nothing is pushed
agent_uuid: "<agent-uuid>"
http:
enabled: true
listen: "<management-ip>:8443"
self_signed: true # generate a certificate on first start
api_key: "<at least 32 random characters>"
hosts: ["agent.example.com"] # extra names/IPs for the certificate
agent:
allowed_operations: # only what you need
- xenserver.vm.list
- xenserver.vm.startGenerate a token with openssl rand -base64 48. The agent refuses to start if the token is shorter than 32 characters or still CHANGE_ME….
Leave nats.enabled at true to run both transports side by side.
-
Self-signed (
http.self_signed: true): an ECDSA P-256 certificate is created athttp.cert_file/http.key_fileon first start (default/var/lib/plusclouds/tls/), reused on later starts and renewed 30 days before expiry. A certificate that already exists is never overwritten. Add the names or IPs clients use tohttp.hosts. -
Your own certificate: set
self_signed: falseand pointcert_file/key_fileat it. -
Pinning: the SHA-256 fingerprint is logged at startup (
HTTPS server starting). Pin it on the client rather than disabling verification:curl --cacert /path/to/agent.crt https://agent.example.com:8443/healthz # or compare the fingerprint of the certificate the server presentscurl -kskips verification and is fine for a quick test only.
| Method and path | Auth | Purpose |
|---|---|---|
GET /healthz |
none | Liveness and version: {"status":"ok","agent_uuid":"…","agent_version":"v1.2.0","protocol_versions":[1]} |
POST /v1/command |
Authorization: Bearer <api_key> |
Run one operation |
Requests are limited to 1 MiB. A wrong or missing token returns 401. Other methods on /v1/command return 405.
Every request envelope carries "v", the protocol version (currently 1). Send it explicitly; an omitted v is treated as 1. Any other value is rejected with HTTP 400 and payload.status: "rejected":
{"payload":{"status":"rejected","message":"unsupported protocol version 2; this agent supports [1]"}}The result envelope echoes the request's v. To discover what an agent speaks before sending commands, call GET /healthz (agent_version, protocol_versions). Every response, including errors, also carries X-Agent-Version and X-Protocol-Version headers. The URL path (/v1/command) names the endpoint generation; v is the message-format version. See protocol.md.
curl -s https://agent.example.com:8443/v1/command \
--cacert agent.crt \
-H "Authorization: Bearer $AGENT_API_KEY" \
-d '{
"v": 1,
"id": "req-1",
"type": "command",
"payload": {
"operation": "xenserver.vm.snapshot_create",
"params": { "uuid": "<vm-uuid>", "label": "before-upgrade" }
}
}'id is yours to choose and is echoed back as payload.command_id. params holds the operation's parameters; docs/operations.md lists them.
The reply is an envelope whose payload looks like:
{
"command_id": "req-1",
"status": "completed",
"message": "",
"output": { "operation": "vm-snapshot", "target": "<vm-uuid>", "success": true,
"message": "Snapshot created.", "output": "<snapshot-uuid>" }
}payload.status |
HTTP | Meaning |
|---|---|---|
completed |
200 | The operation ran. Also check output.success: xe-based operations report their own failure there |
failed |
200 | The agent could not run it (bad input, missing precondition, or the command failed). message says why |
rejected |
200 | Refused: not in allowed_operations, bad parameters, or a destructive call without confirm |
accepted |
202 | A long operation started in the background; output is the job (see below) |
HTTP 4xx/5xx are reserved for transport problems (bad token, bad JSON, wrong method). Application outcomes are always in payload.status.
| Field | Meaning |
|---|---|
operation, target |
What ran and on which object |
success |
true/false |
message |
Plain-English summary or error |
output |
Raw string result, such as a new uuid |
data |
Structured result, such as {"uuid": "<new-object>"} |
detail |
On failure: command, exit_code, error_code, stderr, stdout |
diagnostics |
On failure: extra explanations the agent gathered (for example why a VM could not start) |
List operations return their array or object directly in output.
Failures are written for people. Examples:
- Starting a running VM:
Cannot start "web-1": the VM is running, but it must be halted. - Plugging a card twice:
Cannot plug network card "web-1": the network card is already plugged in. - Resizing a plugged disk:
Cannot resize disk …: it is plugged into a running VM and this storage does not support online resize … Unplug it first … or stop the VM, resize, then plug it again. - Destroying an attached disk: refused unless
allow_attachedis set.
Branch on output.detail.error_code (the xapi error code) when you need to automate, and show message to people.
Operations such as vm.destroy, vdi.destroy, network.destroy, vlan.destroy, sr.remove and pif.unplug need "confirm": true. Without it the call is rejected and nothing happens.
vm.destroy also needs "expected_name": the VM's exact current name-label. If it differs from the real name (for example a wrong uuid), the delete is refused.
Add "async": true to a long operation (see the list in the README). The reply is HTTP 202:
{ "payload": { "status": "accepted",
"output": { "job_id": "9f1c…", "operation": "xenserver.vm.export", "status": "running",
"progress": { "bytes_done": 0 } } } }Poll it:
… -d '{"v":1,"id":"p","type":"command","payload":{"operation":"agent.job.status","params":{"job_id":"9f1c…"}}}'{ "job_id": "9f1c…", "status": "running", "elapsed_s": 41.2,
"progress": { "bytes_done": 1288490188, "bytes_total": 8589934592, "percent": 15 } }status is running, completed, failed or cancelled. When it finishes, result holds the operation's normal output; on failure error explains. agent.job.list shows recent jobs and agent.job.cancel stops one and removes a half-written export. Jobs live in memory and are lost if the agent restarts. Only agent.max_jobs (default 2) run at once. See backups.md.
Instead of polling, an async call can ask the agent to report the final result to your server:
{"operation":"xenserver.vm.import",
"params":{"filename":"/mnt/repo/image.xva","sr_uuid":"<sr>","new_name":"vm-123","async":true,
"callback":{"url":"https://platform.example.com/api/agent-callbacks/vm-123","token":"<bearer token>"}}}When the job ends the agent POSTs JSON to that URL, with Authorization: Bearer <token>:
{"agent_uuid":"…","job_id":"…","operation":"xenserver.vm.import","status":"completed",
"error":"","elapsed_s":412.3,"result":{"operation":"vm-import","success":true,"data":{"uuid":"<new-vm>","renamed":true}}}- Delivery is retried up to 4 times with growing delays; any 2xx counts as delivered. A failed callback never affects the job:
agent.job.statusalways has the result. Treat callbacks as a hint and make your handler idempotent. - Off by default. The agent only calls URLs under a prefix listed in
agent.callback_allowed_urls(prefixes must be https and end in/), and only overhttps, with no credentials or fragment, and a plain path (no percent-encoding,./..segments or//); the agent sends the validated URL, never the raw string, and does not follow redirects; anything else is rejected before the job starts. This stops callers from using the agent to reach arbitrary addresses. - The
tokenis masked in logs. Certificates are verified normally (the agent trusts the host's CA store). - A job that is cancelled or fails still calls back, with
statuscancelledorfailed. Jobs lost to an agent restart do not call back.
With agent.dry_run: true the same calls are authenticated and validated but never executed; the reply has "dry_run": true, "executed": false. Useful to test an integration against a live host safely.
Typical times on a XenServer 8.2 host over a LAN: reads 0.1–0.6 s; start of a VM a few seconds; disk create about 0.5 s; hot-plug 1–2 s; snapshot a few seconds; exports are bounded by the target's write speed (use async). Synchronous calls time out server-side after 30 s for ordinary operations; long ones have their own limits (10 min medium, 2 h long).
| Symptom | Likely cause |
|---|---|
| Connection refused / timeout | Agent not running, http.enabled false, wrong listen, firewall |
Agent exits at start naming api_key |
Token empty, placeholder or under 32 characters |
401 |
Wrong or missing Authorization: Bearer token |
400 with unsupported protocol version |
v is not one of protocol_versions from /healthz |
rejected … not permitted on this agent |
Operation missing from allowed_operations |
| Certificate error | Name not in http.hosts, or the certificate was regenerated; re-pin |
status: accepted never finishes |
Check agent.job.status; jobs do not survive an agent restart |
Run the agent in the foreground with log.level: debug to see each command, parameters (secrets masked) and result.