Gitiles
Code Review Sign In
gerrit-public.fairphone.software / external / ebtables / refs/heads/int/n/fp2 / . / docs / ebtables-faq.html
blob: 80e1a970b04eee8347971b876881728167fb922d [file] [log] [blame]
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<HTML>
3 <HEAD>
4 <TITLE>Ebtables (Ethernet Bridge Tables) Frequently Asked
5 Questions</TITLE>
6 <LINK rel="SHORTCUT ICON" href="">
7 <LINK rel="STYLESHEET" type="text/css" href="ebtables.css">
8 <META name="description" content=
9 "Ethernet Bridge Tables Frequently Asked Questions">
Bart De Schuymerf3e01472003-11-30 18:29:49 +0000[diff] [blame]10 <META name="author" content="Bart De Schuymer and Nick Fedchik">
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]11 <META name="keywords" content=
12 "Linux, netfilter, firewall, bridge, brouter, ebtables, iptables">
13 <META name="keywords" content=
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]14 "FAQ, kernel, ebtables, br-nf, br-nf-bds, ethernet, nat, chains, rules, tables">
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]15 </HEAD>
16 <BODY>
17 <DIV class="banner" align="center">
18 <H1>Ebtables (Ethernet Bridge Tables) Frequently Asked Questions</H1>
19 </DIV>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]20 <A name="top"></A>
21 <P>Last modified: November 09, 2003</P>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]22 <H2>Questions</H2>
23 <OL>
24 <LI><A href="#quiz0">Intro</A></LI>
25 <LI><A href="#quiz1">Installation</A></LI>
26 <LI><A href="#quiz2">Usage</A></LI>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]27 <LI><A href="#quiz3">Problems</A></LI>
28 <LI><A href="#quiz4">Other</A></LI>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]29 </OL>
30 <H2>Answers</H2>
31 <OL>
32 <LI>
33 <B><A name="quiz0">Intro</A></B>
34 <DL>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]35 <DT>What is ebtables?</DT>
36 <DD>The ebtables project is the Linux 2.5.x (and above) Link Layer
37 firewalling subsystem, a patch for 2.4.x is maintained too.
38 It delivers for Linux the functionality of
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]39 Ethernet frame filtering, all kinds of frame NAT (Network Address
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]40 Translation) and frame matching. The ebtables infrastructure is
41 a part of the standard Linux 2.5.x (and above) kernels.</DD>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]42 <DT>Why would I use it?</DT>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]43 <DD>To filter frames by MAC-address or frame type at
44 Link Layer inside your Linux-based Ethernet bridge, to do
45 some basic filtering of certain protocol headers, to
46 make a Linux brouter.</DD>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]47 </DL>
48 <A class=navbar href="#top">[Back to the top]</A>
49 <HR>
50 </LI>
51 <LI>
52 <B><A name="quiz1">Installation</A></B>
53 <DL>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]54 <DT>How do I install the kernel part?</DT>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]55 <DD>First step is to decide what kernel version to use. If you
56 want to use a 2.5.x (or above) kernel, then just use the latest
57 and greatest kernel version. You won't have to patch the kernel.
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]58 </DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]59 <DD>If you want to use a 2.4.x kernel, then go to
60 <A href="http://sourceforge.net/projects/ebtables/">Ethernet bridge
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]61 tables</A> and download the latest patch from the <B>2.4-ebtables-brnf</B>
62 package. Apply the patch as follows (substitute "linux" for the appropriate directory):
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]63 </DD>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]64<PRE>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]65# cp ebtables-brnf-3_vs_2.4.22.diff.gz /usr/src/linux
fnm31fadacb2003-02-18 16:49:43 +0000[diff] [blame]66# cd /usr/src/linux
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]67# gunzip ebtables-brnf-3_vs_2.4.22.diff.gz
68# patch -p1 &lt; ebtables-brnf-3_vs_2.4.22.diff
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]69</PRE>
70 </DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]71 <DT>What is the "ebtables" package and how do I install it?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]72 <DD>
73 The <B>ebtables</B> package contains the ebtables userspace
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]74 tool. This ebtables binary is used to make filtering
75 rules for the Linux-based Ethernet bridge. All traffic entering
76 or leaving on a bridge port will be seen by the rules. The ebtables usage is very
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]77 similar to the iptables, so it should not be so hard. Of
78 course, there is a man page supplied. Just gunzip and untar the
79 package and read the INSTALL file.<BR>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]80
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]81<PRE>
82# make
83</PRE>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]84 Copy the ebtables binary, man page and protocol file to the correct
85 directory (see the INSTALL file for options):
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]86<PRE>
87# make install
88</PRE>
89 </DD>
90 </DL>
91 <A class=navbar href="#top">[Back to the top]</A>
92 <HR>
93 </LI>
94 <LI>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]95 <B><A name="quiz2">Usage</A></B>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]96 <DL>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]97 <DT>Can I filter on ARP packets in the Linux bridge box using
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]98 ebtables?</DT>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]99 <DD>Yes, it's possible to filter on the ARP header, using ebtables.
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]100 See the <A href="http://ebtables.sourceforge.net/ebtables-man.html">ebtables manual page</A> for
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]101 details.</DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]102 <DT>Can I use ebtables with iptables? Are there any problems to
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]103 use it together? How exactly is the packet/frame traversing order for ebtables/iptables?</DT>
104 <DD>Yes, it's possible to use ebtables together with iptables, there are no incompatibility issues. Detailed
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]105 info about ebtables/iptables interaction is explained at the
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]106 <A href="http://ebtables.sourceforge.net/br_fw_ia/br_fw_ia.html">
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]107 "ebtables/iptables interaction on a Linux-based bridge"</A> page.</DD>
108 <DT>Does ebtables keep count statistics?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]109 <DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]110 Yes, it's possible to view the match and byte count for every rule, using
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]111<PRE>
112# ebtables -L --Lc
113</PRE>
114 </DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]115 <DT>When using the option --Lc, what does the pcnt value represent?</DT>
116 <DD>
117 Normally, pcnt will represent the number of frames that matched this rule. However,
118 if IP connection tracking is enabled, all fragmented IP packets will first be
119 defragmented. Therefore, the pcnt value for IP packets will then represent the
120 number of matched IP packets, not the number of matched frames containing IP fragments.
121 In the BROUTING chain however, pcnt will always represent the number of matched frames, since
122 the IP connection tracking is not done before this chain is traversed.
123 </DD>
124 <DT>What is this brouter stuff and when is it useful?</DT>
125 <DD>
126 The ebtables BROUTING chain gets traversed very early, namely right after a frame
127 is received on a forwarding bridge port. If a rule's decision is to route the frame,
128 the input device will remain the physical device of the bridge port and the bridge
129 code won't touch the frame. The frame will be processed by the network stack. If the
130 decision is to bridge the frame (the default behaviour), then the input device will
131 become the bridge device on which the port is enslaved and the bridge code will decide
132 what to do with the frame.</DD>
133 <DT>So, what's the difference between the ebtables BROUTING and PREROUTING chains?</DT>
134 <DD>The ebtables PREROUTING chain is only traversed when the bridge code is deciding what
135 to do with the frame. So, if a BROUTING chain rule decided the frame should be routed, then
136 the ebtables PREROUTING chain won't see it. See the
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]137 <A href="http://ebtables.sourceforge.net/br_fw_ia/br_fw_ia.html">
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]138 "ebtables/iptables interaction on a Linux-based bridge"</A> page for the details.</DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]139 <DT>I'm using a 2.5.x or higher kernel and my iptables rules won't match on the bridge port
140 devices, what's wrong?</DT>
141 <DD>
142 There is one difference between the br-nf behaviour in the 2.5.x or higher kernels and
143 the 2.4.x patch. To get the br-nf code accepted into the standard 2.5.x kernels, we had to
144 remove the code that automatically checked on the bridge port in the iptables port checking
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]145 code (options -i and -o). Instead there is now an iptables match module, called 'physdev', that
146 can be used to filter on the bridge ports. This match module has some extra options and
147 is in the standard 2.6 kernels, the corresponding userspace module is available in the
148 iptables userspace tool. See the iptables man pages and
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]149<PRE>
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]150# iptables -m physdev -h
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]151</PRE>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]152 The kernel module has to be compiled in the kernel, the option 'physdev match support' will
153 appear under the 'IP netfilter configuration' when the bridge is already enabled in the
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]154 configuration.
155</DD>
156 <DT>I want to use the most recent ebtables code, even if it's not yet in an official release.
157 How do I do this?</DT>
158 <DD>
159 The most recent code is available at the <A href="http://sourceforge.net/projects/ebtables">
160 sourceforge ebtables</A> CVS repository. To get a copy of the repository, do the following:
161<PRE>
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]162# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ebtables login
163# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ebtables co ebtables2
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]164</PRE>
165 The current userspace code is in the ebtables2/userspace/ebtables2 directory. To compile the
166 CVS userspace tool you'll need to do the following:
167<PRE>
Bart De Schuymer6c97d522003-02-19 20:09:51 +0000[diff] [blame]168# make KERNEL_INCLUDES=/usr/src/linux/include/
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]169# make install
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]170</PRE>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]171 Obviously you'll need to use the right kernel directory.</DD>
172 <DD> Why is compiling the CVS different?
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]173 Because the kernel include files are not maintained in the userspace directory of the CVS.
174 When a new ebtables release is made, the kernel include files get copied in the tar file, so
175 the standard installation knows where to get its kernel include files.</DD>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]176 <DD>The ebtables CVS tree has its own kernel tree with ebtables related files (for 2.4 and 2.6).
177 The CVS directory (base_dir)/ebtables2/kernel/linux2.5/include/ can be used for compiling the userspace tool.
178 </DD>
179 <DD>New ebtables modules might not yet be in the standard kernel. The CVS directory
180 (base_dir)/ebtables2/kernel/linux2.5/net/bridge/netfilter/ contains the not yet submitted modules. The modules
181 that are already in the standard kernel are also in this directory and they are normally in sync with the latest
182 kernel release.
183 </DD>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]184 </DL>
185 <BR>
186 <A class=navbar href="#top">[Back to the top]</A>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]187 <HR>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]188 </LI>
189 <LI>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]190 <B><A name="quiz3">Problems</A></B><BR>
191 <DL>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]192 <DT>My bridging box seems to drop all IP packets, which is not what I want and I'm sure my
193 ebtables rules don't drop them.</DT>
194 <DD>Your iptables rules are probably dropping them then. By default, on a Linux bridging firewall all
195 bridged IP packets are seen by iptables, so you should take that into account.</DD>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]196 <DT>This stuff isn't working on my 64-bit machine with a 32-bit userspace (like the Sparc64)</DT>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]197 <DD>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.
198 In case it doesn't, please notify the ebtables-devel mailing list. Making it work on a different 64/32 processor
199 should be easy, but we'll wait for someone to come along who asks for this and who can consequently test the fix.</DD>
200 <DT>I'm getting a message that looks like: ``br_netfilter: Argh!! : bad mac.raw pointer''</DT>
201 <DD>We sometimes get reports about this message occurring. The bridge-nf code reports this message when a
202 specific irregularity is observed, in technical terms: the mac.raw pointer of the sk_buff isn't set properly.
203 The most likely cause of this is the network device driver. Since this only happens for a few persons, the
204 only way to debug this is if those persons are willing to try patches. Up until now this has not been the case.<BR>
205 The easiest solution is to try a different type of network card or a different device driver.
206 </DD>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]207 <DT>I'm getting this message when doing IP DNAT: ``Performing cross-bridge DNAT requires IP
208 forwarding to be enabled''</DT>
209 <DD>First make sure IP forwarding is enabled:
210<PRE>
Bart De Schuymer38b9d6d2003-11-09 20:55:03 +0000[diff] [blame]211# echo 1 > /proc/sys/net/ipv4/ip_forward
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]212</PRE>
213 If that's the case and the message doesn't go away, make sure your routing table has all necessary
214 entries. For example, suppose we want to DNAT traffic on a bridge device that doesn't have an IP address to
215 an IP address somewhere on the Internet.
216<PRE>
217eth0 = connection to Internet
218br0 = eth1+eth2
219br0 has no IP address
220iptables -t nat -A PREROUTING -s 172.16.1.2 -d 172.16.1.4 -j DNAT --to-dest &lt;destination&gt;
221route -A -net 172.16.1.0 netmask 255.255.255.0 dev br0
222</PRE>
223 172.16.1.2 is on the eth1 side, .4 on the eth2 side, the &lt;destination&gt; is somewhere on the Internet.
224 Without the routing table entry (last line above), it is obvious that this DNAT wouldn't work (because the bridge/router
225 wouldn't know where to send 172.16.1.xx traffic). It is possible that the mentioned
226 error message gets printed on the screen or in your logs when this routing table entry is omitted.
227 </DD>
Bart De Schuymerf3e01472003-11-30 18:29:49 +0000[diff] [blame]228 <DT>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...</DT>
229 <DD>The DROP target in the BROUTING chain doesn't change the MAC destination to the bridge device, by default. You need
230 to explicitly do this by using the redirect target:
231<PRE>
232ebtables -t broute -A BROUTING -p IPv4 -j redirect --redirect-target DROP
233</PRE>
234 </DD>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]235 </DL>
236 <BR>
237 <A class=navbar href="#top">[Back to the top]</A>
238 </LI>
239 <LI>
240 <B><A name="quiz4">Other</A></B><BR>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]241 <DL>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]242 <DT>I'm not a Linux system's programmer, but I need a feature, which
243 is not (yet) implemented in ebtables. What should I do?</DT>
244 <DD>Subscribe to the <A href= "https://lists.sourceforge.net/lists/listinfo/ebtables-user">
245 ebtables users mailing list</A>. Then post a short and clean description of
246 your wanted feature to this mailing list.</DD>
247 <DT>I'm a C programmer and I want to add an ebtables feature by
248 myself. Where should I begin?</DT>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]249 <DD>Subscribe to the <A href=
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]250 "https://lists.sourceforge.net/lists/listinfo/ebtables-devel">ebtables
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]251 developers mail list</A>. Read the <A href=
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]252 "http://ebtables.sourceforge.net/ebtables-hacking/ebtables-hacking-HOWTO.html">"Ebtables Hacking HOWTO"</A> and
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]253 have a look at the already implemented modules. You will find that
254 adding a module is not very hard. Additional information is available
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]255 at the ebtables <A href="http://ebtables.sourceforge.net">
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]256 homepage</A>.</DD>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]257 </DL>
258 <BR>
259 <A class=navbar href="#top">[Back to the top]</A>
260 </LI>
261 </OL>
262 <HR>
263 </BODY>
264</HTML>