Muen

The instructions in this article have been tested with Muen revision 1cd1f88.

MirageOS heavily depends on the OCaml Package Manager (OPAM) as its build system. Follow the installation instructions here to setup OPAM on your system. However, do not yet install mirage until after the next step.

Solo5 comes bundled with simple test cases, most of which can be executed on Muen in QEMU/KVM. Download Solo5 and build the tests like so:

Then, build the tests:

This should leave you with a Hello World unikernel ready to go, which you can find at tests/test_hello/test_hello.muen. Post-process the compiled binary with the solo5-muen-gencspec script invoking it from the Muen toplevel directory as follows:

The script generates a Muen component specification for the unikernel and copies the test_hello.muen binary to the Muen build directory. It is expected to be found in the policy/obj directory when assembling the Muen system image.

Finally, emulate the system:

The unikernel does not produce any VGA output but you should see the following messages in the log:

The mirage-skeleton repository contains example unikernels. One of these examples serves a static website.

The content that will be served can be found in the htdocs directory. You can replace it with something more interesting, e.g. an article about your successful adventures with MirageOS and Muen.

Which IP address the unikernel is supposed to use is configured via the --ipv4* options that can either be passed as unikernel configure parameters or using the --bootparams parameter of the solo5-muen-gencspec.py script.

To serve the website from 192.168.254.10, build the static_website_tls unikernel by issuing the following commands:

If all goes well an unikernel image called https.muen should be present in the current directory.

As before, process the ELF binary using the solo5-muen-gencspec.py script:

The unikernel serves the website via https on port 4433. Since we are using QEMU’s host forwarding to expose networking of the emulated system to the host, we must forward this port by setting the QEMU_NETDEV_EXTRA_OPTS environment variable:

Now once more build and emulate the system:

Since system startup time varies, you can check the log file to make sure networking is up and ready:

Finally, you can point your browser to https://localhost:4433/ and after accepting the certificate warnings you should see the static website served by MirageOS. Congratulations, you have just successfully served yourself a website via a MirageOS unikernel running on Muen!

The following graph gives an overview of the muen.sk system image build process:

In order to be able to serve the page via the TLS stack provided by MirageOS, up to date SSL/TLS certificates are required. We use Letsencrypt certificates for that purpose.

Therefore, the first step in the build process is to check whether the currently deployed certificates are still valid. This is done using openssl:

The command checks whether the certificate expires within 30 days. If renewal is required, a new certificate is requested via the standalone feature of the Letsencrypt’s certbot client. The certificate files are then added as content of stage one in the multi-stage Docker build.

The complete Muen system image build consists of two Docker images:

These images can be found on our GitHub page. The key is to import artifacts from the previous build stage into the next one using the COPY --from syntax. The following commands serve as an example of how to copy the unikernel binary the MirageOS container to the Muen system image build stage:

The assembled Muen system image containing the unikernel subject serving the Muen website is copied out of the final Docker container. Because we want the target system to only boot cryptographically verified images, the image is signed using the following command (as described by the iPXE homepage):

memdisk is a small kernel extracted from syslinux required to reliably boot the ISO image via HTTP(S). The files and associated signatures are uploaded to a webserver which is reachable by the target system.

In order to support image signature verification, the iPXE bootloader must be compiled with the IMAGE_TRUST_CMD option enabled:

The following script instructs iPXE to only boot images which are deemed trusted (i.e. which have a valid signature). Besides the general networking setup steps, it fetches the memdisk kernel and the Muen system image containing our MirageOS webserver subject from a given URL and then verifies the associated signatures. The imgstat command is for debugging purposes and displays the current image state before booting the verified Muen system.

The files are signed using a certificate issued by our own private CA. In order for iPXE to successfully verify such a signature, we need to embed and trust the appropriate certificates. The CERT and TRUST environment variables can be used for this:

This command compiles a bootable iPXE image which can be dumped onto an USB stick. The certificates specified via CERT are embedded into the image. Since embedded certificates are not automatically trusted, our CA must be specified explicitly via the TRUST option.

The DEBUG option is very helpful during initial testing if the image fetching or signature verification step fails for some reason.

The last step of the build process is to trigger a restart of the target system via Intel AMT functionality. The target system restarts and performs the steps depicted in the following graph:

Your minimal, unikernel-based website should now be served at the configured IP after system start.