TUN device support for Elixir.

Tundra provides a simple API for creating and using TUN devices on Linux and Darwin.

TUN device creation is a privileged operation requiring root or CAP_NET_ADMIN on Linux. Tundra supports two modes of operation:

1. Direct creation (Linux only): When the BEAM VM runs with sufficient privileges, Tundra creates TUN devices directly via the NIF without requiring a server process.

2. Server-based creation: When the BEAM VM lacks privileges, Tundra delegates device creation to a separate privileged server daemon (tundra_server).

Tundra automatically attempts direct creation first and falls back to the server if privileges are insufficient. Once created, the device is represented within the runtime as a socket on Darwin and a NIF resource on Linux, with process-ownership semantics:

• Only the owning process can read from or write to the device and receive i/o notifications from it.
• The TUN device is removed when the owning process exits.

Server Process

For unprivileged operation, Tundra requires a separate privileged server daemon (tundra_server) to be running. The server is a standalone C program located in the c_src/server/ directory and must be built and started independently with root privileges before using the Tundra library.

The server listens on a Unix domain socket at /var/run/tundra.sock and accepts requests from the NIF to create and configure TUN devices. The resulting file descriptor is sent back to the NIF via SCM_RIGHTS, which then creates a socket from it (on Darwin) or wraps it in a NIF resource (on Linux).

Users connecting to the server must be members of the tundra group. On Linux, use sudo usermod -aG tundra $USER; on macOS, use sudo dseditgroup -o edit -a $USER -t user tundra. Log out and back in after adding yourself to the group.

See the c_src/server/README.md file for instructions on building and running the server.

Non-blocking I/O

Tundra only supports non-blocking I/O on TUN devices. The recv/3 and send/3 functions currently require that :nowait is pssed as the last argument. If the operation would block, the function will return {:select, select_info} and a notification of the following form will be sent to the owning process when the device is ready:

{:"$socket", dev, :select, select_handle}

Note that, although on Linux the underlying TUN device is not technically a socket, the same notification is used to reduce platform specific code. Only the contents of dev differ.

IPv6

Tundra is designed to work with IPv6 and has only been tested with IPv6.

Example

The following GenServer creates a TUN device and then relays packets by

1. Reading a frame from the device
2. Swapping the source and destination addresses
3. Writing the modified frame back to the device

defmodule Reflector do
  use GenServer

  @mtu 1500

  def start_link(_), do: GenServer.start_link(__MODULE__, [], name: __MODULE__)

  @impl true
  def init(_args) do
    # Create a TUN device with the given address and options
    {:ok, state} =
      Tundra.create("fd11:b7b7:4360::2",
        dstaddr: "fd11:b7b7:4360::1",
        netmask: "ffff:ffff:ffff:ffff::",
        mtu: @mtu)
    {:ok, state, {:continue, :read}}
  end

  @impl true
  def handle_continue(:read, {dev, _} = state) do
    # Read a frame from the device
    case Tundra.recv(dev, @mtu, :nowait) do
      {:ok, data} ->
        {:noreply, state, {:continue, {:reflect, data}}}
      {:select, _} ->
        {:noreply, state}
    end
  end

  def handle_continue({:reflect, data}, {dev, _} = state) do
    # Swap the source and destination addresses of the IPv6 packet
    <<pre::binary-size(8),
      src::binary-size(16),
      dst::binary-size(16),
      rest::binary>> = data
    reflected = [pre, dst, src, rest]

    # Write the frame back to the device, assume it won't block
    :ok = Tundra.send(dev, reflected, :nowait)
    {:noreply, state, {:continue, :read}}
  end

  @impl true
  def handle_info({:"$socket", dev, :select, _}, {dev, _} = state) do
    # Handle 'input ready' notifications
    {:noreply, state, {:continue, :read}}
  end

end