From 448e69471c34ad3a48dbe22c2771c3cfdcca2aa6 Mon Sep 17 00:00:00 2001 From: Jan Grashoefer Date: Sun, 15 May 2022 13:10:58 +0200 Subject: [PATCH] af_packet: Convert README formatting to Markdown. --- src/iosource/af_packet/README | 121 ---------------------------------- 1 file changed, 121 deletions(-) delete mode 100644 src/iosource/af_packet/README diff --git a/src/iosource/af_packet/README b/src/iosource/af_packet/README deleted file mode 100644 index c9871be9d0..0000000000 --- a/src/iosource/af_packet/README +++ /dev/null @@ -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 -`_ 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=`` 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 /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 /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.