Gitiles
Code Review Sign In
gerrit-public.fairphone.software / external / ebtables / 3d7626afdadbe4a8053464a0754c07405d82b38a / . / docs / ebtables-faq.html
blob: 7292bf93d1289684bb732c3c47306381d44a2810 [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">
10 <META name="author" content="Nick Fedchik">
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>
20 <A name="top"></A>
Bart De Schuymera7780cf2003-04-17 18:35:35 +0000[diff] [blame]21 <P>Last modified: April 15, 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>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]42 <DT>Why do 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 Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]54 <DT>What should I know before ebtables installation?</DT>
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.
58 Check out the submitted kernel patches, available through the
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]59 <A href="http://ebtables.sourceforge.net/sourcecode.html">
60 sourcecode</A> section of the ebtables <A href="http://ebtables.sourceforge.net">
61 homepage</A> to see if there are any pending patches.</DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]62 <DD>If you want to use a 2.4.x kernel, then go to
63 <A href="http://sourceforge.net/projects/ebtables/">Ethernet bridge
64 tables</A> and download the <B>br_nf_bds</B>, <B>ebtables_kernel</B>
65 and <B>ebtables</B> packages. Use the latest packages and use the
66 kernel version for which the kernel patches were made. The
67 <B>ebtables_kernel</B> patch has to be applied before the <B>br_nf_bds</B>
68 kernel patch.</DD>
69 <DT>What is the "ebtables_kernel" package and how do I install it?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]70 <DD>
71 The <B>ebtables_kernel</B> package contains a patch against a
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]72 Linux 2.4.x kernel. It allows filtering on the Link Layer (OSI Layer
73 2). It is well-known that iptables works on the Network Layer (OSI
74 Layer 3) and on higher layers. For a bridging firewall it is
75 important to be able to filter on the Link Layer as well.</DD>
76 <DD>Copy the patch file to the kernel source (usually it is named
77 /usr/src/linux or /usr/src/linux-2.X.YZ) and execute the following
78 (use the correct file names and directories where necessary)
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]79<PRE>
80# cp ebtables-v2.0.003_vs_2.4.20.diff.gz /usr/src/linux
fnm31fadacb2003-02-18 16:49:43 +0000[diff] [blame]81# cd /usr/src/linux
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]82# gunzip ebtables-v2.0.003_vs_2.4.20.diff.gz
83# patch -p1 &lt; ebtables-v2.0.003_vs_2.4.20.diff
84</PRE>
85 </DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]86 <DT>What is the "br-nf-bds" package and how do I install it?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]87 <DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]88 The <B>br-nf-bds</B> package contains a patch against a Linux
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]89 kernel that is already patched with the <B>ebtables_kernel</B>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]90 patch. It adds the ability of iptables usage on bridge packets to make a
91 bridging firewall. Most work on this patch was done by
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]92 Lennert Buytenhek. The bridge-nf code is automatically compiled
93 into the patched kernel if the bridge and netfilter support is
94 enabled.
95<PRE>
96# cp bridge-nf-0.0.10-against-2.4.20.diff.gz /usr/src/linux
fnm31fadacb2003-02-18 16:49:43 +0000[diff] [blame]97# cd /usr/src/linux
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]98# gunzip bridge-nf-0.0.10-against-2.4.20.diff.gz
99# patch -p1 &lt; bridge-nf-0.0.10-against-2.4.20.diff
100</PRE>
101 </DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]102 <DT>What is the "ebtables" package and how do I install it?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]103 <DD>
104 The <B>ebtables</B> package contains the ebtables userspace
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]105 tool. This ebtables binary is used to make filtering
106 rules for the Linux-based Ethernet bridge. All traffic entering
107 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]108 similar to the iptables, so it should not be so hard. Of
109 course, there is a man page supplied. Just gunzip and untar the
110 package and read the INSTALL file.<BR>
111
112<PRE>
113# make
114</PRE>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]115 Copy the ebtables binary, man page and protocol file to the correct
116 directory (see the INSTALL file for options):
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]117<PRE>
118# make install
119</PRE>
120 </DD>
121 </DL>
122 <A class=navbar href="#top">[Back to the top]</A>
123 <HR>
124 </LI>
125 <LI>
126 <B><A name="quiz2">Usage</A></B>
127 <DL>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]128 <DT>Can I filter on ARP packets in the Linux bridge box using
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]129 ebtables?</DT>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]130 <DD>Yes, it's possible to filter on the ARP header, using ebtables.
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]131 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]132 details.</DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]133 <DT>Can I use ebtables with iptables? Are there any problems to
fnm3e94ebb82003-02-18 17:53:43 +0000[diff] [blame]134 use it together? How exactly the packet/frame traversing the ebtables/iptables?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]135 <DD>Yes, it's possible to use ebtables with iptables. Detailed
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]136 info about ebtables/iptables interaction is explained at 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">
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]138 "ebtables/iptables interaction on a Linux-based bridge"</A> page.</DD>
139 <DT>Does ebtables keep count statistics?</DT>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]140 <DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]141 Yes, it's possible to view the match and byte count for every rule, using
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]142<PRE>
143# ebtables -L --Lc
144</PRE>
145 </DD>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]146 <DT>When using the option --Lc, what does the pcnt value represent?</DT>
147 <DD>
148 Normally, pcnt will represent the number of frames that matched this rule. However,
149 if IP connection tracking is enabled, all fragmented IP packets will first be
150 defragmented. Therefore, the pcnt value for IP packets will then represent the
151 number of matched IP packets, not the number of matched frames containing IP fragments.
152 In the BROUTING chain however, pcnt will always represent the number of matched frames, since
153 the IP connection tracking is not done before this chain is traversed.
154 </DD>
155 <DT>What is this brouter stuff and when is it useful?</DT>
156 <DD>
157 The ebtables BROUTING chain gets traversed very early, namely right after a frame
158 is received on a forwarding bridge port. If a rule's decision is to route the frame,
159 the input device will remain the physical device of the bridge port and the bridge
160 code won't touch the frame. The frame will be processed by the network stack. If the
161 decision is to bridge the frame (the default behaviour), then the input device will
162 become the bridge device on which the port is enslaved and the bridge code will decide
163 what to do with the frame.</DD>
164 <DT>So, what's the difference between the ebtables BROUTING and PREROUTING chains?</DT>
165 <DD>The ebtables PREROUTING chain is only traversed when the bridge code is deciding what
166 to do with the frame. So, if a BROUTING chain rule decided the frame should be routed, then
167 the ebtables PREROUTING chain won't see it. See the
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]168 <A href="http://ebtables.sourceforge.net/br_fw_ia/br_fw_ia.html">
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]169 "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]170 <DT>I'm using a 2.5.x or higher kernel and my iptables rules won't match on the bridge port
171 devices, what's wrong?</DT>
172 <DD>
173 There is one difference between the br-nf behaviour in the 2.5.x or higher kernels and
174 the 2.4.x patch. To get the br-nf code accepted into the standard 2.5.x kernels, we had to
175 remove the code that automatically checked on the bridge port in the iptables port checking
176 code (options -i and -o). Instead there is now an iptables match module that you have to use
177 to filter on the bridge ports. This kernel module is in the standard 2.5.x kernels and the
178 corresponding userspace module is available in the iptables userspace tool. See the iptables
179 man pages and
180<PRE>
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]181# iptables -m physdev -h
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]182</PRE>
183 The kernel module has to be compiled in the kernel, the option ``physdev match support'' will
184 appear under the ``IP netfilter configuration'' when the bridge is already enabled in the
185 configuration.
186</DD>
187 <DT>I want to use the most recent ebtables code, even if it's not yet in an official release.
188 How do I do this?</DT>
189 <DD>
190 The most recent code is available at the <A href="http://sourceforge.net/projects/ebtables">
191 sourceforge ebtables</A> CVS repository. To get a copy of the repository, do the following:
192<PRE>
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]193# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ebtables login
194# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ebtables co ebtables2
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]195</PRE>
196 The current userspace code is in the ebtables2/userspace/ebtables2 directory. To compile the
197 CVS userspace tool you'll need to do the following:
198<PRE>
Bart De Schuymer6c97d522003-02-19 20:09:51 +0000[diff] [blame]199# make KERNEL_INCLUDES=/usr/src/linux/include/
fnm3cd1e2e62003-02-18 16:44:07 +0000[diff] [blame]200# make install
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]201</PRE>
202 Obviously you'll need to use the right kernel directory. Why is compiling the CVS different?
203 Because the kernel include files are not maintained in the userspace directory of the CVS.
204 When a new ebtables release is made, the kernel include files get copied in the tar file, so
205 the standard installation knows where to get its kernel include files.</DD>
206 <DD>To copy the ebtables kernel 2.4.x code to a full 2.4.x kernel tree, use this script:
207<PRE>
208ebtables2/kernel/scripts/CopyRep
209</PRE>
210To copy the ebtables kernel 2.5.x code to a full 2.5.x kernel tree, use this script:
211<PRE>
212ebtables2/kernel/scripts/CopyRep2.5
213</PRE>
214 You'll need to adjust the variables $FROM and $TO in the script, for more information: read the
215 script.</DD>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]216 </DL>
217 <BR>
218 <A class=navbar href="#top">[Back to the top]</A>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]219 <HR>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]220 </LI>
221 <LI>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]222 <B><A name="quiz3">Problems</A></B><BR>
223 <DL>
Bart De Schuymera7780cf2003-04-17 18:35:35 +0000[diff] [blame]224 <DT>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.</DT>
225 <DD>Your iptables rules are probably dropping them then. On a Linux bridging firewall all bridge IP packets are seen by iptables,
226 so you should take that into account.</DD>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]227 <DT>This stuff isn't working on my 64-bit machine with a 32-bit userspace (like the Sparc64)</DT>
228 <DD>We know. It's kind of hard to fix this without access to such a machine. The problem is caused by the
229 different word length between kernel and userspace.</DD>
230 <DT>I'm getting this message when doing IP DNAT: ``Performing cross-bridge DNAT requires IP
231 forwarding to be enabled''</DT>
232 <DD>First make sure IP forwarding is enabled:
233<PRE>
234# echo '1' > /proc/sys/net/ipv4/ip_forward
235</PRE>
236 If that's the case and the message doesn't go away, make sure your routing table has all necessary
237 entries. For example, suppose we want to DNAT traffic on a bridge device that doesn't have an IP address to
238 an IP address somewhere on the Internet.
239<PRE>
240eth0 = connection to Internet
241br0 = eth1+eth2
242br0 has no IP address
243iptables -t nat -A PREROUTING -s 172.16.1.2 -d 172.16.1.4 -j DNAT --to-dest &lt;destination&gt;
244route -A -net 172.16.1.0 netmask 255.255.255.0 dev br0
245</PRE>
246 172.16.1.2 is on the eth1 side, .4 on the eth2 side, the &lt;destination&gt; is somewhere on the Internet.
247 Without the routing table entry (last line above), it is obvious that this DNAT wouldn't work (because the bridge/router
248 wouldn't know where to send 172.16.1.xx traffic). It is possible that the mentioned
249 error message gets printed on the screen or in your logs when this routing table entry is omitted.
250 </DD>
251 </DL>
252 <BR>
253 <A class=navbar href="#top">[Back to the top]</A>
254 </LI>
255 <LI>
256 <B><A name="quiz4">Other</A></B><BR>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]257 <DL>
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]258 <DT>I'm not a Linux system's programmer, but I need a feature, which
259 is not (yet) implemented in ebtables. What should I do?</DT>
260 <DD>Subscribe to the <A href= "https://lists.sourceforge.net/lists/listinfo/ebtables-user">
261 ebtables users mailing list</A>. Then post a short and clean description of
262 your wanted feature to this mailing list.</DD>
263 <DT>I'm a C programmer and I want to add an ebtables feature by
264 myself. Where should I begin?</DT>
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]265 <DD>Subscribe to the <A href=
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]266 "https://lists.sourceforge.net/lists/listinfo/ebtables-devel">ebtables
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]267 developers mail list</A>. Read the <A href=
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]268 "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]269 have a look at the already implemented modules. You will find that
270 adding a module is not very hard. Additional information is available
Bart De Schuymerb713d412003-03-03 11:42:22 +0000[diff] [blame]271 at the ebtables <A href="http://ebtables.sourceforge.net">
Bart De Schuymer9ea96e22003-02-15 13:47:40 +0000[diff] [blame]272 homepage</A>.</DD>
fnm381d84b62003-02-08 15:08:34 +0000[diff] [blame]273 </DL>
274 <BR>
275 <A class=navbar href="#top">[Back to the top]</A>
276 </LI>
277 </OL>
278 <HR>
279 </BODY>
280</HTML>