a07d6dacfcfbe8b54489ee3a1875ab295f8b1ecd
[dragonfly.git] / share / man / man7 / firewall.7
1 .\" Copyright (c) 2001 Matthew Dillon.  Terms and conditions are those of
2 .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in
3 .\" the source tree.
4 .\"
5 .\" $FreeBSD: src/share/man/man7/firewall.7,v 1.1.2.8 2003/04/29 07:57:22 brueffer Exp $
6 .\" $DragonFly: src/share/man/man7/firewall.7,v 1.9 2007/02/19 11:10:11 swildner Exp $
7 .\"
8 .Dd May 26, 2001
9 .Dt FIREWALL 7
10 .Os
11 .Sh NAME
12 .Nm firewall
13 .Nd simple firewalls under
14 .Dx
15 .Sh FIREWALL BASICS
16 A Firewall is most commonly used to protect an internal network
17 from an outside network by preventing the outside network from
18 making arbitrary connections into the internal network.  Firewalls
19 are also used to prevent outside entities from spoofing internal
20 IP addresses and to isolate services such as NFS or SMBFS (Windows
21 file sharing) within LAN segments.
22 .Pp
23 The
24 .Dx
25 firewalling system also has the capability to limit bandwidth using
26 .Xr dummynet 4 .
27 This feature can be useful when you need to guarantee a certain
28 amount of bandwidth for a critical purpose.  For example, if you
29 are doing video conferencing over the Internet via your
30 office T1 (1.5 MBits/s), you may wish to bandwidth-limit all other
31 T1 traffic to 1 MBit/s in order to reserve at least 0.5 MBits
32 for your video conferencing connections.  Similarly if you are
33 running a popular web or ftp site from a colocation facility
34 you might want to limit bandwidth to prevent excessive bandwidth
35 charges from your provider.
36 .Pp
37 Finally,
38 .Dx
39 firewalls may be used to divert packets or change the next-hop
40 address for packets to help route them to the correct destination.
41 Packet diversion is most often used to support NAT (network
42 address translation), which allows an internal network using
43 a private IP space to make connections to the outside for browsing
44 or other purposes.
45 .Pp
46 Constructing a firewall may appear to be trivial, but most people
47 get them wrong.  The most common mistake is to create an exclusive
48 firewall rather than an inclusive firewall.  An exclusive firewall
49 allows all packets through except for those matching a set of rules.
50 An inclusive firewall allows only packets matching the rulset
51 through.  Inclusive firewalls are much, much safer then exclusive
52 firewalls but a tad more difficult to build properly.  The
53 second most common mistake is to blackhole everything except the
54 particular port you want to let through.  TCP/IP needs to be able
55 to get certain types of ICMP errors to function properly - for
56 example, to implement MTU discovery.  Also, a number of common
57 system daemons make reverse connections to the
58 .Sy auth
59 service in an attempt to authenticate the user making a connection.
60 Auth is rather dangerous but the proper implementation is to return
61 a TCP reset for the connection attempt rather than simply blackholing
62 the packet.  We cover these and other quirks involved with constructing
63 a firewall in the sample firewall section below.
64 .Sh IPFW KERNEL CONFIGURATION
65 You do not need to create a customer kernel to use the IP firewalling features.
66 If you enable firewalling in your
67 .Em /etc/rc.conf
68 (see below), the ipfw kernel module will be loaded automatically.  However,
69 if you are paranoid you can compile IPFW directly into the
70 .Dx
71 kernel by using the
72 .Sy IPFIREWALL
73 option set.  If compiled in the kernel defaults its firewall to deny all
74 packets by default, which means that if you do not load in
75 a permissive ruleset via
76 .Em /etc/rc.conf ,
77 rebooting into your new kernel will take the network offline
78 and will prevent you from being able to access it if you
79 are not sitting at the console.  It is also quite common to
80 update a kernel to a new release and reboot before updating
81 the binaries.  This can result in an incompatibility between
82 the
83 .Xr ipfw 8
84 program and the kernel which prevents it from running in the
85 boot sequence, also resulting in an inaccessible machine.
86 Because of these problems the
87 .Sy IPFIREWALL_DEFAULT_TO_ACCEPT
88 kernel option is also available which changes the default firewall
89 to pass through all packets.  Note, however, that using this option
90 may open a small window of opportunity during booting where your
91 firewall passes all packets.  Still, it's a good option to use
92 while getting up to speed with
93 .Dx
94 firewalling.  Get rid of it once you understand how it all works
95 to close the loophole, though.  There is a third option called
96 .Sy IPDIVERT
97 which allows you to use the firewall to divert packets to a user program
98 and is necessary if you wish to use
99 .Xr natd 8
100 to give private internal networks access to the outside world.
101 If you want to be able to limit the bandwidth used by certain types of
102 traffic, the
103 .Sy DUMMYNET
104 option must be used to enable
105 .Em ipfw pipe
106 rules.
107 .Sh SAMPLE IPFW-BASED FIREWALL
108 Here is an example ipfw-based firewall taken from a machine with three
109 interface cards.  fxp0 is connected to the 'exposed' LAN.  Machines
110 on this LAN are dual-homed with both internal 10. IP addresses and
111 Internet-routed IP addresses.  In our example, 192.100.5.x represents
112 the Internet-routed IP block while 10.x.x.x represents the internal
113 networks.  While it isn't relevant to the example, 10.0.1.x is
114 assigned as the internal address block for the LAN on fxp0, 10.0.2.x
115 for the LAN on fxp1, and 10.0.3.x for the LAN on fxp2.
116 .Pp
117 In this example we want to isolate all three LANs from the Internet
118 as well as isolate them from each other, and we want to give all
119 internal addresses access to the Internet through a NAT gateway running
120 on this machine.  To make the NAT gateway work, the firewall machine
121 is given two Internet-exposed addresses on fxp0 in addition to an
122 internal 10. address on fxp0: one exposed address (not shown)
123 represents the machine's official address, and the second exposed
124 address (192.100.5.5 in our example) represents the NAT gateway
125 rendezvous IP.  We make the example more complex by giving the machines
126 on the exposed LAN internal 10.0.0.x addresses as well as exposed
127 addresses.  The idea here is that you can bind internal services
128 to internal addresses even on exposed machines and still protect
129 those services from the Internet.  The only services you run on
130 exposed IP addresses would be the ones you wish to expose to the
131 Internet.
132 .Pp
133 It is important to note that the 10.0.0.x network in our example
134 is not protected by our firewall.  You must make sure that your
135 Internet router protects this network from outside spoofing.
136 Also, in our example, we pretty much give the exposed hosts free
137 reign on our internal network when operating services through
138 internal IP addresses (10.0.0.x).   This is somewhat of security
139 risk... what if an exposed host is compromised?  To remove the
140 risk and force everything coming in via LAN0 to go through
141 the firewall, remove rules 01010 and 01011.
142 .Pp
143 Finally, note that the use of internal addresses represents a
144 big piece of our firewall protection mechanism.  With proper
145 spoofing safeguards in place, nothing outside can directly
146 access an internal (LAN1 or LAN2) host.
147 .Bd -literal
148 # /etc/rc.conf
149 #
150 firewall_enable="YES"
151 firewall_type="/etc/ipfw.conf"
152
153 # temporary port binding range let
154 # through the firewall.
155 #
156 # NOTE: heavily loaded services running through the firewall may require
157 # a larger port range for local-size binding.  4000-10000 or 4000-30000
158 # might be a better choice.
159 ip_portrange_first=4000
160 ip_portrange_last=5000
161 \&...
162 .Ed
163 .Pp
164 .Bd -literal
165 # /etc/ipfw.conf
166 #
167 # FIREWALL: the firewall machine / nat gateway
168 # LAN0      10.0.0.X and 192.100.5.X (dual homed)
169 # LAN1      10.0.1.X
170 # LAN2      10.0.2.X
171 # sw:       ethernet switch (unmanaged)
172 #
173 # 192.100.5.x represents IP addresses exposed to the Internet
174 # (i.e. Internet routeable).  10.x.x.x represent internal IPs
175 # (not exposed)
176 #
177 #   [LAN1]
178 #      ^
179 #      |
180 #   FIREWALL -->[LAN2]
181 #      |
182 #   [LAN0]
183 #      |
184 #      +--> exposed host A
185 #      +--> exposed host B
186 #      +--> exposed host C
187 #      |
188 #   INTERNET (secondary firewall)
189 #    ROUTER
190 #      |
191 #    [Internet]
192 #
193 # NOT SHOWN:  The INTERNET ROUTER must contain rules to disallow
194 # all packets with source IP addresses in the 10. block in order
195 # to protect the dual-homed 10.0.0.x block.  Exposed hosts are
196 # not otherwise protected in this example - they should only bind
197 # exposed services to exposed IPs but can safely bind internal
198 # services to internal IPs.
199 #
200 # The NAT gateway works by taking packets sent from internal
201 # IP addresses to external IP addresses and routing them to natd, which
202 # is listening on port 8668.   This is handled by rule 00300.  Data coming
203 # back to natd from the outside world must also be routed to natd using
204 # rule 00301.  To make the example interesting, we note that we do
205 # NOT have to run internal requests to exposed hosts through natd
206 # (rule 00290) because those exposed hosts know about our
207 # 10. network.  This can reduce the load on natd.  Also note that we
208 # of course do not have to route internal<->internal traffic through
209 # natd since those hosts know how to route our 10. internal network.
210 # The natd command we run from /etc/rc.local is shown below.  See
211 # also the in-kernel version of natd, ipnat.
212 #
213 #       natd -s -u -a 208.161.114.67
214 #
215 #
216 add 00290 skipto 1000 ip from 10.0.0.0/8 to 192.100.5.0/24
217 add 00300 divert 8668 ip from 10.0.0.0/8 to not 10.0.0.0/8
218 add 00301 divert 8668 ip from not 10.0.0.0/8 to 192.100.5.5
219
220 # Short cut the rules to avoid running high bandwidths through
221 # the entire rule set.  Allow established tcp connections through,
222 # and shortcut all outgoing packets under the assumption that
223 # we need only firewall incoming packets.
224 #
225 # Allowing established tcp connections through creates a small
226 # hole but may be necessary to avoid overloading your firewall.
227 # If you are worried, you can move the rule to after the spoof
228 # checks.
229 #
230 add 01000 allow tcp from any to any established
231 add 01001 allow all from any to any out via fxp0
232 add 01001 allow all from any to any out via fxp1
233 add 01001 allow all from any to any out via fxp2
234
235 # Spoof protection.  This depends on how well you trust your
236 # internal networks.  Packets received via fxp1 MUST come from
237 # 10.0.1.x.  Packets received via fxp2 MUST come from 10.0.2.x.
238 # Packets received via fxp0 cannot come from the LAN1 or LAN2
239 # blocks.  We can't protect 10.0.0.x here, the Internet router
240 # must do that for us.
241 #
242 add 01500 deny all from not 10.0.1.0/24 in via fxp1
243 add 01500 deny all from not 10.0.2.0/24 in via fxp2
244 add 01501 deny all from 10.0.1.0/24 in via fxp0
245 add 01501 deny all from 10.0.2.0/24 in via fxp0
246
247 # In this example rule set there are no restrictions between
248 # internal hosts, even those on the exposed LAN (as long as
249 # they use an internal IP address).  This represents a
250 # potential security hole (what if an exposed host is
251 # compromised?).  If you want full restrictions to apply
252 # between the three LANs, firewalling them off from each
253 # other for added security, remove these two rules.
254 #
255 # If you want to isolate LAN1 and LAN2, but still want
256 # to give exposed hosts free reign with each other, get
257 # rid of rule 01010 and keep rule 01011.
258 #
259 # (commented out, uncomment for less restrictive firewall)
260 #add 01010 allow all from 10.0.0.0/8 to 10.0.0.0/8
261 #add 01011 allow all from 192.100.5.0/24 to 192.100.5.0/24
262 #
263
264 # SPECIFIC SERVICES ALLOWED FROM SPECIFIC LANS
265 #
266 # If using a more restrictive firewall, allow specific LANs
267 # access to specific services running on the firewall itself.
268 # In this case we assume LAN1 needs access to filesharing running
269 # on the firewall.  If using a less restrictive firewall
270 # (allowing rule 01010), you don't need these rules.
271 #
272 add 01012 allow tcp from 10.0.1.0/8 to 10.0.1.1 139
273 add 01012 allow udp from 10.0.1.0/8 to 10.0.1.1 137,138
274
275 # GENERAL SERVICES ALLOWED TO CROSS INTERNAL AND EXPOSED LANS
276 #
277 # We allow specific UDP services through: DNS lookups, ntalk, and ntp.
278 # Note that internal services are protected by virtue of having
279 # spoof-proof internal IP addresses (10. net), so these rules
280 # really only apply to services bound to exposed IPs.  We have
281 # to allow UDP fragments or larger fragmented UDP packets will
282 # not survive the firewall.
283 #
284 # If we want to expose high-numbered temporary service ports
285 # for things like DNS lookup responses we can use a port range,
286 # in this example 4000-65535, and we set to /etc/rc.conf variables
287 # on all exposed machines to make sure they bind temporary ports
288 # to the exposed port range (see rc.conf example above)
289 #
290 add 02000 allow udp from any to any 4000-65535,domain,ntalk,ntp
291 add 02500 allow udp from any to any frag
292
293 # Allow similar services for TCP.  Again, these only apply to
294 # services bound to exposed addresses.  NOTE: we allow 'auth'
295 # through but do not actually run an identd server on any exposed
296 # port.  This allows the machine being authed to respond with a
297 # TCP RESET.  Throwing the packet away would result in delays
298 # when connecting to remote services that do reverse ident lookups.
299 #
300 # Note that we do not allow tcp fragments through, and that we do
301 # not allow fragments in general (except for UDP fragments).  We
302 # expect the TCP mtu discovery protocol to work properly so there
303 # should be no TCP fragments.
304 #
305 add 03000 allow tcp from any to any http,https
306 add 03000 allow tcp from any to any 4000-65535,ssh,smtp,domain,ntalk
307 add 03000 allow tcp from any to any auth,pop3,ftp,ftp-data
308
309 # It is important to allow certain ICMP types through, here is a list
310 # of general ICMP types.  Note that it is important to let ICMP type 3
311 # through.
312 #
313 #       0       Echo Reply
314 #       3       Destination Unreachable (used by TCP MTU discovery, aka
315 #                                       packet-too-big)
316 #       4       Source Quench (typically not allowed)
317 #       5       Redirect (typically not allowed - can be dangerous!)
318 #       8       Echo
319 #       11      Time Exceeded
320 #       12      Parameter Problem
321 #       13      Timestamp
322 #       14      Timestamp Reply
323 #
324 # Sometimes people need to allow ICMP REDIRECT packets, which is
325 # type 5, but if you allow it make sure that your Internet router
326 # disallows it.
327
328 add 04000 allow icmp from any to any icmptypes 0,3,8,11,12,13,14
329
330 # log any remaining fragments that get through.  Might be useful,
331 # otherwise don't bother.  Have a final deny rule as a safety to
332 # guarantee that your firewall is inclusive no matter how the kernel
333 # is configured.
334 #
335 add 05000 deny log ip from any to any frag
336 add 06000 deny all from any to any
337 .Ed
338 .Sh PORT BINDING INTERNAL AND EXTERNAL SERVICES
339 We've mentioned multi-homing hosts and binding services to internal or
340 external addresses but we haven't really explained it.  When you have a
341 host with multiple IP addresses assigned to it, you can bind services run
342 on that host to specific IPs or interfaces rather than all IPs.  Take
343 the firewall machine for example:  With three interfaces
344 and two exposed IP addresses
345 on one of those interfaces, the firewall machine is known by 5 different
346 IP addresses (10.0.0.1, 10.0.1.1, 10.0.2.1, 192.100.5.5, and say
347 192.100.5.1).  If the firewall is providing file sharing services to the
348 windows LAN segment (say it is LAN1), you can use samba's 'bind interfaces'
349 directive to specifically bind it to just the LAN1 IP address.  That
350 way the file sharing services will not be made available to other LAN
351 segments.  The same goes for NFS.  If LAN2 has your UNIX engineering
352 workstations, you can tell nfsd to bind specifically to 10.0.2.1.  You
353 can specify how to bind virtually every service on the machine and you
354 can use a light
355 .Xr jail 8
356 to indirectly bind services that do not otherwise give you the option.
357 .Sh SEE ALSO
358 .Xr dummynet 4 ,
359 .Xr ipnat 5 ,
360 .Xr rc.conf 5 ,
361 .Xr smb.conf 5 [ /usr/pkgsrc/net/samba ] ,
362 .Xr samba 7 [ /usr/pkgsrc/net/samba ] ,
363 .Xr config 8 ,
364 .Xr ipfw 8 ,
365 .Xr ipnat 8 ,
366 .Xr jail 8 ,
367 .Xr natd 8 ,
368 .Xr nfsd 8
369 .Sh ADDITIONAL READING
370 .Xr ipf 5 ,
371 .Xr ipf 8 ,
372 .Xr ipfstat 8
373 .Sh HISTORY
374 The
375 .Nm
376 manual page was originally written by
377 .An Matthew Dillon
378 and first appeared
379 in
380 .Fx 4.3 ,
381 May 2001.