Skip to content

Less Code, Less Magic, More Results

Choose a tag to compare
@yomimono yomimono released this 24 Jan 22:13

Major Changes

  • The solo5 targets ukvm and virtio (see, which allow unikernels to run on KVM hypervisors and on FreeBSD via bhyve, are now available in the mainline mirage package. These targets use a newly refactored freestanding OCaml runtime (see
  • The V1 and V1_LWT modules, which contained module type definitions agreed upon by implementations used in mirage, have been renamed to Mirage_types and Mirage_types_lwt. The module type definitions themselves are no longer contained in this repository, but have been moved to their own independently-versioned repositories and are merely referenced from Mirage_types and Mirage_types_lwt. Users are encouraged to refer to the module types directly (e.g., Mirage_block_lwt.S instead of Mirage_types_lwt.BLOCK), and depend on the corresponding packages.
  • Across the universe of module type definitions, errors in computation are now signalled by a result type and a set of polymorphic variants representing common errors that might occur. Individual implementations may extend this set, and users can always count on the provided module to provide a pretty-printer for these errors.
  • The CLOCK module type has been replaced with PCLOCK and MCLOCK, which represent a POSIX-style wall clock and a monotonically-increasing clock respectively. The Mirage module provides default_posix_clock and default_monotonic_clock for getting an impl of each clock. Existing functions which took a clock impl argument now take an mclock impl wherever this is reasonable (in practice, everywhere except for logs).
  • mirage-types-lwt is now its own opam package, rather than an optionally installed sub-library bundled with mirage-types.
  • mirage configure no longer automatically attempts to install packages. Rather, it generates a .opam file representing the dependencies that have been discovered based on the and the arguments passed to mirage configure. Running make depend against the Makefile generated by mirage configure will attempt to install these dependencies via opam.
  • Documentation for the project is now automatically built and provided via odig.
  • The build system for mirage and many other libraries has been changed from OASIS to topkg.

Less Major API changes to Mirage module

  • Mirage.register and Mirage.foreign no longer take a libraries argument. Their packages argument is now of type Functoria.package list, and the library information is included in package.
  • connect functions provided by individual implementations are no longer expected to return a t result or Ok t by the mirage front-end tool's code generation. Rather, they are expected to raise an exception on failure and return the value directly on success.
  • Two random impls are now available - stdlib_random, which wraps the OCaml Random module, and nocrypto_random, which is a passthrough to the Fortuna PRNG implemented in the nocrypto library. default_random is available for accessing stdlib_random by default, but can be told to use nocrypto_random at compile or runtime via the prng key.
  • A syslog implementation is usable from mirage. Construct a record of type Mirage.syslog_config and call Mirage.syslog_udp, Mirage.syslog_tcp, or Mirage.syslog_tls to obtain a syslog impl.
  • Functions for interfacing with the mirage-qubes library are now included: Mirage.qubes_ipv4_stack and Mirage.ipv4_qubes, as well as Mirage.default_qubesdb. Unikernels which are built with these functions will fail unless mirage configure is invoked with -t qubes.
  • Mirage.tap0 has been renamed to Mirage.default_network and now works as expected on Xen targets.
  • Mirage.farp is available as an alternative to Mirage.arp, and will use instead of the ARP implementation in mirage-tcpip.
  • The Mirage.ipv4_config and Mirage.ipv6_config types have been changed to reflect reasonable configuration assumptions rather than attempt to mirror one another's structure.
  • Mirage.create_ipv4 now takes ethernet impl and arpv4 impl arguments, rather than creating an ipv4 impl directly from a network impl and hiding the intermediate ethernet and arpv4 from the caller.
  • Mirage.create_ipv6 now takes an ethernet impl argument rather than a network impl argument.
  • Mirage.default_ipv4 has been removed.
  • Mirage.direct_udp now takes an optional random impl argument.
  • Functions which yield a stackv4 impl now take an ipv4 impl argument instead of a network impl.
  • Mirage.direct_stackv4_with_default_ipv4 and direct_stackv4_with_static_ipv4 no longer exist. Instead, consider using direct_stackv4, static_ipv4_stack, or dhcp_ipv4_stack.
  • Network-related functions which took a console impl argument no longer do so.
  • Mirage.get_mode, Mirage.add_to_opam_packages, and Mirage.add_to_ocamlfind_libraries have been removed (as warned in the 2.9.1 release).

Less Major API changes to Mirage_key module

  • Mirage_key.is_xen has been removed and Mirage_key.is_unix added, as that is the more exceptional case.
  • Mirage_key.ipv4 is now an (Ipaddr.V4.Prefix.t * Ipaddr.V4.t) converter. For an Ipaddr.V4.t converter, use the new Mirage_key.ipv4_address.
  • A type Mirage_key.mode is available for referring to the set of polymorphic variants including Unix, Xen, MacOSX, Ukvm, Virtio, and Qubes.
  • Mirage_key.no_ocaml_check has been removed.
  • Mirage_key.kv_ro may now produce a direct key in addition to Archive, Crunch, and Fat keys.
  • Mirage_key.prng is available for choosing between the standard library and nocrypto random implementations.
  • has been renamed to Mirage_key.interface, as network has been repurposed in the Mirage_key.V4 and Mirage_key.V6 modules.
  • Mirage_key.V4.ip and Mirage_key.V4.netmask have been replaced with, which treats the IP and netmask as a single item.
  • Mirage_key.V4.gateways has been replaced with Mirage_key.V4.gateway, which is a t option instead of the previous t list.
  • Mirage_key.V6.ip and Mirage_key.V6.netmask have been replaced with Mirage_key.V6.ips and Mirage_key.V6.netmasks respectively, which accept lists instead of single items.

Less Major API changes outside of mirage

  • format function and Format_unknown error have been removed from the FS module type in mirage-fs.
  • read_stream, io_stream, and read_until have been removed from the CHANNEL module type in mirage-channel.
  • log has been removed from the CONSOLE module type in mirage-console. log_s has been renamed to log to replace it.
  • id has been removed from the DEVICE module type in mirage-device.
  • The RANDOM module type provided by mirage-random now includes a function generate that provides random bytes as a buffer (currently a Cstruct.t), replacing the previous int-based interface.
  • A mem function is now required by the KV_RO module type in mirage-kv.
  • The read and size functions required by the KV_RO module type in mirage-kv now take int64s rather than ints.
  • sleep (which took a float argument representing the number of seconds) has been replaced by sleep_ns (which takes an int64 representing the numer of nanoseconds) in the module type TIME provided by mirage-time.
  • IP source and destination argument names have been standardized to src and dst, and source and destination ports to src_port and dst_port, in the module types provided by mirage-protocols.
  • The pseudoheader function is now required for IP module types in mirage-protocols.

Less Major Usage Changes

  • An additional target qubes exists for automatically packaging the additional libraries and initialization logic necessary for running MirageOS on QubesOS. The qubes target is at its heart xen plus some other stuff.
  • mirage configure -f will no longer traverse into subdirectories. mirage configure needs to be called with a working directory the same as the configuration file.
  • mirage configure --unix and mirage configure --xen are no longer understood, as warned in the 2.9.1 release. Instead, use mirage configure -t unix and mirage configure -t xen respectively.
  • The artifact generated by make is no longer prefixed with mir-, and the name given to register will be stripped of OCaml-unfriendly characters before files are written.

Bugfixes and Other Improvements

  • Functions used by mirage-generated programs at runtime have been split off into the mirage-runtime package, which will be linked instead of the full mirage package. (This is largely the collection of parsers for runtime keys.)
  • The mirage command-line utility is now at for easier discovery.
  • It's now possible to get an ipv6 impl.
  • Tar file generators for use with tar-format implementations are less broken.
  • The Str module is no longer included in the OCaml runtime.
  • Emit an ocamlfind predicate that matches the target.
  • Improvements to nocrypto handling.
  • Using crunch always requires io-page.
  • Xen unikernels will no longer refuse to start when they receive unexpected boot parameters.
  • Disable warning #42 in generated code.
  • mirage-fs provides transforming FS into KV_RO, rather than requiring fat-filesystem.
  • UDP now provides source port randomization even with the direct stack.
  • DHCP is now provided by charrua-client and charrua-core rather than tcpip.
  • Link libgcc.a only when building on ARM.
  • Stop generating so many unnecessary artifacts.
  • clean target removes more artifacts.
  • Comply with mirage-clock-xen's rename to mirage-clock-freestanding.