This is the content I propose to add to the wiki stub prepared by @jon . I read the documentation and merged few sentences inspired by the official website with the text produced by both the AI models.
@jon @bonnietwin @bbitsch What do you think? Should I remove the deeper explanation of the layer two vs layer 3 (brouting) part of the text?
+++ text starts here +++
Package description
ebtables is a transparent network-traffic filtering tool for Linux-based systems functioning as bridges of two or more networks.
Primarily, ebtables operates at the Data Link Layer (Layer 2 bridging) of the OSI model, which is a standardized framework that describes how network protocols communicate and interact. At this level, ebtables primarily inspects and takes actions based on MAC addresses, which are unique identifiers assigned to each network device. While the primary function of ebtables is to filter based on the layer 2 information, it can also inspect the IP packet within the Ethernet frame payload, enabling it to perform certain Layer 3 operations.
Letās consider an Ethernet frame as an example:
|-----------------------------------------------------------------------------------|
| Ethernet Frame |
|-----------------------------------------------------------------------------------|
| Preamble | SFD | Destination MAC | Source MAC | Type | Payload | Frame Check |
| 7 bytes | 1 byte | 6 bytes | 6 bytes | 2 bytes | 46-1500 bytes | 4 bytes |
|-----------------------------------------------------------------------------------|
The āPayloadā of the Ethernet frame carries an IP packet:
|---------------------------------------------------------------------------|
| IP Packet (Ethernet Frame Payload) |
|---------------------------------------------------------------------------|
| Version | IHL | TOS | Total Length | ID | Flags | Frag Offset | TTL |
| 4 bits | 4 bits | 8 bits | 16 bits | 16 bits | 3 bits | 13 bits | 8 bits |
|---------------------------------------------------------------------------|
| Protocol | Header Checksum | Source IP Address | Destination IP Address |
| 8 bits | 16 bits | 32 bits | 32 bits |
|---------------------------------------------------------------------------|
| Options (if IHL > 5) | Padding | Data |
| Variable | Variable | Up to 65535 bytes (usually less) |
|---------------------------------------------------------------------------|
The IP packet includes both the āSource IP Addressā and āDestination IP Addressā among other information which can all be used by ebtales.
Beyond filtering, ebtables offers advanced logging to monitor network activity, the ability to modify MAC addresses in data traffic (a process known as MAC DNAT/SNAT), and ābrouterā capabilities, enabling the system to operate both as a bridge and a router.
One of the key advantages of ebtables is its ability to integrate with other Linux filtering tools including iptables, ip6tables, and arptables. This allows the realization of a comprehensive firewall that filters network traffic at multiple OSI model layers.
The ebtables and arptables tools are maintained by the same developers who contribute to the netfilter project, the same framework that facilitates network traffic filtering used by IPFire. They continue to ensure these tools are updated and effective. The original website remains primarily for documentation reference purposes (see references).
Usage
ebtables allows defining filtering rules that get applied to frames passing through a bridge interface.
As for iptables, in the Linux kernel ebtables uses tables (in this case they are three) that contain built-in chains for organizing its rules. These tables allow us to separate the functionality into different groups of rules.
- A āchainā is just a set of rules arranged in a specific order. Each rule in the chain checks if it matches a particular Ethernet frame (a unit of data sent over a network).
- If a rule matches the frame, it then uses a ātargetā, or an instruction, to determine what to do with that frame (i.e. ACCEPT, DROP, CONTINUE, RETURN).
- If a rule does not match the frame, the system moves on to the next rule in the chain, and so on, until a match is found or all rules have been checked.
For better performance and organization, users can create their own custom chains.
Example rules
# Block all frames with a source MAC of 00:11:22:33:44:55 on the input interface (replace with your actual interface)
ebtables -A INPUT -i green0 -s 00:11:22:33:44:55 -j DROP
# Allow only VLAN 100 on the bridge interface (replace with your actual bridge interface)
ebtables -A FORWARD -i br0 --vlan-id 100 -j ACCEPT
ebtables -A FORWARD -i br0 -j DROP
## Limit ARP broadcasts on the internal (GREEN) interface, only allowing ARP requests and replies,
## and dropping all other types of ARP packets.
ebtables -A FORWARD -i green0 -p ARP --arp-opcode Request -j ACCEPT
ebtables -A FORWARD -i green0 -p ARP --arp-opcode Reply -j ACCEPT
ebtables -A FORWARD -i green0 -p ARP -j DROP
References
Acknowledgments
This page was created with the assistance of OpenAIās ChatGPT-4, a language model developed by OpenAI, and Claude, a language model developed by Anthropic.
