Architecture

Xen Orchestra (XO) is built as one server and several clients: the two web interfaces (XO 6 and XO 5), the command line client xo-cli, and anything speaking the REST API. The server, xo-server, is the only piece that talks to your infrastructure.

tip

XO is totally agent-less: nothing to install on your hosts. xo-server speaks XAPI, the native toolstack of XCP-ng, directly over the network.

One server, several clients, your whole infrastructureXOXCP-ng

Note that xo-server only needs to reach the master of each pool: the master relays to the other hosts of its pool. One XO connects to any number of pools, on any site.

XOA

The Xen Orchestra Appliance (XOA) is a VM with the whole stack pre-installed, configured and QA validated. It is the way we recommend and support running XO: see Installation.

xo-server

xo-server is the heart of Xen Orchestra: a Node.js daemon connected permanently to your pools. Its central position is what makes XO more than a mere client:

• Always on: as a daemon, it listens to and records every event of your infrastructure, around the clock, whether a client is watching or not. That is what makes always-up-to-date views, scheduled backup jobs and task history possible.
• Event driven: xo-server subscribes to XAPI events instead of polling. Changes on a host or VM appear in your browser the moment they happen, and the server-side cache answers clients instantly, at any infrastructure size.
• A single connection point: clients connect to xo-server, never to your hosts. Legacy thick clients opened connections from every admin workstation to every server; here one daemon holds one connection per pool, and any number of clients share it.
• A proxy for your hosts: because everything flows through it, xo-server can expose VM consoles to clients that have no network access to the hosts, or stream a VM export from one pool straight into another (that is warm migration territory) without a file stop in between.
• Pluggable: features like LDAP authentication, load balancing, netbox synchronization or backup reports are plugins, not core patches.

Events, not polling

Legacy clients ask the servers "anything new?" every few seconds: slow, and it collapses at scale. xo-server subscribes once to the XAPI event stream, and pushes every change to all connected clients the moment it happens:

Polling asks, events arriveXOXCP-ng

The web interfaces

Two web UIs currently ship with Xen Orchestra, served by xo-server and talking to it over WebSockets:

• XO 6 (@xen-orchestra/web), the new default interface, built with Vue.js on a dedicated design system. See the XO 6 documentation.
• XO 5 (xo-web), the complete historical interface, built with React. See the infrastructure management section for what you can do with it.

https://your-xo/v6/#/dashboard

XO 6, the new default web interface

Both run against the same server and the same data at the same time: see XO 6 vs. XO 5.

xo-cli

xo-cli sends commands to xo-server from a shell. Thanks to introspection, it discovers every method the server exposes, plus a convenient wrapper around the REST API.

warning

xo-cli is mainly a debug and power-user tool: there is no absolute guarantee on its stability. Prefer the REST API for automation.

Register your XO instance first (only a token is stored):

workstation — register your XO

# xo-cli register http://xo.my-company.net admin@admin.net admin
Successfully logged with admin@admin.net

Discover what the server exposes:

workstation — explore the API

# xo-cli list-commands  # every available method
# xo-cli list-commands '{user,group}.*'  # filtered by pattern
# xo-cli list-objects type=VM-template  # objects, filterable by properties

Then call any method with xo-cli <command> <param>=<value>:

workstation — add a server

# xo-cli server.add host=my.server.net username=root password=secret-password
42

Parameters are strings by default (true/false are parsed as booleans); prefix with json: for other types (baz='json:[1, 2, 3]'). xo-cli help documents everything, including the xo-cli rest get|post|patch|del subcommands that map directly onto the REST API.

note

xo-cli imports XVA files only (xo-cli vm.import sr=<SR UUID> @=vm.xva). For OVA imports, use the web UI or xo-upload-ova.

APIs

The public, supported API of Xen Orchestra is the REST API: plain HTTP, easy to call from any language or tool, with its own documentation page and a live OpenAPI reference at /rest/v0/docs/ on your XO.

Internally, the web UIs and xo-cli talk to xo-server over a JSON-RPC-over-WebSockets protocol: that connected mode is what lets clients subscribe to events and stay current in real time. This internal API is not designed for third parties: if you automate against XO, use the REST API.

Plugins

Plugins extend Xen Orchestra without touching its core. They live in "Settings, then Plugins":

zoomed detail

The Plugins page in Settings

Each plugin can be activated or deactivated, loaded at startup, and configured entirely from the web interface:

zoomed detail

Configuring a plugin from the web interface