Documentation and guides

Running MirageOS Xen kernels

Building a MirageOS unikernel for the Xen backend results in a Xen PV kernel with a .xen extension. This must be booted as a normal Xen domU kernel. If you manage your own Xen, you'll be able to use configuration information automatically generated by mirage; some advice on booting with popular Xen-based cloud providers is also given below.

Locally Managed Xen

For recent Xen versions, Mirage will attempt to provide a reasonable configuration document for use with the xl tool. The filename will be based on the string argument given to register in the unikernel's config.ml. For instance, if your config.ml has lines like this:

let () =
  register "hello" [main $ default_posix_clock]

then running

    $ mirage configure -t xen

will generate a hello.xl file which references the location where the Xen machine image will be created. After running

    $ make depend
    $ make

the compiled machine image should be present at hello.xen.

    $ sudo xl create hello.xl -c

will try to boot the unikernel and attach a console in the terminal from which the command was run. To detach the console and recover the terminal, use Ctrl-]. The unikernel will continue running, and you can resume viewing the console output with

    $ sudo xl console hello

mirage configure -t xen does its best to generate a good .xl, but frequently the file needs editing to reflect your local configuration. Common changes are the name of the network bridge given on a vif line, and the name or location of disks specified in a disk line.

Amazon EC2

Amazon's Elastic Compute Cloud supports booting user-specified kernels. Currently MirageOS only knows how to create paravirtualized Xen images, so only those instance types which support PV will boot MirageOS unikernels. To see a list of instance types which support PV guests, see the EC2 documentation on virtualization types. Users wishing to run unikernels on the t1.micro instance type will need to create EBS volumes usable in that configuration.

Automated Solutions

Adam Wick created ec2-unikernel for deploying HaLVM on EC2. For users who are happy to install an additional toolchain or outside dependencies, this may be a good, quick, and free solution for deploying Mirage unikernels to EC2.

Less-Automated Solutions

Booting the unikernel requires a two-stage boot process:

To boot a MirageOS kernel on EC2, it must first be copied onto a block device known to AWS. After that, the image needs to be bundled into an Amazon Machine Image (AMI), and then registered as a bootable image using the EC2 tools. Once there is a valid AMI registration, it's possible ot create and boot an instance based on the AMI.

Generating an AMI

First download the API tools and AMI tools from Amazon. Set the following environment 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/ec2.sh in the mirage repository, 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

Rackspace? Other Xen-based Cloud Providers?

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