Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 06:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

af_packet: Convert README formatting to Markdown.

Browse source
This commit is contained in:
Jan Grashoefer 2022-05-15 13:10:58 +02:00 • committed by Tim Wojtulewicz
parent 1fe008945e
commit 448e69471c
1 changed files with 0 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

121
src/iosource/af_packet/README
View file

@ -1,121 +0,0 @@
Zeek::AF_Packet
==============
This plugin provides native AF_Packet support for Zeek
(http://man7.org/linux/man-pages/man7/packet.7.html).
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 3.0.2)
[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.
Upgrade from Bro 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/
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.