XO documentation

# Architecture

Xen Orchestra (XO) is software built with a server and clients, such as the web client xo-web, but also a CLI capable client, called xo-cli.

TIP

XO is totally agent-less: you don't have to install any program on your hosts to get it working!

# XOA

Xen Orchestra Virtual Appliance (XOA) is a virtual machine with Xen Orchestra already installed, thus working out-of-the-box.

This is the easiest way to try Xen Orchestra quickly.

Your XOA is connected to all your hosts, or the pool master only if you are using Pools in XCP-ng/Citrix Hypervisor:

# Xen Orchestra (XO)

Xen Orchestra itself is built as a modular solution. Each part has its role.

# xo-server (server)

The core is "xo-server (opens new window)" - a daemon dealing directly with XCP-ng/XenServer or XAPI capable hosts. This is where users are stored, and it's the center point for talking to your whole Xen infrastructure.

XO-Server is the core of Xen Orchestra. Its central role opens a lot of possibilities versus other solutions - let's see why.

# Daemon mode

As a daemon, XO-Server is always up. Because of this, it can listen and record every event occurring on your entire Xen infrastructure. Connections are always open and it can cache information before serving it to another client (CLI, Web or anything else).

# Central point

Contrary to XenCenter, each Xen Orchestra's client is connected to one XO-Server, and not all the Xen servers. With a traditional architecture:

You can see how we avoid a lot of resource and bandwidth waste with a central point:

# Events

Legacy interfaces use the "pull" model, requesting data every "x" seconds:

It's not scalable and slow.

Previously with XO < 3.4, we used events in the following way:

But the interface was still lagging behind the server. With XO 3.4 and beyond, we now have a full event system, allowing instant display of what's happening on your infrastructure:

# A proxy for your hosts

XO-Server will act as a proxy for all your clients. This opens a lot of possibilities!

# Console proxy

A good example is the console: you can now expose your consoles even if your clients are outside the network!

# VM streaming

Another possibility is to stream a VM from one host to another.

To do that previously, you needed to export your VM somewhere, then re-import it:

Thanks to our architecture, it's now far easier:

# Patching on the fly

To install a patch manually, it requires a lot of steps: find, download, extract and apply the patch, sequentially.

"xo-server" can do all these steps at once:

  1. automatically download the patch from Citrix servers
  2. unzip it and upload it on the fly to your host
  3. apply it as soon it's done

# Pluggable

It's really easy to connect other modules to XO-server, and extend or adapt the solution to your needs (see XO-web and XO-cli for real examples).

# ACLs

# NodeJS under the hood

NodeJS (opens new window) is a software platform for scalable server-side and networking applications. It's famous for its efficiency, scalability and its asynchronous capabilities. Exactly what we need! Thus, XO-server is written in JavaScript.

# xo-web (web UI)

The web interface is "xo-web (opens new window)" - it runs directly from your browser. The connection with xo-server is done via WebSockets.

This is probably the first part of Xen Orchestra you'll see. The Web interface allows you to interact with your virtual infrastructure. As a module of XO-Web it facilitates everyday Xen administrator work, but also provides a solution to delegate parts of your infrastructure to other people.

Read the manage section to discover what you can do in XO-web.

# ReactJS

We stay consistent from the back-end to the front-end with one main language: ReactJS (opens new window)

# xo-cli (CLI)

"xo-cli (opens new window)" is a module allowing you to send commands directly from the command line.

Thanks to introspection, xo-cli will detect all the available features exposed in the xo-server API.

WARNING

This CLI is mainly used as a debug tool, there's no 100% guarantee on its stability. Use it only if you really know what you do.

# Usage

$ xo-cli help
Usage:

  xo-cli register [--allowUnauthorized] [--expiresIn <duration>] [--otp <otp>] <XO-Server URL> <username> [<password>]
  xo-cli register [--allowUnauthorized] [--expiresIn <duration>] --token <token> <XO-Server URL>
    Registers the XO instance to use.

    --allowUnauthorized, --au
      Accept invalid certificate (e.g. self-signed).

    --expiresIn <duration>
      Can be used to change the validity duration of the
      authorization token (default: one month).

    --otp <otp>
      One-time password if required for this user.

    --token <token>
      An authentication token to use instead of username/password.

  xo-cli create-token <params>…
    Create an authentication token for XO API.

    <params>…
      Accept the same parameters as register, see its usage.

  xo-cli unregister
    Remove stored credentials.

  xo-cli list-commands [--json] [<pattern>]...
    Returns the list of available commands on the current XO instance.

    The patterns can be used to filter on command names.

  xo-cli list-objects [--<property>]… [<property>=<value>]...
    Returns a list of XO objects.

    --<property>
      Restricts displayed properties to those listed.

    <property>=<value>
      Restricted displayed objects to those matching the patterns.

  xo-cli <command> [--json] [<name>=<value>]...
    Executes a command on the current XO instance.

    --json
      Prints the result in JSON format.

  xo-cli rest del <resource>
    Delete the resource.

    Examples:
      xo-cli rest del tasks/<task id>
      xo-cli rest del vms/<vm id>/tags/<tag>

  xo-cli rest get <collection> [fields=<fields>] [filter=<filter>] [limit=<limit>]
    List objects in a REST API collection.

    <collection>
      Full path of the collection to list

    fields=<fields>
      When provided, returns a collection of objects containing the requested
      fields instead of the simply the objects' paths.

      The field names must be separated by commas.

    filter=<filter>
      List only objects that match the filter

      Syntax: https://xen-orchestra.com/docs/manage_infrastructure.html#filter-syntax

    limit=<limit>
      Maximum number of objects to list, e.g. `limit=10`

    Examples:
      xo-cli rest get
      xo-cli rest get tasks filter='status:pending'
      xo-cli rest get vms fields=name_label,power_state

  xo-cli rest get [--output <file>] <object> [wait | wait=result]
    Show an object from the REST API.

    --output <file>
      If specified, the response will be saved in <file> instead of being parsed.

      If <file> ends with `/`, it will be considered as the directory in which
      to save the response, and the filename will be last part of the <object> path.

    <object>
      Full path of the object to show

    wait
      If the object is a task, waits for it to be updated before returning.

    wait=result
      If the object is a task, waits for it to be finished before returning.

    Examples:
      xo-cli rest get vms/<VM UUID>
      xo-cli rest get tasks/<task id>/actions wait=result

  xo-cli rest patch <object> <name>=<value>...
    Update properties of an object (not all properties are writable).

    <object>
      Full path of the object to update

    <name>=<value>...
      Properties to update on the object

    Examples:
      xo-cli rest patch vms/<VM UUID> name_label='My VM' name_description='Its description

  xo-cli rest post <action> <name>=<value>...
    Execute an action.

    <action>
      Full path of the action to execute

    <name>=<value>...
      Paramaters to pass to the action

    Examples:
      xo-cli rest post tasks/<task id>/actions/abort
      xo-cli rest post vms/<VM UUID>/actions/snapshot name_label='My snapshot'

  xo-cli rest put <collection>/<item id> <name>=<value>...
    Put a item in a collection

    <collection>/<item id>
      Full path of the item to add

    <name>=<value>...
      Properties of the item

    Examples:
      xo-cli rest put vms/<vm id>/tags/<tag>

# Register your XO instance

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

Note: only a token will be saved in the configuration file.

# List available objects

Prints all objects:

xo-cli list-objects

It is possible to filter on object properties, for instance to print all VM templates:

xo-cli list-objects type=VM-template

# List available commands

xo-cli list-commands

Commands can be filtered using patterns:

xo-cli list-commands '{user,group}.*'

# Execute a command

The same syntax is used for all commands: xo-cli <command> <param name>=<value>...

E.g., adding a new server:

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

The return value is the identifier of this new server in XO.

Parameters (except true and false which are correctly parsed as booleans) are assumed to be strings. For other types, you may use JSON encoding by prefixing with json::

xo-cli foo.bar baz='json:[1, 2, 3]'
# VM export
xo-cli vm.export vm=a01667e0-8e29-49fc-a550-17be4226783c @=vm.xva
# VM import
xo-cli vm.import sr=60a6939e-8b0a-4352-9954-5bde44bcdf7d @=vm.xva

Note: xo-cli only supports the import of XVA files. It will not import OVA files. To import OVA images, you must use the XOA web UI or use xo-upload-ova available here (opens new window).

# API

Our web UI (xo-web) and CLI (xo-cli) both talk to xo-server via the same API. This API works in a kind of "connected mode", using JSON-RPC through websockets, in a way where we can subscribe to any events to always stay up-to-date on the client side.

WARNING

However, this API was initially meant to only be private. Also, as it's JSON-RPC inside websockets, it's not trivial to use. If you want to make calls in an easy fashion, you should take a look at our REST API.

If you need assistance on how to use it:

  1. Try to use xo-cli first. You'll learn all the available calls
  2. A good intro can be find within xo-lib (opens new window)
  3. Create a support ticket asking us for precise call you want to make, we'll help you!

# Plugins

Xen Orchestra plugins allow you to extend features without rewriting the core of the application.

You can see your installed plugins in "Settings" then the "Plugins" page:

All plugin configuration should be done in the web interface:

A plugin can be:

  • activated/deactivated
  • loaded on start of the application
  • configured (extend the plugin settings by clicking on the "+" icon

← Troubleshooting →