QUICK SETUP

$ rebar3 compile # or: make

To compile the examples:

$ make examples
# Allow your user to epcap with root privs
sudo visudo
youruser ALL = NOPASSWD: /path/to/epcap/priv/epcap
# And if requiretty is enabled, disable it by using one of these
Defaults!/path/to/epcap/priv/epcap !requiretty
Defaults:youruser !requiretty
rebar3 shell
% Start the sniffer process
sniff:start_link().
% Use your interface, or leave it out and trust in pcap
sniff:start([{interface, "eth0"}]).
% To change the filter
sniff:start([{filter, "icmp or (tcp and port 80)"},{interface, "eth0"}]).
% To stop sniffing
sniff:stop().

USAGE

epcap:start() -> {ok, pid()}
epcap:start(Args) -> {ok, pid()}
epcap:start_link() -> {ok, pid()}
epcap:start_link(Args) -> {ok, pid()}
Types Args = [Options]
Options = {chroot, string()} | {group, string()} | {interface, string()} | {promiscuous, boolean()} |
{user, string()} | {filter, string()} | {progname, string()} | {file, string()} |
{monitor, boolean()} | {cpu_affinity, string()} | {cluster_id, non_neg_integer()}} |
{inject, boolean()} | {snaplen, non_neg_integer} | {buffer, non_neg_integer()} |
{time_unit, microsecond | timestamp}
Packets are delivered as messages:
{packet, DataLinkType, Time, Length, Packet}
The DataLinkType is an integer representing the link layer,
e.g., ethernet, Linux cooked socket.
The Time can be either in microseconds or a timestamp in the same
format as erlang:now/0 depending on the value of the time_unit
option (default: timestamp):
{MegaSecs, Secs, MicroSecs}
The Length corresponds to the actual packet length on the
wire. The captured packet may have been truncated. To get the
captured packet length, use byte_size(Packet).
The Packet is a binary holding the captured data.
If the version of the pcap library supports it, the pcap buffer
size can be set to avoid dropped packets by using the 'buffer'
option. The buffer size must be larger than the snapshot
length (default: 65535) plus some overhead for the pcap data
structures. Using some multiple of the snapshot length is
suggested.
epcap:send(Ref, Packet) -> ok
Types Ref = pid()
Packet = binary()
Inject a packet on the network interface. To enable sending
packets, start_link/1 must be called with the {inject, true} option
(default: {inject, false}). When disabled, any data sent
to the epcap port is silently discarded.
Packet injection failures are treated as fatal errors, terminating
the epcap port. Partial writes are not considered to be errors
and are ignored (an error message will be printed to stderr if
the verbose option is used).

PF_RING

In case you want to compile epcap with PF_RING support,
just specify the path to the libpfring and modified libpcap libraries
via shell variable PFRING.
PFRING=/home/user/pfring make
To complete the configuration you need to set up the cluster_id option.
The value of the cluster_id option is integer and should be in range between 0 and 255.
epcap:start_link([{interface, "lo"}, {cluster_id, 2}]).
You can also specify the option cpu_affinity to set up CPU affinity for epcap port:
epcap:start_link([{interface, "lo"}, {cluster_id, 2}, {cpu_affinity, "1,3,5-7"}]).