View Source tuncer (tunctl v0.3.4)
Summary
Functions
Configure the broadcast address for a TUN/TAP device.
Change the controlling process of the TUN/TAP device.
Create the tap0 device.
Create a named tap device.
Create a tuntap device.
Remove the TUN/TAP device.
Get the TUN/TAP device name.
Unconfigure a TUN/TAP device.
Configure the remote address for a TUN/TAP device in point-to-point mode.
Returns an integer holding the interface creation flags.
Get TUN/TAP device file descriptor.
Set the GID owning the interface.
Parse TUN/TAP packet header.
Get the MTU (maximum transmission unit) for the TUN/TAP device.
Set the UID owning the interface.
Set the interface to exist after the Erlang process exits.
Read data from the tuntap device file descriptor.
Read up to the specified number of bytes from the tuntap device file descriptor.
Read data to the tuntap device.
Read up to the specified number of bytes from the tuntap device.
Write data to the tuntap device.
Set TUN/TAP device option.
Configure a TUN/TAP device using the default netmask and broadcast for the network.
Configure a TUN/TAP device.
Write data to the tuntap device file descriptor.
Types
-type dev() :: pid().
Functions
-spec broadcast(dev(), inet:socket_address() | inet:hostname()) -> ok | {error, file:posix()}.
Configure the broadcast address for a TUN/TAP device.
Support
* Linux (IPv4 addresses only)
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> tuncer:broadcast(Dev, "10.1.1.3").
ok
6: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 500
link/none
inet 10.1.1.1/32 brd 10.1.1.3 scope global tun0
valid_lft forever preferred_lft forever
inet6 fe80::9d37:9d1:efba:75a1/64 scope link stable-privacy
valid_lft forever preferred_lft forever
Change the controlling process of the TUN/TAP device.
Change the process owning the socket. Allows another process to send and receive packets from the TUN/TAP device.-spec create() -> gen_server:start_ret().
Create the tap0 device.
Examples
1> tuncer:create().
{ok,<0.175.0>}
$ ip link show tap0
2: tap0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
link/ether 32:a9:6a:5b:48:c3 brd ff:ff:ff:ff:ff:ff
-spec create(Ifname :: binary() | string()) -> gen_server:start_ret().
Create a named tap device.
Examples
1> tuncer:create("foo").
{ok,<0.175.0>}
$ ip link show foo
3: foo: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
link/ether 9e:f1:90:e2:2c:66 brd ff:ff:ff:ff:ff:ff
-spec create(Ifname :: binary() | string(), Opt :: proplists:proplist()) -> gen_server:start_ret().
Create a tuntap device.
Device is the TUN/TAP device name. If a device name is empty, the TUN/TAP driver will choose one (for tap devices, starting from tap0
; for tun devices, beginning from tun0
).
When the device is in {active, true}
mode, data is sent as messages:
{tuntap, PID, binary()}
If an error is encountered:
{tuntap_error, PID, posix()}
Retrieving data from devices in {active, false}
mode can be done using recv/1,2 or read/1,2.
Options contains a list of flags.
tun: create a tun interface
tap: create a tap interface
no_pi: do not prepend the data with a 4 byte header describing the physical interface
The options default to [tap, no_pi, {active, false}]
.
Examples
1> tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.181.0>}
$ ip link show tun0
4: tun0: <POINTOPOINT,MULTICAST,NOARP> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 500
link/none
-spec destroy(dev()) -> ok.
Remove the TUN/TAP device.
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.175.0>}
2> tuncer:destroy(Dev).
ok
-spec devname(dev()) -> binary().
Get the TUN/TAP device name.
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.175.0>}
2> tuncer:devname(Dev).
<<"tap0">>
-spec down(dev()) -> ok | {error, file:posix()}.
Unconfigure a TUN/TAP device.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> tuncer:down(Dev).
ok
-spec dstaddr(dev(), inet:socket_address() | inet:hostname()) -> ok | {error, file:posix()}.
Configure the remote address for a TUN/TAP device in point-to-point mode.
Support
* Linux (IPv4 addresses only)
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.197.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> tuncer:dstaddr(Dev, "10.1.1.2").
ok
$ ip a show tun0
4: tun0: <POINTOPOINT,MULTICAST,NOARP,NOTRAILERS,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 500
link/none
inet 10.1.1.1 peer 10.1.1.2/32 scope global tun0
valid_lft forever preferred_lft forever
inet6 fe80::e0f7:c90f:e2d8:91e8/64 scope link stable-privacy
valid_lft forever preferred_lft forever
-spec flags(dev()) -> integer().
Returns an integer holding the interface creation flags.
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.175.0>}
2> tuncer:flags(Dev).
[tap,no_pi]
-spec getfd(dev()) -> integer().
Get TUN/TAP device file descriptor.
Get the file descriptor associated with the process. Use getfd/1 with read/1,2 and write/2 to interact directly with the tuntap device (bypassing the gen_server).
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.175.0>}
2> tuncer:getfd(Dev).
22
-spec group(dev(), integer()) -> ok | {error, file:posix()}.
Set the GID owning the interface.
Support
* Linux
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.201.0>}
2> tuncer:group(Dev, 1000).
ok
-spec header(binary()) -> {tun_pi, tunctl:uint16_t(), tunctl:uint16_t()} | {error, file:posix()}.
Parse TUN/TAP packet header.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> {ok, Bin} = tuncer:recv(Dev).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,247,188,77,
238,78,171,184,107,255,2,0,...>>}
4> tuncer:header(Bin).
{tun_pi,96,0,
<<0,8,58,255,254,128,0,0,0,0,0,0,247,188,77,238,78,171,
184,107,255,2,0,0,0,...>>}
-spec mtu(dev()) -> integer().
Get the MTU (maximum transmission unit) for the TUN/TAP device.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> tuncer:mtu(Dev).
1500
-spec mtu(dev(), integer()) -> {ok, tunctl:fd(), binary()} | {error, file:posix()}.
-spec owner(dev(), integer()) -> ok | {error, file:posix()}.
Set the UID owning the interface.
Support
* Linux
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.201.0>}
2> tuncer:owner(Dev, 1000).
ok
-spec persist(dev(), boolean()) -> ok | {error, file:posix()}.
Set the interface to exist after the Erlang process exits.
Support
* Linux
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.201.0>}
2> tuncer:persist(Dev, true).
ok
-spec read(tunctl:fd()) -> {ok, binary()} | {error, file:posix()}.
Read data from the tuntap device file descriptor.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.197.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> FD = tuncer:getfd(Dev).
22
4> tuncer:read(FD).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,36,14,228,
30,140,106,15,112,255,2,0,...>>}
-spec read(tunctl:fd(), integer()) -> {ok, binary()} | {error, file:posix()}.
Read up to the specified number of bytes from the tuntap device file descriptor.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.197.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> FD = tuncer:getfd(Dev).
22
4> tuncer:read(FD, 16).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0>>}
Read data to the tuntap device.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> {ok, D} = tuncer:recv(Dev).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,89,201,218,
161,25,116,199,243,255,2,0,...>>}
Read up to the specified number of bytes from the tuntap device.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> tuncer:recv(Dev, 16).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0>>}
Write data to the tuntap device.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> {ok, Data} = tuncer:recv(Dev).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,89,201,218,
161,25,116,199,243,255,2,0,...>>}
4> tuncer:send(Dev, Data).
ok
Set TUN/TAP device option.
setopt/2 currently supports toggling active
mode for performing flow control.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> tuncer:setopt(Dev, {active, true}).
ok
4> tuncer:setopt(Dev, {active, false}).
ok
5> flush().
Shell got {tuntap,<0.205.0>,
<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,44,191,1,21,92,
149,243,132,255,2,0,0,0,0,0,0,0,0,0,0,0,0,0,2,133,0,255,
72,0,0,0,0>>}
Shell got {tuntap,<0.205.0>,
<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,44,191,1,21,92,
149,243,132,255,2,0,0,0,0,0,0,0,0,0,0,0,0,0,2,133,0,255,
72,0,0,0,0>>}
Shell got {tuntap,<0.205.0>,
<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0,44,191,1,21,92,
149,243,132,255,2,0,0,0,0,0,0,0,0,0,0,0,0,0,2,133,0,255,
72,0,0,0,0>>}
ok
-spec up(dev(), inet:socket_address() | inet:hostname()) -> ok | {error, file:posix()}.
Configure a TUN/TAP device using the default netmask and broadcast for the network.
Examples
1> {ok, Dev} = tuncer:create().
{ok,<0.201.0>}
2> tuncer:up(Dev, "127.8.8.8").
ok
# ip a show dev tap0
7: tap0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000
link/ether 6e:fb:29:46:df:00 brd ff:ff:ff:ff:ff:ff
inet 127.8.8.8/32 brd 127.255.255.255 scope host tap0
valid_lft forever preferred_lft forever
inet6 fe80::6cfb:29ff:fe46:df00/64 scope link
valid_lft forever preferred_lft forever
-spec up(dev(), inet:socket_address() | inet:hostname(), 0..32) -> ok | {error, file:posix()}.
Configure a TUN/TAP device.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.197.0>}
2> tuncer:up(Dev, "10.1.1.1", 24).
ok
16: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 500
link/none
inet 10.1.1.1/24 scope global tun0
valid_lft forever preferred_lft forever
inet6 fe80::5472:aa66:7afa:64b9/64 scope link stable-privacy
valid_lft forever preferred_lft forever
-spec write(tunctl:fd(), binary()) -> ok | {error, file:posix()}.
Write data to the tuntap device file descriptor.
Examples
1> {ok, Dev} = tuncer:create("tun0", [tun, no_pi, {active, false}]).
{ok,<0.205.0>}
2> tuncer:up(Dev, "10.1.1.1").
ok
3> FD = tuncer:getfd(Dev).
22
4> {ok, Data} = tuncer:read(FD, 16).
{ok,<<96,0,0,0,0,8,58,255,254,128,0,0,0,0,0,0>>}
6> tuncer:write(FD, Data).
ok