client.md

Client

Clients manage a connection to an LXC instance, either locally or remotely.

Connection

To create a new client on the local domain socket, require and call node-lxd without any arguments. No data is sent until an action is performed, so you can't be sure the connection was successful until you attempt an action.

var lxd = require("node-lxd");
var client = lxd();

To connect to a remote client, specify the protocol (http || https), host and port by passing it to the node-lxd.

var lxd = require("node-lxd");
var client = lxd("https://instance.mycompany.io:1234");

You can also authenticate to your server with certificate and key:

var lxd = require("node-lxd");
var client = lxd("https://instance.mycompany.io:1234", {
    cert: fs.readFileSync(__dirname + '/cert.pem'),
    key: fs.readFileSync(__dirname + '/key.pem'),
    password: 'password' // password to lxd server
});

Errors

Throughout the node-lxd docs, most callback functions will provide an err parameter. This is either null if no error occured, or an OperationError if the command failed. The client provides the error message and status information provided by lxd.

function callback(err, ...) {
  console.error(err.getMessage());
  console.error(err.getStatus());
  console.error(err.getStatusCode());
}

Containers

Containers are a form of virtualization that creates a mini-environment ontop of your existing operating system, with near bare metal speeds. Unlike other virtualisation techniques, the programs run on the host operating system, resulting in faster performance, efficency and boot times.

Creating

To create a container, call create on your newly connected client. You will need to setup some images prior, follow the tutorials on the LXD website to do so. I'll assume you've imported the ubuntu image throughout this doc. The first argument specifies a 64-character ASCII name for the container, the second contains the image name.

client.create("container-name", "ubuntu", function(err, container) {
  if (err) {
    console.error(err.getMessage());
  } else {
    console.log(container.name() + " created!");
  }
});

For simplicity, call launch to both create and start a container.

client.launch("container-name", "ubuntu", function(err, container) {
  if (err) {
    console.error(err.getMessage());
  } else {
    console.log(container.name() + " started!");
  }
});

You can also pass standard LXD configuration by providing the configuration parameter to either launch or create.

client.launch("container-name", "ubuntu", {
  "limits.memory" : "512MB"
}, function(err, container) {
  if (err) {
    console.error(err.getMessage());
  } else {
    console.log(container.name() + " started with 512MB (hard limit)!");
  }
});

It is also possible to pass own source according to lxd rest api:

client.launch("container-name", {
  "type": "image",                             // Can be: "image", "migration", "copy" or "none"
  "mode": "pull",                              // One of "local" (default) or "pull"
  "server": "https://10.0.2.3:8443",           // Remote server (pull mode only)
  "protocol": "lxd",                           // Protocol (one of lxd or simplestreams, defaults to lxd)
  "certificate": "PEM certificate",            // Optional PEM certificate. If not mentioned, system CA is used.
  "alias": "ubuntu/devel"
}, {
  "limits.memory" : "512MB"
}, function(err, container) {
  if (err) {
    console.error(err.getMessage());
  } else {
    console.log(container.name() + " started with 512MB (hard limit)!");
  }
});

Get container

To get a container by name, call container and pass the name of the container. If successful, container will be a Container object.

client.container("container-name", function(err, container) {
  console.log("container's ip: " + container.ipv4());
});

Get containers

To list all the containers on an instance, call containers. If you have more than five or ten containers, you should call this function lazily, which only downloads the names of the containers instead of their status.

client.containers(function(err, containers) {
  for (var i = 0; i < containers.length; i++) {
    console.log(containers[i].name()); // containers are actual objects
  }
});

or lazily:

client.containers(true, function(err, containers) {
  for (var i = 0; i < containers.length; i++) {
    console.log(containers[i]); // containers are just names
  }
});

Info

To get information about the LXC instance the client is connected to, call info.

client.info(function(err, info) {
  console.log(info);
});

This returns an object of this format:

{
    api_compat:1,
    auth:'trusted',
    config:{ },
    environment:{
        addresses:[],
        architectures:[ 2, 1 ],
        driver:'lxc',
        driver_version:'2.0.0.beta2',
        kernel:'Linux',
        kernel_architecture:'x86_64',
        kernel_version:'3.19.0-25-generic',
        server:'lxd',
        server_pid:4153,
        server_version:'2.0.0.beta1',
        storage:'btrfs',
        storage_version:'3.12'
    }
}