Zeek::AF_Packet
==============

This plugin provides native AF_Packet support for Zeek
(http://man7.org/linux/man-pages/man7/packet.7.html).

Upgrade to Zeek
---------------

In the context of the transition from Bro to Zeek, the plugin has been renamed. To upgrade from the Bro-version of the plugin, just remove the old version and then install the renamed one. Using the package manager the following will uninstall the old version of the plugin::

    # zkg remove bro-af_packet-plugin

For manually installed plugins, remove the corresponding plugin directory::

    # rm -rf <path_to_zeek>/lib/bro/plugins/Bro_AF_Packet/

Installation
------------

Before installing the plugin, make sure the kernel headers are installed and
your kernel supports PACKET_FANOUT [1]_ and TPACKET_V3.

Package Manager
```````````````
The plugin is available as package for the `Zeek Package Manager
<https://github.com/zeek/package-manager>`_ and can be installed using the
following command::

    zkg install zeek-af_packet-plugin

Manual Install
``````````````
The following will compile and install the AF_Packet plugin alongside Zeek,
assuming it can find the kernel headers in a standard location::

    # ./configure && make && make install

If the headers are installed somewhere non-standard, add
``--with-kernel=<kernel-header-directory>`` to the ``configure`` command.
Furthermore, ``--with-latest-kernel`` will use the latest headers available
instead of looking for the headers matching the running kernel's version. If
everything built and installed correctly, you should see this::

    # zeek -NN Zeek::AF_Packet
    Zeek::AF_Packet - Packet acquisition via AF_Packet (dynamic, version 2.1.1)
    [Packet Source] AF_PacketReader (interface prefix "af_packet"; supports live input)
    [Type] AF_Packet::FanoutMode
    [Constant] AF_Packet::buffer_size
    [Constant] AF_Packet::enable_hw_timestamping
    [Constant] AF_Packet::enable_fanout
    [Constant] AF_Packet::fanout_mode
    [Constant] AF_Packet::fanout_id

.. [1] Note that some kernel versions between 3.10 and 4.7 might exhibit a bug
   that prevents the required symmetric hashing. The script available at
   https://github.com/JustinAzoff/can-i-use-afpacket-fanout can be used to
   verify whether PACKET_FANOUT works as expected.

Usage
-----

Once installed, you can use AF_Packet interfaces/ports by prefixing them with
``af_packet::`` on the command line. For example, to use AF_Packet to monitor
interface ``eth0``::

    # zeek -i af_packet::eth0

To use AF_Packet, running Zeek without root privileges, the Zeek processes
need the CAP_NET_RAW capability. You can set it with the following command (on
each sensor, after ``zeekctl install``)::

    # setcap cap_net_raw+eip <path_to_zeek>/bin/zeek

The AF_Packet plugin automatically enables promiscuous mode on the interfaces.
As the plugin is using PACKET_ADD_MEMBERSHIP to enter the promiscuous mode
without interfering others, the PROMISC flag is not touched. To verify that the
interface entered promiscuous mode you can use ``dmesg``.

To adapt the plugin to your needs, you can set a couple of parameters like
buffer size. See scripts/init.zeek for the default values.

Usage with ``zeekctl``
---------------------

To use the AF_Packet plugin with ``zeekctl``, the ``custom`` load balance method
can be utilized. The following shows an exemplary configuration::

    [manager]
    type=manager
    host=localhost

    [proxy-1]
    type=proxy
    host=localhost

    [worker-1]
    type=worker
    host=localhost
    interface=af_packet::eth0
    lb_method=custom
    lb_procs=8
    pin_cpus=0,1,2,3,4,5,6,7
    # Optional parameters for per node configuration:
    af_packet_fanout_id=23
    af_packet_fanout_mode=AF_Packet::FANOUT_HASH
    af_packet_buffer_size=128*1024*1024

If all interfaces using ``lb_method=custom`` should be configured for
AF_Packet, the prefix can be globally definied by adding the following
line to ``zeekctl.conf``::

  lb_custom.InterfacePrefix=af_packet::

Limitations
-----------

* Even using AF_Packet's ``ETH_P_ALL``, the kernel removes VLAN tags.
  While the tags are provided spereately, there is no efficient way to
  pass them to Zeek.