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