node-xl-wrapper

Node.js wrapper around local or remote Xen xl management utility

This is a work in progress and should not be used yet !!!

You have been warned

Requirements

Client-Side

The side that is running the Node-Application using this lib

Node.js -- tested with 0.10.33, if you tested older versions, let me know

Server-Side

The sie that is running Xen and xl

SSH server -- OpenSSH for example
Xen with xl as toolstack -- tested with Xen 4.4
A user with access to the xl command -- I would strongly recommend you to read the security recommendations!

API documentation

Constructor

new XL(options)

Options must at least contain the property executorName which can currently be set to local to execute the commands on the local machine (via child_process.spawn()) or ssh to execute the commands on a remote machine via a SSH connection (done by ssh2).

Supported properties:

executorName (String) - Required: Name of the executor to use for executing xl commands (local or ssh)
executorOptions (Object) - See below for a detailed explanation
filter (String | RegExp) default: .* - This can optionally be used to restrict a session to specific DomU names. All commands only work if the accessed DomU's name matches the string (strictly) or the RegExp (test()). Other commands like list filter all DomUs from the output, that don't match this filter.

The executorOptions are split in two parts. For all currently supported executors you can use these options:

sudo (Boolean) default: false - Prefix all commands with sudo (see security recommendations)
debug (Boolean) default: false - Show debug output
verbose (Boolean) default: false - Show a more verbose debug output

Specific options for the executor ssh are:

host (String) - Hostname or IP of the SSH server
port (Number) default: 22 - Port of the SSH server
username (String) - Username for login
password (String) - Password for login
privateKey (String | Buffer) - Content of the private key file for public key authentication (OpenSSH format).
.. and many more. In general you can use all ssh2 connect options. There is one custom addition though:
persistent (Boolean) default: false - Use a persistent SSH connection. It is strongly recommended to enable this if you send more than one command over this SSH connection, because otherwise the connection has to be established for each command execution individually. This leads to a massive overhead.

Specific options for the executor local are:

none 😄

Commands

To execute a command you have to instantiate XL and call the command you like. Example:

var XL = require('node-xl-wrapper');
var con = new XL({
    'executorName': 'local'
});
con.shutdown({
    'name': 'myDomU'
}, function(err, data) {
    // Do what you want with the returned data
    // Data is generally the stdout string of the xl command or a object (e.g. for list)
});

You can omit the first parameter (options object) if the command has no options or you don't want to pass any.

The commands are named after their corresponding xl commands. Currently these are supported:

Security recommendations

First of all: Never ever use the root user to run this lib in production!

As you can see it supports using the sudo command when configured via the constructor options. To use this you have to create a new user, let's call him xlrunner. Then edit the /etc/sudoers file using the command visudo and append this line (of course change the username if you created another user):

xlrunner      ALL=NOPASSWD:   /usr/sbin/xl

Your new user should now have the permission to execute the xl command with prefixed sudo and arbitrary arguments. You may restrict these arguments for your use case. There are plenty how-tos out there to achieve this.

My second recommendation is to use public key authentication instead of password-based one. Just read a how-to about it. It's worth it.

benurb/node-xl-wrapper