xen-api

xen-api

Connector to the Xen API

Install

Installation of the npm package:

npm install --save xen-api

Usage

Tested with:

• XenServer 7.6
• XenServer 7.5
• XenServer 7.4
• XenServer 7.3
• XenServer 7.2
• XenServer 7.1
• XenServer 7
• XenServer 6.5
• XenServer 6.2
• XenServer 5.6

Library

const { createClient } = require('xen-api')

const xapi = createClient({
  url: 'https://xen1.company.net',
  allowUnauthorized: false,
  auth: {
    user: 'root',
    password: 'important secret password',
  },
  readOnly: false,
})

Options:

• url: address of a host in the pool we are trying to connect to
• allowUnauthorized: whether to accept self-signed certificates
• auth: credentials used to sign in (can also be specified in the URL)
• readOnly = false: if true, no methods with side-effects can be called
• callTimeout: number of milliseconds after which a call is considered failed (can also be a map of timeouts by methods)
• httpProxy: URL of the HTTP/HTTPS proxy used to reach the host, can include credentials

// Force connection.
xapi.connect().catch(error => {
  console.error(error)
})

// Watch objects.
xapi.objects.on('add', objects => {
  console.log('new objects:', objects)
})

Note: all objects are frozen and cannot be altered!

Custom fields on objects (hidden − ie. non enumerable):

• $type: the type of the object (VM, task, …);
• $ref: the (opaque) reference of the object;
• $id: the identifier of this object (its UUID if any, otherwise its reference);
• $pool: the pool object this object belongs to.

Furthermore, any field containing a reference (or references if an array) can be resolved by prepending the field name with a $:

console.log(xapi.pool.$master.$resident_VMs[0].name_label)
// vm1

Calling a XAPI method

For very fast methods, use call(method, ...args):

const nameLabel = await xapi.call('VM.get_name_label', vmRef)

For methods that could take some time (doing an action, etc.), use callAsync(method, ...args), it will automatically call the asynchronous variant of the method and monitor the associated task:

const snapshotRef = await xapi.callAsync('VM.snapshot', vmRef, 'My snapshot')

Both call() and callAsync() accepts an optional Map-like object as a first parameter to use as a cache:

// to avoid leaking memory, make sure to not keep entries forever
//
// see:
// - https://www.npmjs.com/package/@isaacs/ttlcache
// - https://www.npmjs.com/package/lru-cache
const cache = new Map()

// the first time, the call is really executed
console.log(await xapi.call(cache, 'VM.get_name_label', vmRef))

// next times, the value of the cache is directly returned
console.log(await xapi.call(cache, 'VM.get_name_label', vmRef))

// to delete the entry from the cache, simply compute the key
const key = xapi.computeCacheKey('VM.get_name_label', vmRef)
cache.delete(key)

Note: Failures are not cached.

CLI

A CLI is provided to help exploration and discovery of the XAPI.

> xen-api xen1.company.net root
Password: ******
[e-mail]> xapi.status
'connected'
[e-mail]> xapi.pool.master
'OpaqueRef:ec7c5147-8aee-990f-c70b-0de916a8e993'
[e-mail]> xapi.pool.$master.name_label
'xen1'

You can optionally prefix the address by a protocol: https:// (default) or http://.

In case of error due to invalid or self-signed certificates you can use the --allow-unauthorized flag (or --au):

> xen-api --au xen1.company.net root

To ease searches, find() and findAll() functions are available:

[e-mail]> findAll({ $type: 'VM' }).length
183

To get a record from the local cache:

[e-mail]> vm = getObject('17ccab66-9cc0-90a4-71a5-95874f9ad5e0')

[e-mail]> vm.name_label
'My VM'

[e-mail]> vm.$ref
'OpaqueRef:9a533a13-64bf-4755-ad6a-9b0f67d686ca'

To call a XAPI method:

[e-mail]> call('VM.start', 'OpaqueRef:9a533a13-64bf-4755-ad6a-9b0f67d686ca', false, false)
''

[e-mail]> vm.$call('start', false, false)
''

To call a XAPI method

Contributions

Contributions are very welcomed, either on the documentation or on the code.

You may:

• report any issue you've encountered;
• fork and create a pull request.

License

ISC © Vates SAS