tuntap#

Host TAP device binding, exposing the device as an Eio flow of raw Ethernet frames.

Installation#

Install with opam:

$ opam install tuntap

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install tuntap

Overview#

A TAP device is a virtual link-layer interface. Frames written to the flow are injected on the interface; frames the kernel sends to the interface are read from the flow. tuntap opens and configures the device through ioctl / netlink and wraps its file descriptor as an Eio.Flow.two_way, so a frame processor (a bridge, a switch, the firewall engine) can read and write raw Ethernet directly.

The raw bindings are vendored from mirage/ocaml-tuntap (the C stubs for TUNSETIFF and the link ioctls), trimmed to the TAP path; this package adds the Eio flow adapter and a few link attributes.

Creating and configuring a device needs privilege (CAP_NET_ADMIN / root). Linux and macOS are supported; set_master (enslaving to a bridge) is Linux only.

Features#

• create / destroy a TAP device, persistent or transient.
• The device as an Eio.Flow.two_way of raw Ethernet frames.
• Link attributes: bring up, set MTU, assign an IPv4 address, enslave to a bridge.
• Read back the MTU and MAC.

Usage#

Opening a device needs privilege, so this example is wrapped in a function rather than run inline:

let main () =
  Eio_main.run @@ fun _env ->
  Eio.Switch.run @@ fun sw ->
  let tap = Tuntap.v ~sw ~name:"tap0" () in
  Tuntap.set_mtu tap 1500;
  Tuntap.add_addr tap
    ~netmask:(Ipaddr.V4.Prefix.of_string_exn "0.0.0.0/24")
    (Ipaddr.V4.of_string_exn "10.0.0.1");
  let flow = Tuntap.flow tap in
  (* read and write raw Ethernet frames on [flow] *)
  ignore flow

Related Work#

• mirage/ocaml-tuntap - the upstream TUN/TAP bindings these C stubs are vendored from. This package keeps the raw layer and adds an Eio flow rather than exposing a bare Unix.file_descr.
• vmnet - the macOS vmnet framework binding, an alternative host networking path.
• The Go songgao/water and Rust tun crates offer the same primitive in other ecosystems.

License#

ISC License. See LICENSE.md for details.