macula_tun (macula v4.0.0)

View Source

TUN device lifecycle for macula-net.

High-level facade over macula_tun_nif. The NIF owns all kernel-side syscalls (open / write / reader-thread / close); this module keeps the BEAM-side API stable and ergonomic.

Usage

   {ok, Tun} = macula_tun:open(<<"macula0">>, 1280),
   ok        = macula_tun:start_reader(Tun, self()),
   ok        = macula_tun:write(Tun, IPv6Packet),
   ...
   ok        = macula_tun:close(Tun).

After start_reader/2, the calling process (or the supplied Pid) receives messages of shape {macula_net_packet, Handle, Payload} for every packet read from the TUN.

Requires CAP_NET_ADMIN. Without it, open/2 returns {error, ...} and the operator should consult the runbook (PLAN_MACULA_NET.md §10.3).

Summary

Types

handle/0
if_name/0

e.g. <<"macula0">>

ipv6_packet/0
mtu/0

Functions

close(Handle)

Close the TUN device. Idempotent; the device is also closed automatically when BEAM GCs the handle.

name(Handle)

Return the actual interface name assigned by the kernel.

open(IfName, Mtu)

Create a TUN device. Kernel may pick a different actual name on conflict; use name/1 to confirm.

start_reader(Handle, Pid)

Spawn the reader thread. Subsequent packets read from the TUN are delivered to Pid as {macula_net_packet, Handle, Payload}.

write(Handle, Packet)

Write a complete IPv6 packet to the TUN device.

Types

handle/0

-opaque handle()

if_name/0

-type if_name() :: binary().

e.g. <<"macula0">>

ipv6_packet/0

-type ipv6_packet() :: binary().

mtu/0

-type mtu() :: 1280..65535.

Functions

close(Handle)

-spec close(handle()) -> ok | {error, term()}.

Close the TUN device. Idempotent; the device is also closed automatically when BEAM GCs the handle.

name(Handle)

-spec name(handle()) -> {ok, binary()} | {error, term()}.

Return the actual interface name assigned by the kernel.

open(IfName, Mtu)

-spec open(if_name(), mtu()) -> {ok, handle()} | {error, term()}.

Create a TUN device. Kernel may pick a different actual name on conflict; use name/1 to confirm.

start_reader(Handle, Pid)

-spec start_reader(handle(), pid()) -> ok | {error, term()}.

Spawn the reader thread. Subsequent packets read from the TUN are delivered to Pid as {macula_net_packet, Handle, Payload}.

write(Handle, Packet)

-spec write(handle(), ipv6_packet()) -> ok | {error, term()}.

Write a complete IPv6 packet to the TUN device.