tools.xenserver_tools module

XenServer / XCP-ng pool management via the XenAPI XML-RPC (HTTPS).

Uses the XenAPI PyPI package (see requirements.txt). Connects to the pool master on port 443 by default. Works with XenServer and XCP-ng (same XAPI).

Security: requires UNSANDBOXED_EXEC — controls foundational infrastructure.

TLS verification is off by default (verify_ssl=false); typical self-signed pool certs. Use only on trusted networks or terminate TLS elsewhere.

async tools.xenserver_tools.run(host='', user='', password='', action='', verify_ssl=False, pool_uuid=None, host_uuid=None, vm_uuid=None, sr_uuid=None, snapshot_name=None, snapshot_vm_uuid=None, credential_profile='', ctx=None)[source]

Validate and execute one XenServer/XCP-ng pool action, returning JSON.

Entry point for the xenserver_control tool. It enforces the UNSANDBOXED_EXEC gate, optionally hydrates host/user/password from a saved credential profile, validates the action and every supplied identifier, then runs the blocking XenAPI work off the event loop and serialises the result. A response that would exceed _MAX_JSON_CHARS is replaced with a “narrow the request” error so a huge pool dump cannot blow up the message pipeline.

Interactions and side effects: gates via _check_priv(); when a credential_profile is given it loads and merges saved credentials through tools._credential_profile_store.load_profile() / tools._credential_profile_store.merge_profile() (kwargs override the profile). It validates the action against _VALID_ACTIONS and the inputs with _host_ok(), _user_ok(), _uuid_ok(), and _snapshot_name_ok(), normalises the URL with _normalize_master_url(), and dispatches the actual XML-RPC call by running _xapi_dispatch() in a worker thread via asyncio.to_thread(). Mutating actions (VM start/shutdown/reboot/migrate/ destroy, snapshot create/revert/delete) change live infrastructure; read actions only fetch data. Reads redis/config/user_id off ctx. Dispatched by the tool loader via the xenserver_control handler entry in this module’s TOOLS list.

Parameters:

  • host (str) – Pool master hostname, IP, or URL; optional when credential_profile supplies it.

  • user (str) – XenAPI username; optional when supplied by a profile.

  • password (str) – Account password; optional when supplied by a profile.

  • action (str) – The operation to perform; must be one of _VALID_ACTIONS.

  • verify_ssl (bool) – When True, verify TLS; defaults to False for self-signed pool certs (mapped to ignore_ssl for XenAPI).

  • pool_uuid (str | None) – Optional pool UUID for pool_info.

  • host_uuid (str | None) – Host UUID for host_info or the vm_pool_migrate destination.

  • vm_uuid (str | None) – VM UUID for VM lifecycle, snapshot-create, migrate, and destroy actions.

  • sr_uuid (str | None) – Reserved for future SR-scoped actions; currently ignored.

  • snapshot_name (str | None) – Label used by snapshot_create.

  • snapshot_vm_uuid (str | None) – Snapshot VM UUID for snapshot_revert and snapshot_delete.

  • credential_profile (str) – Name of a saved profile to load credentials from; explicit kwargs override the loaded values.

  • ctx (Any) – The ToolContext supplying redis, config, and user_id; required.

Returns:

A JSON string with the action result (always carrying success), or a success: false error for a missing context, denied privilege, invalid action/identifier, or an oversized (truncated) response.

Return type:

str