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