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