Documentation and guides

Running MirageOS Xen kernels

Building a MirageOS unikernel for Xen, e.g., as at the end of how to build the MirageOS website results in a Xen PV kernel with a .xen extension. This must be booted as a normal Xen domU kernel. The specifics vary based on your setup or cloud provider, and in some cases are wrapped up in the Mirari configuration and deployment tool.

Open Source Xen

When using open-source Xen, you need to create a configuration file, e.g., app.cfg, for the VM that looks something like:


You can launch this domain with xm create -c app.cfg (for Xen versions earlier than 4.1) and xl create -c app.cfg for Xen 4.1 or greater.

Alternatively, for Xen versions greater than 4.1, you can simply invoke Mirage to do this for you:

    $ mirage configure -t xen
    $ make

The MirageOS website contains an example. Thie mirage configure will create an xl configuration file, and you will then need to edit it to add any VIFs or disks required by your application. Consult the Xen documentation for your distro for the specifics on this.

Amazon EC2

Amazon has recently added support for booting user-specified kernels. This involves a two-stage boot procedure behind the scenes:

So to boot a MirageOS kernel on EC2, it must first be wrapped in a block device. After that, the image needs to be bundled into an AMI, and then registered as a bootable image using the EC2 tools.

Command Line Tools

First download the API tools and AMI tools from Amazon. Edit your .profile to add the following variables:

There is a script that then takes care of packaging up the MirageOS kernel image and uploading it to Amazon automatically.. It is found at scripts/, and you specify your kernel.xen file as the first argument to the script.

Using micro instances

To use the EC2 t1.micro instances the kernel needs to reside inside an EBS volume. To create a bootable EBS volume containing an MirageOS kernel use the following steps:

    default 0
    timeout 1
    title Mirage-Test
         root (hd0,0)
         kernel /kernel

This process could be put in a script easily.

Xen Cloud Platform

The Xen Cloud Platform is a distribution that provides cluster-wide support for multi-tenant VMs. It uses a command-line interface and an XML-RPC API to configure and control VMs.

There is a script in scripts/ that takes a kernel.xen output from MirageOS and makes the appropriate API and SSH calls. Thanks to Mike McClurg from Citrix for contributing this script.

Rackspace Cloud

Noone has tried this yet. Get in touch if you do!