Last modified: December 04, 2004

Summary

  1. Intro
  2. Installation
  3. Usage
  4. Problems
  5. Other

Q&A

  1. Intro
    What is ebtables?
    The ebtables project is the Linux 2.6 (and above) Link Layer firewalling subsystem, a patch for the latest 2.4 kernel is also maintained. It delivers for Linux the functionality of Ethernet frame filtering, MAC NAT (Network Address Translation), logging and brouting. The ebtables infrastructure is a part of the standard Linux 2.6 (and above) kernels.
    Why would I use ebtables?
    To filter frames by MAC address or frame type at Link Layer inside your Linux-based Ethernet bridge, to do some basic filtering of certain protocol headers, to make a Linux brouter, to do MAC NAT, to log traffic.
    Although {ip,ip6,arp}tables can see bridged traffic, the only way to have full access to the Ethernet header is by using ebtables. Furthermore, ebtables is essential for making a brouter.

    [Back to the top]


  2. Installation
    How do I install the kernel part?
    First step is to decide what kernel version to use. If you want to use a 2.6 (or above) kernel, then just use the latest and greatest kernel version. You won't have to patch the kernel. If you don't have a reason to still use the 2.4 kernel, then you should switch to the 2.6 kernel. The supported ebtables and bridge-nf code is the code in the 2.6 kernel, the 2.4 patch is only supplied because there is still a demand for it. All development and testing is done on the 2.6 kernel.
    If you want to use a 2.4 kernel, then go to the download section and get the latest 2.4-ebtables-brnf patch. Only the latest standard 2.4 kernel is supported, so please don't ask for a patch against an older kernel or a non-standard kernel (like a RHE kernel). For info about the configuration of the kernel, we also refer to the download section.
    What is the "ebtables" package and how do I install it?
    The ebtables package contains the ebtables userspace tool. This binary is used set up the ebtables rules in the kernel. All traffic entering or leaving on a bridge port will be seen by the rules. The ebtables usage is very similar to the iptables, so it should not be so hard to use (please read the man page and the examples section before posting a question). See the download section for more information about the installation and for obtaining the latest release or the most recent code.
    [Back to the top]
  3. Usage
    Can I filter on ARP packets in the Linux bridge box using ebtables?
    Yes, it's possible to filter on the ARP header, using ebtables. See the ebtables manual page for details (look for the arp match extension).
    Can I use ebtables with iptables? Are there any problems to use it together? How exactly is the packet/frame traversing order for ebtables/iptables?
    Yes, it's possible to use ebtables together with iptables, there are no incompatibility issues. Detailed info about ebtables/iptables interaction is explained in the "ebtables/iptables interaction on a Linux-based bridge" document.
    Does ebtables keep count statistics?
    Yes, it's possible to view the match and byte count for every rule, using
    # ebtables -L --Lc
    
    When using the option --Lc, what does the pcnt value represent?
    Normally, pcnt will represent the number of frames that matched this rule. However, if IP connection tracking is enabled, all fragmented IP packets will first be defragmented. Therefore, the pcnt value for IP packets will then represent the number of matched IP packets, not the number of matched frames containing IP fragments. In the BROUTING chain however, pcnt will always represent the number of matched frames, since the IP connection tracking is not done before this chain is traversed.
    What is this brouter stuff and when is it useful?
    The ebtables BROUTING chain gets traversed very early, namely right after a frame is received on a forwarding bridge port. If a rule's decision is to broute the frame, the input device will remain the physical device of the bridge port and the bridge code won't touch the frame. The frame will be processed by the network stack. If the decision is to bridge the frame (the default behavior), then the input device will become the bridge device on which the port is enslaved and the bridge code will decide what to do with the frame. In ebtables, we therefore define the meaning of the verb "to broute" as the action in the BROUTING chain that decides not to bridge the frame, but instead hands it to the network stack.
    A brouter is used when some packets need to be bridged, while other packets need to be routed. The to be routed packets are brouted in the brouting chain, by using the DROP target. See the examples section for more information.
    So, what's the difference between the ebtables BROUTING and PREROUTING chains?
    The ebtables PREROUTING chain is only traversed when the bridge code is deciding what to do with the frame. So, if a BROUTING chain rule decided to broute the frame, the ebtables PREROUTING chain won't see it. See the "ebtables/iptables interaction on a Linux-based bridge" document for the details.
    I want to use the most recent ebtables code, even if it's not yet in an official release. How do I do this?
    The most recent code is available in the ebtables CVS repository. For more information, see the download section.
    Why is compiling the CVS different? Because the kernel include files are not maintained in the userspace directory of the CVS. When a new ebtables release is made, the kernel include files get copied in the tar file, so the standard installation knows where to get its kernel include files.
    New ebtables modules might not yet be in the standard kernel. The CVS directory (base_dir)/ebtables2/kernel/linux2.5/net/bridge/netfilter/ contains the not yet submitted modules. The modules that are already in the standard kernel are also in this directory and they are normally in sync with the latest kernel release.

    [Back to the top]


  4. Problems
    I'm using a 2.6 or higher kernel and my iptables rules won't match on the bridge port devices, what's wrong?
    There is one difference between the bridge-nf behavior in the 2.6 or higher kernels and the 2.4 patch. To get the bridge-nf code accepted into the standard 2.6 kernels, we had to remove the code that automatically checked on the bridge port in the iptables port checking code (options -i and -o). Instead there is now an iptables match module, called physdev, that can be used to filter on the bridge ports. This match modules has some extra options and is in the standard 2.6 kernels, the corresponding userspace module is available in the iptables userspace tool. See the iptables man pages and
    # iptables -m physdev -h
    
    The kernel module has to be compiled in the kernel, the option 'physdev match support' will appear under the 'IP netfilter configuration' when the bridge is already enabled in the configuration. Note that it will not appear if the bridge code is not enabled in your configuration.
    My bridging box seems to drop all IP packets, which is not what I want and I'm sure my ebtables rules don't drop them.
    Your iptables rules are probably dropping them then. By default, on a Linux bridging firewall all bridged IP packets are seen by iptables, so you should take that into account.
    This stuff isn't working on my 64-bit machine with a 32-bit userspace (like the Sparc64)
    As from ebtables v2.0.5, ebtables-brnf-2_vs_2.4.21.diff.gz and above 2.6.0-test1, it should work on a Sparc64. In case it doesn't, please notify the ebtables-devel mailing list. Making it work on a different 64/32 processor should be easy, but we'll wait for someone to come along who asks for this and who can consequently test the fix (if one is required).
    I'm getting a message that looks like: ``br_netfilter: Argh!! : bad mac.raw pointer''
    This message should no longer appear in your logs, as the cause of the malfunction has been traced and has been fixed. Please notify the ebtables-devel mailing list if this message appears in your log.
    I'm getting this message when doing IP DNAT: ``Performing cross-bridge DNAT requires IP forwarding to be enabled''
    First make sure IP forwarding is enabled:
    # echo 1 > /proc/sys/net/ipv4/ip_forward
    
    If that's the case and the message doesn't go away, make sure your routing table has all necessary entries. For example, suppose we want to DNAT traffic on a bridge device that doesn't have an IP address to an IP address somewhere on the Internet.
    # the routing table is empty, no IP addresses are assigned to the network devices
    brctl addbr br0
    brctl addif br0 eth0
    brctl addif br0 eth1
    ifconfig br0 0.0.0.0
    route add -net 172.16.1.0 netmask 255.255.255.0 dev br0
    route add default gw 172.16.1.1 dev br0
    iptables -t nat -A PREROUTING -s 172.16.1.2 -d 172.16.1.4 -j DNAT --to-dest <destination>
    
    172.16.1.2 is on the eth1 side, 172.16.1.4 on the eth2 side, the <destination> is somewhere on the Internet. Without the 2 routing table entries, it is obvious that this DNAT wouldn't work (because the bridge/router wouldn't know where to send the traffic). When doing DNAT to a host on the same network, a route to the network is still required (the default gateway can be omitted). It is possible that the mentioned error message gets printed on the screen or in your logs when this routing table entry is omitted.
    I want to do transparant DNAT but I don't want the bridge to have an IP, is that possible?
    Yes, but your routing table must contain the right routes. See the answer to the above question.
    I'm trying to create a brouter that routes all IP traffic using the command ebtables -t broute -A BROUTING -p IPv4 -j DROP, but it's not working...
    The DROP target in the BROUTING chain doesn't change the MAC destination to the bridge device, by default. You need to explicitly do this by using the redirect target:
    ebtables -t broute -A BROUTING -p IPv4 -j redirect --redirect-target DROP
    
    It might still not work then, because ARP replies arrive on the wrong device. See "Making a brouter" in the examples section.

    [Back to the top]


  5. Other
    I'm not a Linux system's programmer, but I need a feature, which is not (yet) implemented in ebtables. What should I do?
    Subscribe to the ebtables users mailing list. Then post a short and clean description of your wanted feature to this mailing list.
    I'm a C programmer and I want to add an ebtables feature. Where should I begin?
    Subscribe to the ebtables developers mail list. Read the "Ebtables Hacking HOWTO" and have a look at the already implemented modules. You will find that adding a module is not very hard. Additional information is available at the ebtables homepage.

    [Back to the top]


Valid XHTML 1.1!