| blob | b5c4c269df9685d5c1b59d654fee74d8ff5b8f34 |
1 .\"
2 .\" $FreeBSD: src/sbin/ip6fw/ip6fw.8,v 1.3.2.12 2003/02/23 20:17:15 trhodes Exp $
3 .\" $DragonFly: src/sbin/ip6fw/ip6fw.8,v 1.7 2008/09/02 11:50:45 matthias Exp $
4 .\"
5 .\" $KAME$
6 .\"
7 .\" Copyright (C) 1998, 1999, 2000 and 2001 WIDE Project.
8 .\" All rights reserved.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the project nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .Dd September 2, 2008
35 .Dt IP6FW 8
36 .Os
37 .Sh NAME
38 .Nm ip6fw
39 .Nd controlling utility for IPv6 firewall
40 .Sh SYNOPSIS
41 .Nm
42 .Op Fl q
43 .Oo
44 .Fl p Ar preproc
45 .Oo Fl D
46 .Ar macro Ns Op = Ns Ar value
47 .Oc
48 .Op Fl U Ar macro
49 .Oc
50 .Ar pathname
51 .Nm
52 .Op Fl f | Fl q
53 flush
54 .Nm
55 .Op Fl q
56 zero
57 .Op Ar number ...
58 .Nm
59 delete
60 .Ar number ...
61 .Nm
62 .Op Fl aftN
63 list
64 .Op Ar number ...
65 .Nm
66 .Op Fl ftN
67 show
68 .Op Ar number ...
69 .Nm
70 .Op Fl q
71 add
72 .Op Ar number
73 .Ar action
74 .Op log
75 .Ar proto
76 from
77 .Ar src
78 to
79 .Ar dst
80 .Op via Ar name | ipv6no
81 .Op Ar options
82 .Sh DESCRIPTION
83 To ease configuration, rules can be put into a file which is
84 processed using
85 .Nm
86 as shown in the first synopsis line.
87 An absolute
88 .Ar pathname
89 must be used.
90 The file
91 will be read line by line and applied as arguments to the
92 .Nm
93 utility.
94 .Pp
95 Optionally, a preprocessor can be specified using
96 .Fl p Ar preproc
97 where
98 .Ar pathname
99 is to be piped through.
100 Useful preprocessors include
101 .Xr cpp 1
102 and
103 .Xr m4 1 .
104 If
105 .Ar preproc
106 doesn't start with a slash
107 .Pq Ql /
108 as its first character, the usual
109 .Ev PATH
110 name search is performed.
111 Care should be taken with this in environments where not all
112 file systems are mounted (yet) by the time
113 .Nm
114 is being run (e.g. when they are mounted over NFS).
115 Once
116 .Fl p
117 has been specified, optional
118 .Fl D
119 and
120 .Fl U
121 specifications can follow and will be passed on to the preprocessor.
122 This allows for flexible configuration files (like conditionalizing
123 them on the local hostname) and the use of macros to centralize
124 frequently required arguments like IP addresses.
125 .Pp
126 The
127 .Nm
128 code works by going through the rule-list for each packet,
129 until a match is found.
130 All rules have two associated counters, a packet count and
131 a byte count.
132 These counters are updated when a packet matches the rule.
133 .Pp
134 The rules are ordered by a
135 .Dq line-number
136 from 1 to 65534 that is used
137 to order and delete rules.
138 Rules are tried in increasing order, and the
139 first rule that matches a packet applies.
140 Multiple rules may share the same number and apply in
141 the order in which they were added.
142 .Pp
143 If a rule is added without a number, it is numbered 100 higher
144 than the previous rule.
145 If the highest defined rule number is
146 greater than 65434, new rules are appended to the last rule.
147 .Pp
148 The delete operation deletes the first rule with number
149 .Ar number ,
150 if any.
151 .Pp
152 The list command prints out the current rule set.
153 .Pp
154 The show command is equivalent to `ip6fw -a list'.
155 .Pp
156 The zero operation zeroes the counters associated with rule number
157 .Ar number .
158 .Pp
159 The flush operation removes all rules.
160 .Pp
161 Any command beginning with a
162 .Sq # ,
163 or being all blank, is ignored.
164 .Pp
165 One rule is always present:
166 .Bd -literal -offset center
167 65535 deny all from any to any
168 .Ed
169 .Pp
170 This rule is the default policy, i.e., don't allow anything at all.
171 Your job in setting up rules is to modify this policy to match your
172 needs.
173 .Pp
174 The following options are available:
175 .Bl -tag -width flag
176 .It Fl a
177 While listing, show counter values. See also
178 .Dq show
179 command.
180 .It Fl f
181 Don't ask for confirmation for commands that can cause problems if misused
182 (ie; flush).
183 .Ar Note ,
184 if there is no tty associated with the process, this is implied.
185 .It Fl q
186 While adding, zeroing or flushing, be quiet about actions (implies '-f').
187 This is useful for adjusting rules by executing multiple ip6fw commands in a
188 script (e.g. sh /etc/rc.firewall), or by processing a file of many ip6fw rules,
189 across a remote login session. If a flush is performed in normal
190 (verbose) mode, it prints a message. Because all rules are flushed, the
191 message cannot be delivered to the login session, the login session is
192 closed and the remainder of the ruleset is not processed. Access to the
193 console is required to recover.
194 .It Fl t
195 While listing, show last match timestamp.
196 .It Fl N
197 Try to resolve addresses and service names in output.
198 .El
199 .Pp
200 .Ar action :
201 .Bl -hang -offset flag -width 16n
202 .It Ar allow
203 Allow packets that match rule.
204 The search terminates.
205 Aliases are
206 .Ar pass ,
207 .Ar permit ,
208 and
209 .Ar accept .
210 .It Ar deny
211 Discard packets that match this rule.
212 The search terminates.
213 .Ar Drop
214 is an alias for
215 .Ar deny .
216 .It Ar reject
217 (Deprecated.) Discard packets that match this rule, and try to send an ICMPv6
218 host unreachable notice.
219 The search terminates.
220 .It Ar unreach code
221 Discard packets that match this rule, and try to send an ICMPv6
222 unreachable notice with code
223 .Ar code ,
224 where
225 .Ar code
226 is a number from zero to 255, or one of these aliases:
227 .Ar noroute ,
228 .Ar admin ,
229 .Ar notneighbor ,
230 .Ar addr ,
231 or
232 .Ar noport ,
233 The search terminates.
234 .It Ar reset
235 TCP packets only.
236 Discard packets that match this rule,
237 and try to send a TCP reset (RST) notice.
238 The search terminates
239 .Em ( "not working yet" ) .
240 .It Ar count
241 Update counters for all packets that match rule.
242 The search continues with the next rule.
243 .It Ar skipto number
244 Skip all subsequent rules numbered less than
245 .Ar number .
246 The search continues with the first rule numbered
247 .Ar number
248 or higher.
249 .El
250 .Pp
251 If the kernel was compiled with
252 .Dv IPV6FIREWALL_VERBOSE ,
253 then when a packet matches a rule with the
254 .Dq log
255 keyword or a clear/resetlog is performed, a message will be logged to
256 .Xr syslogd 8 ,
257 or, if that fails, to the console. If the kernel was compiled with the
258 .Dv IPV6FIREWALL_VERBOSE_LIMIT
259 option, then logging will cease after the number of packets
260 specified by the option are received for that particular
261 chain entry.
262 When this limit is reached, the limit and rule number will be logged.
263 Logging may then be re-enabled by clearing
264 the packet counter for that entry.
265 .Pp
266 The
267 .Xr syslogd 8
268 logging and the default log limit are adjustable dynamically through the
269 .Xr sysctl 8
270 interface.
271 .Pp
272 .Ar proto :
273 .Bl -hang -offset flag -width 16n
274 .It Ar ipv6
275 All packets match.
276 The alias
277 .Ar all
278 has the same effect.
279 .It Ar tcp
280 Only TCP packets match.
281 .It Ar udp
282 Only UDP packets match.
283 .It Ar ipv6-icmp
284 Only ICMPv6 packets match.
285 .It Ar <number|name>
286 Only packets for the specified protocol matches (see
287 .Pa /etc/protocols
288 for a complete list).
289 .El
290 .Pp
291 .Ar src
292 and
293 .Ar dst :
294 .Bl -hang -offset flag
295 .It Ar <address/prefixlen>
296 .Op Ar ports
297 .El
298 .Pp
299 The
300 .Em <address/prefixlen>
301 may be specified as:
302 .Bl -hang -offset flag -width 16n
303 .It Ar ipv6no
304 An ipv6number of the form
305 .Li fec0::1:2:3:4 .
306 .It Ar ipv6no/prefixlen
307 An ipv6number with a prefix length of the form
308 .Li fec0::1:2:3:4/112 .
309 .El
310 .Pp
311 The sense of the match can be inverted by preceding an address with the
312 .Dq not
313 modifier, causing all other addresses to be matched instead.
314 This
315 does not affect the selection of port numbers.
316 .Pp
317 With the TCP and UDP protocols, optional
318 .Em ports
319 may be specified as:
320 .Bl -hang -offset flag
321 .It Ns {port|port-port} Ns Op ,port Ns Op ,...
322 .El
323 .Pp
324 Service names (from
325 .Pa /etc/services )
326 may be used instead of numeric port values.
327 A range may only be specified as the first value,
328 and the length of the port list is limited to
329 .Dv IPV6_FW_MAX_PORTS
330 (as defined in
331 .In net/ip6fw/ip6_fw.h )
332 ports.
333 .Pp
334 Fragmented packets which have a non-zero offset (i.e. not the first
335 fragment) will never match a rule which has one or more port
336 specifications. See the
337 .Ar frag
338 option for details on matching fragmented packets.
339 .Pp
340 Rules can apply to packets when they are incoming, or outgoing, or both.
341 The
342 .Ar in
343 keyword indicates the rule should only match incoming packets.
344 The
345 .Ar out
346 keyword indicates the rule should only match outgoing packets.
347 .Pp
348 To match packets going through a certain interface, specify
349 the interface using
350 .Ar via :
351 .Bl -hang -offset flag -width 16n
352 .It Ar via ifX
353 Packet must be going through interface
354 .Ar ifX .
355 .It Ar via if*
356 Packet must be going through interface
357 .Ar ifX ,
358 where X is any unit number.
359 .It Ar via any
360 Packet must be going through
361 .Em some
362 interface.
363 .It Ar via ipv6no
364 Packet must be going through the interface having IPv6 address
365 .Ar ipv6no .
366 .El
367 .Pp
368 The
369 .Ar via
370 keyword causes the interface to always be checked.
371 If
372 .Ar recv
373 or
374 .Ar xmit
375 is used instead of
376 .Ar via ,
377 then the only receive or transmit interface (respectively) is checked.
378 By specifying both, it is possible to match packets based on both receive
379 and transmit interface, e.g.:
380 .Pp
381 .Dl "ip6fw add 100 deny ip from any to any out recv ed0 xmit ed1"
382 .Pp
383 The
384 .Ar recv
385 interface can be tested on either incoming or outgoing packets, while the
386 .Ar xmit
387 interface can only be tested on outgoing packets.
388 So
389 .Ar out
390 is required (and
391 .Ar in
392 invalid) whenever
393 .Ar xmit
394 is used.
395 Specifying
396 .Ar via
397 together with
398 .Ar xmit
399 or
400 .Ar recv
401 is invalid.
402 .Pp
403 A packet may not have a receive or transmit interface: packets originating
404 from the local host have no receive interface. while packets destined for
405 the local host have no transmit interface.
406 .Pp
407 Additional
408 .Ar options :
409 .Bl -hang -offset flag -width 16n
410 .It frag
411 Matches if the packet is a fragment and this is not the first fragment
412 of the datagram.
413 .Ar frag
414 may not be used in conjunction with either
415 .Ar tcpflags
416 or TCP/UDP port specifications.
417 .It in
418 Matches if this packet was on the way in.
419 .It out
420 Matches if this packet was on the way out.
421 .It ipv6options Ar spec
422 Matches if the IPv6 header contains the comma separated list of
423 options specified in
424 .Ar spec .
425 The supported IPv6 options are:
426 .Ar hopopt
427 (hop-by-hop options header),
428 .Ar route
429 (routing header),
430 .Ar frag
431 (fragment header),
432 .Ar esp
433 (encapsulating security payload),
434 .Ar ah
435 (authentication header),
436 .Ar nonxt
437 (no next header), and
438 .Ar opts
439 (destination options header).
440 The absence of a particular option may be denoted
441 with a
442 .Dq \&!
443 .Em ( "not working yet" ) .
444 .It established
445 Matches packets that have the RST or ACK bits set.
446 TCP packets only.
447 .It setup
448 Matches packets that have the SYN bit set but no ACK bit.
449 TCP packets only.
450 .It tcpflags Ar spec
451 Matches if the TCP header contains the comma separated list of
452 flags specified in
453 .Ar spec .
454 The supported TCP flags are:
455 .Ar fin ,
456 .Ar syn ,
457 .Ar rst ,
458 .Ar psh ,
459 .Ar ack ,
460 and
461 .Ar urg .
462 The absence of a particular flag may be denoted
463 with a
464 .Dq \&! .
465 A rule which contains a
466 .Ar tcpflags
467 specification can never match a fragmented packet which has
468 a non-zero offset. See the
469 .Ar frag
470 option for details on matching fragmented packets.
471 .It icmptypes Ar types
472 Matches if the ICMPv6 type is in the list
473 .Ar types .
474 The list may be specified as any combination of ranges
475 or individual types separated by commas.
476 .El
477 .Sh CHECKLIST
478 Here are some important points to consider when designing your
479 rules:
480 .Bl -bullet -offset flag
481 .It
482 Remember that you filter both packets going in and out.
483 Most connections need packets going in both directions.
484 .It
485 Remember to test very carefully.
486 It is a good idea to be near the console when doing this.
487 .It
488 Don't forget the loopback interface.
489 .El
490 .Sh FINE POINTS
491 There is one kind of packet that the firewall will always discard,
492 that is an IPv6 fragment with a fragment offset of one.
493 This is a valid packet, but it only has one use, to try to circumvent
494 firewalls.
495 .Pp
496 If you are logged in over a network, loading the KLD version of
497 .Nm
498 is probably not as straightforward as you would think
499 .Em ( "not supported" ) .
500 I recommend this command line:
501 .Bd -literal -offset center
502 kldload /boot/modules/ip6fw_mod.o && \e
503 ip6fw add 32000 allow all from any to any
504 .Ed
505 .Pp
506 Along the same lines, doing an
507 .Bd -literal -offset center
508 ip6fw flush
509 .Ed
510 .Pp
511 in similar surroundings is also a bad idea.
512 .Sh PACKET DIVERSION
513 not supported.
514 .Sh EXAMPLES
515 This command adds an entry which denies all tcp packets from
516 .Em hacker.evil.org
517 to the telnet port of
518 .Em wolf.tambov.su
519 from being forwarded by the host:
520 .Pp
521 .Dl ip6fw add deny tcp from hacker.evil.org to wolf.tambov.su 23
522 .Pp
523 This one disallows any connection from the entire hackers network to
524 my host:
525 .Pp
526 .Dl ip6fw add deny all from fec0::123:45:67:0/112 to my.host.org
527 .Pp
528 Here is a good usage of the list command to see accounting records
529 and timestamp information:
530 .Pp
531 .Dl ip6fw -at l
532 .Pp
533 or in short form without timestamps:
534 .Pp
535 .Dl ip6fw -a l
536 .Sh SEE ALSO
537 .Xr ip 4 ,
538 .Xr ipfirewall 4 ,
539 .Xr protocols 5 ,
540 .Xr services 5 ,
541 .Xr reboot 8 ,
542 .Xr sysctl 8 ,
543 .Xr syslogd 8
544 .Sh HISTORY
545 A
546 .Nm
547 utility first appeared in
548 .Fx 4.0 .
549 .Sh AUTHORS
550 .An Ugen J. S. Antsilevich ,
551 .An Poul-Henning Kamp ,
552 .An Alex Nash ,
553 .An Archie Cobbs .
554 .Pp
555 .An -nosplit
556 API based upon code written by
557 .An Daniel Boulet
558 for BSDI.
559 .Sh BUGS
560 .Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
561 .Pp
562 This program can put your computer in rather unusable state.
563 When
564 using it for the first time, work on the console of the computer, and
565 do
566 .Em NOT
567 do anything you don't understand.
568 .Pp
569 When manipulating/adding chain entries, service and protocol names are
570 not accepted.