Search documentation of macula

# macula_tun (macula v4.4.1)

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(&lt;&lt;"macula0"&gt;&gt;, 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.