Mirage applications can be compiled all into micro-kernels, and so have to handle traffic from Ethernet and up. Ethernet is a low-level protocol that encapsulates IPv4, which in turns drives the reliable TCP protocol. This web-page is then served over the HTTP request/response protocol. The Mirage standard library includes an implementation of all these protocols, written in pure OCaml.

Actually developing complex code in a micro-kernel environment is not terribly productive, as you do not have access to the usual UNIX debugging tools. Luckily, many variants of UNIX provide the facility to "tap" Ethernet traffic into user-space directly via the Tuntap interface. This page describes how to get Mirage up and running with Ethernet traffic under UNIX.

• First, ensure you have a working Mirage installation by following the INSTALL file in the source repository. You can verify it by running cd tests/basic/sleep && mir-unix-direct sleep.bin && ./_build/sleep.bin from the root source directory.

• Next, make sure your operating system supports the tuntap driver. On MacOS X, you will need to install TunTapOSX. Most Linux distributions will have it already enabled by default. I havent had a chance to run this on *BSD yet; it will likely require a minor patch to the driver as the ioctl interface varies between implementations.

• Build tests/net/tcp_echo by cd tests/net/tcp_echo && mir-unix-direct echo.bin from the root of the source repository. If successful, you then run sudo ./_build/echo.bin, that should start up on the interface.

• The details of how to connect now vary by OS:

  • MacOS X unfortunately does not support Ethernet bridging, which means that you cannot talk to the outside world. The driver automatically assigns an IP address of 10.0.0.1 netmask 255.255.255.0 to the tun0 interface (see code). The test application uses 10.0.0.2 for itself, and so you can test it by ping 10.0.0.2. If you see ping replies, and some debug output from the application, you are set!

  • Linux does support bridging, but this is not set up by default. After running the test application, run ifconfig tap0 10.0.0.1 netmask 255.255.255.0 to set up the tap0 interface (remember the interface will not be created until the application is run, so you cannot configure it before). Then try to ping 10.0.0.2 and see if you get a response.

  • The network stack is configured statically at the moment by editing lib/net/direct/config.ml. Select the right function (either DHCP or a static IP assignment) and applications will be compiled with the right policy. In the future, we plan to add a configuration syntax extension that will add the right configuration module at application build-time (rather than the Mirage library build-time as it currently is).

• Once this is working, you can play around with the rest of the protocol stack in lib/net/direct:

  • ARP translates between Ethernet MAC addresses and IP addresses.

  • ICMP is a control protocol for IP, usually to send back errors. IPv4 is in lib/net/direct/ipv4.ml.

  • The datagram protocol UDP is in lib/net/direct/udp.ml, and an experimental TCP stack is in lib/net/direct/tcp.ml.

  • If you have Ethernet bridging, you can use the DHCP client in lib/net/direct/dhcp/client.ml to get an IP address.

  • Finally, a full DNS server exists in lib/net/dns. No DNS client exists, but it should be fairly easy to extend the server code.

If you want to modify the code, then just edit any of those ML files, and type in make && make install at the top-level of the repository, and then rebuild the application. You should get familiar with the tcpdump utility, and graphical ones like Wireshark. Run these against the tap0 interface, for example:

$ sudo tcpdump -i tap0 -vvvx

This will show you the protocol traffic appearing on the bridge.